System Design (HLD)API Gateway in Microservices

API Gateway in Microservices

LevelAdvanced

Duration90 mins

TopicAPI Gateway in Microservices

3 / 5

Authentication Aggregation

The Identity Checkpoint of Your Distributed System

In a microservices architecture with dozens of services, who verifies that requests come from legitimate users? If each service independently validates tokens, fetches user details, and enforces authentication policies, you've created a distributed nightmare of duplicated logic, inconsistent behavior, and performance overhead.

Authentication Aggregation is the pattern where the API Gateway becomes the single point of identity verification. Every request is authenticated once, at the edge, and backend services receive pre-verified identity context. This transforms authentication from a distributed problem into a centralized, manageable concern.

This page provides a comprehensive exploration of authentication aggregation—strategies, protocols, token handling, identity propagation, and the architectural decisions that enable secure, scalable authentication in microservices.

What You Will Learn

By the end of this page, you will understand how to design authentication flows through API Gateways, implement various authentication mechanisms (API keys, OAuth2, JWT, mTLS), propagate identity to services, and avoid common security pitfalls. You'll be equipped to build authentication systems that are both secure and performant.

The Case for Centralized Authentication

Before diving into implementation, let's understand why authentication aggregation is essential in microservices architectures.

The Distributed Authentication Problem:

Without a gateway, each service must:

Parse and validate authentication credentials
Fetch signing keys or certificates for token verification
Query user databases or identity providers
Enforce authentication policies (token expiry, revocation)
Handle authentication failures consistently

This approach has severe drawbacks:

Problems with Distributed Auth

•Duplication — Same validation code in every service
•Inconsistency — Different services may validate differently
•Performance — Each service makes identity provider calls
•Complexity — Every team must understand auth protocols
•Upgrades — Changing auth requires updating all services

Benefits of Gateway Auth

•Single implementation — One place for auth logic
•Consistency — Uniform enforcement across all APIs
•Efficiency — Validates once, propagates context
•Simplicity — Services focus on business logic
•Agility — Auth changes happen in one place

The Trust Boundary Shift

With gateway authentication, the trust boundary shifts. External traffic is untrusted and validated at the gateway. Internal traffic (gateway to services) is trusted—services can assume requests are authenticated. This significantly simplifies service design.

Authentication Mechanisms

API Gateways support multiple authentication mechanisms. The choice depends on your use cases, client types, and security requirements.

Overview of Common Mechanisms:

Authentication Mechanisms Comparison
Mechanism	How It Works	Best For	Considerations
API Keys	Static key in header/query param	Server-to-server, simple integrations	Easy to leak, hard to rotate across clients
Basic Auth	Username:password base64 encoded	Legacy systems, internal tools	Credentials in every request, must use HTTPS
OAuth2/OIDC	Token-based with authorization flows	User authentication, third-party apps	Complex flows, requires IdP infrastructure
JWT	Self-contained signed tokens	Stateless auth, microservices	Token size, revocation challenges
mTLS	Mutual TLS with client certificates	Service-to-service, high security	Certificate management complexity
HMAC Signatures	Request signing with shared secret	AWS-style APIs, high integrity needs	Clock synchronization, implementation complexity

Multiple Mechanisms in Practice:

Real APIs often support multiple authentication mechanisms:

Web applications use OAuth2/OIDC with JWT access tokens
Mobile applications use OAuth2 with refresh tokens for session management
Partner integrations use API keys or HMAC signatures
Internal services use mTLS for service-to-service calls

The gateway evaluates which mechanism to use based on the presence of credentials in the request.

JWT Validation at the Gateway

JSON Web Tokens (JWTs) are the dominant token format for modern authentication. The gateway validates JWTs before forwarding requests, ensuring only authenticated traffic reaches services.

JWT Validation Steps:

Complete JWT Validation Checklist

•Extract token from Authorization header (Bearer <token>) or cookie
•Parse token into header, payload, and signature components
•Validate signature using issuer's public key (asymmetric) or shared secret (symmetric)
•Check exp claim — token must not be expired
•Check nbf claim — token must be active (not before)
•Validate iss claim — issuer must be expected identity provider
•Validate aud claim — audience must include this API/gateway
•Check custom claims — scope, roles, permissions as required
•Validate with revocation list — if using token revocation (optional but recommended)

JWT Validation Configuration
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
# Kong JWT plugin configuration
plugins:
  - name: jwt
    config:
      # Where to find the token
      header_names:
        - Authorization
      cookie_names:
        - access_token
        
      # Claims to validate
      claims_to_verify:
        - exp  # Token not expired
        - nbf  # Token is active
        
      # Key claim for looking up consumer
      key_claim_name: iss
      
      # Maximum allowed clock skew
      maximum_expiration: 3600
      
      # Anonymous consumer for failed auth (if allowed)
      # anonymous: null  # Reject unauthenticated
      
# Consumer and JWT credential setup
consumers:
  - username: auth0-users
    jwt_secrets:
      - key: "auth0"
        algorithm: RS256
        rsa_public_key: |
          -----BEGIN PUBLIC KEY-----
          MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...
          -----END PUBLIC KEY-----
 
  - username: internal-services
    jwt_secrets:
      - key: "internal-idp"
        algorithm: RS256
        rsa_public_key: |
          -----BEGIN PUBLIC KEY-----
          MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...
          -----END PUBLIC KEY-----

JWKS Caching is Critical

Validating JWTs requires the issuer's public keys. Fetching these keys for every request would devastate performance. Always cache JWKS (JSON Web Key Set) with appropriate TTL. Most gateways support automatic JWKS fetching and caching from the /.well-known/jwks.json endpoint.

OAuth2 Integration

While JWT validation handles token verification, OAuth2 encompasses the complete authentication and authorization flow. The gateway can participate in OAuth2 flows at multiple levels.

Gateway OAuth2 Responsibilities:

Gateway OAuth2 Functions

•Token Validation — Verify access tokens (JWT or opaque) from Authorization header
•Token Introspection — For opaque tokens, call IdP introspection endpoint to validate
•Scope Enforcement — Check if token scopes permit the requested operation
•Token Refresh — Optionally handle token refresh transparently for clients
•OAuth2 Flows Proxy — Redirect clients to IdP for authorization code flow
•Token Exchange — Exchange tokens for downstream service calls

OAuth2 Token Introspection
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
// Pseudo-code for OAuth2 token introspection at gateway
async function validateOpaqueToken(token: string): Promise<TokenInfo> {
    // Check local cache first
    const cached = tokenCache.get(token);
    if (cached && !cached.isExpired()) {
        return cached;
    }
    
    // Call IdP introspection endpoint
    const response = await fetch(config.introspectionEndpoint, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'Authorization': `Basic ${base64(clientId + ':' + clientSecret)}`
        },
        body: `token=${token}`
    });
    
    const result = await response.json();
    
    // {
    //   "active": true,
    //   "scope": "read write",
    //   "client_id": "partner-app",
    //   "username": "alice",
    //   "exp": 1735689600,
    //   "sub": "user-12345"
    // }
    
    if (!result.active) {
        throw new AuthenticationError('Token is not active');
    }
    
    // Cache for remaining lifetime (with buffer)
    const ttl = result.exp - Date.now()/1000 - 60;
    if (ttl > 0) {
        tokenCache.set(token, result, ttl);
    }
    
    return result;
}

Token Introspection vs. JWT Validation:

Aspect	JWT Validation	Token Introspection
Token Type	Self-contained JWT	Opaque string
Validation Method	Cryptographic signature check	Call to IdP endpoint
Performance	Fast (local validation)	Slower (network call)
Revocation	Difficult (token is valid until expiry)	Immediate (IdP checks revocation)
Token Size	Larger (contains claims)	Smaller (reference only)
Best For	Stateless, high-performance	When immediate revocation is critical

Hybrid Approach

Many systems use JWTs with short expiry (5-15 minutes) combined with refresh tokens. The gateway validates JWT signatures locally for speed, and short expiry limits exposure if a token is compromised. Refresh tokens trigger re-authentication and revocation checks.

API Key Authentication

API keys are the simplest form of API authentication—a static secret shared between client and server. Despite their simplicity, they require careful handling to remain secure.

API Key Architecture at the Gateway:

API Key Management
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
# Kong API Key authentication plugin
plugins:
  - name: key-auth
    config:
      # Where to look for the key
      key_names:
        - apikey
        - x-api-key
        - api_key
      key_in_header: true
      key_in_query: true
      key_in_body: false
      
      # Reject vs pass-through for missing keys
      anonymous: null  # Reject if no key
      
      # Hide the key from upstream services
      hide_credentials: true
      
# Consumer with API key
consumers:
  - username: partner-acme
    keyauth_credentials:
      - key: "akc_prod_7f8e9d0c1b2a..."
        tags: ["production", "partner"]
        
  - username: partner-beta
    keyauth_credentials:
      - key: "akc_test_1a2b3c4d5e6f..."
        tags: ["testing", "partner"]
 
# Associate consumers with rate limiting
plugins:
  - name: rate-limiting
    consumer: partner-acme
    config:
      minute: 1000
      policy: redis
      
  - name: rate-limiting
    consumer: partner-beta
    config:
      minute: 100
      policy: local

API Key Security Best Practices

•Never log API keys — Mask or redact keys in logs and error messages
•Store hashed keys — Hash keys before storing; never store plaintext
•Use secure generation — Cryptographically random, sufficient entropy (256+ bits)
•Include prefixes — Prefixes like pk_live_ help identify key type and environment
•Implement rotation — Support multiple active keys per client for rotation
•Set expiration — Keys should have optional expiry dates
•Track usage — Log key usage for audit and abuse detection
•Scope keys — Different keys for read vs. write operations if needed

API Keys Are Not User Authentication

API keys identify applications, not users. They're appropriate for server-to-server communication but shouldn't be used for end-user authentication. Keys can be shared, embedded in code, and leaked. For user auth, use OAuth2/OIDC.

Identity Propagation to Services

After the gateway authenticates a request, it must communicate the authenticated identity to backend services. This is identity propagation—ensuring services know who made the request without re-authenticating.

Propagation Strategies:

Identity Propagation Methods
Method	How It Works	Pros	Cons
Header Injection	Gateway adds X-User-ID, X-User-Roles headers	Simple, fast, explicit	Services must trust gateway; headers can be spoofed if exposed
JWT Forwarding	Gateway forwards the original JWT to services	Self-contained, verifiable	Services must validate JWT; token size overhead
Internal JWT	Gateway creates internal JWT with user context	Controlled claims, verifiable	Additional token management
Metadata in Context	Service mesh propagates identity via sidecar	Transparent to services	Requires service mesh; complexity

Identity Propagation Configuration
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# Gateway configuration for header-based identity propagation
plugins:
  - name: request-transformer
    config:
      add:
        headers:
          # Extract from validated JWT and add as headers
          - "X-User-ID:$(jwt.sub)"
          - "X-User-Email:$(jwt.email)"
          - "X-User-Roles:$(jwt.roles | join(','))"
          - "X-Request-ID:$(uuid)"
          - "X-Authenticated-At:$(timestamp)"
          
      remove:
        headers:
          # Remove any client-provided identity headers (security)
          - "X-User-ID"
          - "X-User-Email"
          - "X-User-Roles"
 
---
# Service code can then simply read headers
# Express.js example:
# const userId = req.headers['x-user-id'];
# const roles = req.headers['x-user-roles'].split(',');

Defense in Depth

Even with gateway authentication, services should validate that identity headers are present and properly formatted. In Kubernetes, network policies can ensure only the gateway can reach services, making header spoofing impossible. Combine network-level controls with application-level validation.

mTLS for Service Authentication

Mutual TLS (mTLS) provides cryptographic authentication for service-to-service communication. Both client and server present certificates, proving their identity at the transport layer.

mTLS in the Gateway Context:

mTLS Gateway Patterns

•External mTLS — Gateway requires client certificates from external callers (B2B, partner APIs)
•Internal mTLS — Gateway uses certificates when calling backend services
•TLS Termination — Gateway terminates external TLS, uses mTLS internally
•TLS Passthrough — Gateway passes encrypted traffic directly to service (for end-to-end encryption)
•Service Mesh Integration — Sidecar proxies handle mTLS transparently

mTLS Configuration
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
# NGINX mTLS configuration
server {
    listen 443 ssl;
    server_name api.example.com;
    
    # Server certificate (gateway's identity)
    ssl_certificate /etc/nginx/certs/gateway.crt;
    ssl_certificate_key /etc/nginx/certs/gateway.key;
    
    # Client certificate verification (external mTLS)
    ssl_client_certificate /etc/nginx/certs/ca-bundle.crt;
    ssl_verify_client on;  # Require valid client cert
    ssl_verify_depth 2;    # Allow intermediate CAs
    
    # Strong TLS settings
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers on;
    
    # Extract client certificate info
    location /api {
        # Pass certificate DN to backend
        proxy_set_header X-Client-DN $ssl_client_s_dn;
        proxy_set_header X-Client-Serial $ssl_client_serial;
        proxy_set_header X-Client-Verified $ssl_client_verify;
        
        proxy_pass https://backend-service;
        
        # mTLS to backend (internal mTLS)
        proxy_ssl_certificate /etc/nginx/certs/internal-client.crt;
        proxy_ssl_certificate_key /etc/nginx/certs/internal-client.key;
        proxy_ssl_trusted_certificate /etc/nginx/certs/internal-ca.crt;
        proxy_ssl_verify on;
    }
}

Certificate Lifecycle Automation

Manual certificate management doesn't scale. Use automated certificate management (cert-manager in Kubernetes, AWS ACM, HashiCorp Vault PKI) to handle issuance, renewal, and rotation. Service meshes like Istio provide automatic certificate rotation with no application changes.

Summary: Authentication Aggregation

Authentication aggregation is one of the most valuable responsibilities of an API Gateway. Let's consolidate the key insights:

Key Takeaways

•Centralization simplifies — Gateway authentication eliminates duplicated auth logic across services, ensuring consistency and reducing attack surface.
•Multiple mechanisms coexist — Real systems support OAuth2/JWT for users, API keys for partners, and mTLS for services. Configuration determines which applies.
•JWT validation is local — Verify signatures and claims without network calls. Cache JWKS and use short-lived tokens for the best security/performance balance.
•Token introspection enables revocation — For scenarios requiring immediate revocation, opaque tokens with introspection provide real-time validation at the cost of latency.
•Identity propagation is essential — Services need authenticated context. Choose between header injection (simple), JWT forwarding (verifiable), or internal tokens (controlled).
•API keys need careful handling — Generate securely, store hashed, never log, and remember they authenticate applications, not users.
•mTLS secures service-to-service — Cryptographic identity at the transport layer. Service meshes automate certificate lifecycle.
•Defense in depth — Combine network policies, gateway auth, and service-level validation for robust security.

What's Next:

With authentication covered, the next page explores Rate Limiting at the API Gateway—how to protect your services from abuse, implement fair usage policies, and gracefully handle traffic spikes without compromising legitimate users.

Page Complete

You now understand how to design authentication aggregation in API Gateways. From JWT validation to OAuth2 integration, from API key management to mTLS, you're equipped to build secure, scalable authentication for microservices architectures.

3 / 5

Loading learning content...

System Design (HLD)API Gateway in Microservices

API Gateway in Microservices

LevelAdvanced

Duration90 mins

TopicAPI Gateway in Microservices

3 / 5

Authentication Aggregation

The Identity Checkpoint of Your Distributed System

What You Will Learn

The Case for Centralized Authentication

Before diving into implementation, let's understand why authentication aggregation is essential in microservices architectures.

The Distributed Authentication Problem:

Without a gateway, each service must:

Parse and validate authentication credentials
Fetch signing keys or certificates for token verification
Query user databases or identity providers
Enforce authentication policies (token expiry, revocation)
Handle authentication failures consistently

This approach has severe drawbacks:

Problems with Distributed Auth

•Duplication — Same validation code in every service
•Inconsistency — Different services may validate differently
•Performance — Each service makes identity provider calls
•Complexity — Every team must understand auth protocols
•Upgrades — Changing auth requires updating all services

Benefits of Gateway Auth

•Single implementation — One place for auth logic
•Consistency — Uniform enforcement across all APIs
•Efficiency — Validates once, propagates context
•Simplicity — Services focus on business logic
•Agility — Auth changes happen in one place

The Trust Boundary Shift

Authentication Mechanisms

API Gateways support multiple authentication mechanisms. The choice depends on your use cases, client types, and security requirements.

Overview of Common Mechanisms:

Authentication Mechanisms Comparison
Mechanism	How It Works	Best For	Considerations
API Keys	Static key in header/query param	Server-to-server, simple integrations	Easy to leak, hard to rotate across clients
Basic Auth	Username:password base64 encoded	Legacy systems, internal tools	Credentials in every request, must use HTTPS
OAuth2/OIDC	Token-based with authorization flows	User authentication, third-party apps	Complex flows, requires IdP infrastructure
JWT	Self-contained signed tokens	Stateless auth, microservices	Token size, revocation challenges
mTLS	Mutual TLS with client certificates	Service-to-service, high security	Certificate management complexity
HMAC Signatures	Request signing with shared secret	AWS-style APIs, high integrity needs	Clock synchronization, implementation complexity

Multiple Mechanisms in Practice:

Real APIs often support multiple authentication mechanisms:

Web applications use OAuth2/OIDC with JWT access tokens
Mobile applications use OAuth2 with refresh tokens for session management
Partner integrations use API keys or HMAC signatures
Internal services use mTLS for service-to-service calls

The gateway evaluates which mechanism to use based on the presence of credentials in the request.

JWT Validation at the Gateway

JSON Web Tokens (JWTs) are the dominant token format for modern authentication. The gateway validates JWTs before forwarding requests, ensuring only authenticated traffic reaches services.

JWT Validation Steps:

Complete JWT Validation Checklist

•Extract token from Authorization header (Bearer <token>) or cookie
•Parse token into header, payload, and signature components
•Validate signature using issuer's public key (asymmetric) or shared secret (symmetric)
•Check exp claim — token must not be expired
•Check nbf claim — token must be active (not before)
•Validate iss claim — issuer must be expected identity provider
•Validate aud claim — audience must include this API/gateway
•Check custom claims — scope, roles, permissions as required
•Validate with revocation list — if using token revocation (optional but recommended)

JWT Validation Configuration
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
# Kong JWT plugin configuration
plugins:
  - name: jwt
    config:
      # Where to find the token
      header_names:
        - Authorization
      cookie_names:
        - access_token
        
      # Claims to validate
      claims_to_verify:
        - exp  # Token not expired
        - nbf  # Token is active
        
      # Key claim for looking up consumer
      key_claim_name: iss
      
      # Maximum allowed clock skew
      maximum_expiration: 3600
      
      # Anonymous consumer for failed auth (if allowed)
      # anonymous: null  # Reject unauthenticated
      
# Consumer and JWT credential setup
consumers:
  - username: auth0-users
    jwt_secrets:
      - key: "auth0"
        algorithm: RS256
        rsa_public_key: |
          -----BEGIN PUBLIC KEY-----
          MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...
          -----END PUBLIC KEY-----
 
  - username: internal-services
    jwt_secrets:
      - key: "internal-idp"
        algorithm: RS256
        rsa_public_key: |
          -----BEGIN PUBLIC KEY-----
          MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...
          -----END PUBLIC KEY-----

JWKS Caching is Critical

OAuth2 Integration

While JWT validation handles token verification, OAuth2 encompasses the complete authentication and authorization flow. The gateway can participate in OAuth2 flows at multiple levels.

Gateway OAuth2 Responsibilities:

Gateway OAuth2 Functions

•Token Validation — Verify access tokens (JWT or opaque) from Authorization header
•Token Introspection — For opaque tokens, call IdP introspection endpoint to validate
•Scope Enforcement — Check if token scopes permit the requested operation
•Token Refresh — Optionally handle token refresh transparently for clients
•OAuth2 Flows Proxy — Redirect clients to IdP for authorization code flow
•Token Exchange — Exchange tokens for downstream service calls

OAuth2 Token Introspection
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
// Pseudo-code for OAuth2 token introspection at gateway
async function validateOpaqueToken(token: string): Promise<TokenInfo> {
    // Check local cache first
    const cached = tokenCache.get(token);
    if (cached && !cached.isExpired()) {
        return cached;
    }
    
    // Call IdP introspection endpoint
    const response = await fetch(config.introspectionEndpoint, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'Authorization': `Basic ${base64(clientId + ':' + clientSecret)}`
        },
        body: `token=${token}`
    });
    
    const result = await response.json();
    
    // {
    //   "active": true,
    //   "scope": "read write",
    //   "client_id": "partner-app",
    //   "username": "alice",
    //   "exp": 1735689600,
    //   "sub": "user-12345"
    // }
    
    if (!result.active) {
        throw new AuthenticationError('Token is not active');
    }
    
    // Cache for remaining lifetime (with buffer)
    const ttl = result.exp - Date.now()/1000 - 60;
    if (ttl > 0) {
        tokenCache.set(token, result, ttl);
    }
    
    return result;
}

Token Introspection vs. JWT Validation:

Aspect	JWT Validation	Token Introspection
Token Type	Self-contained JWT	Opaque string
Validation Method	Cryptographic signature check	Call to IdP endpoint
Performance	Fast (local validation)	Slower (network call)
Revocation	Difficult (token is valid until expiry)	Immediate (IdP checks revocation)
Token Size	Larger (contains claims)	Smaller (reference only)
Best For	Stateless, high-performance	When immediate revocation is critical

Hybrid Approach

API Key Authentication

API keys are the simplest form of API authentication—a static secret shared between client and server. Despite their simplicity, they require careful handling to remain secure.

API Key Architecture at the Gateway:

API Key Management
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
# Kong API Key authentication plugin
plugins:
  - name: key-auth
    config:
      # Where to look for the key
      key_names:
        - apikey
        - x-api-key
        - api_key
      key_in_header: true
      key_in_query: true
      key_in_body: false
      
      # Reject vs pass-through for missing keys
      anonymous: null  # Reject if no key
      
      # Hide the key from upstream services
      hide_credentials: true
      
# Consumer with API key
consumers:
  - username: partner-acme
    keyauth_credentials:
      - key: "akc_prod_7f8e9d0c1b2a..."
        tags: ["production", "partner"]
        
  - username: partner-beta
    keyauth_credentials:
      - key: "akc_test_1a2b3c4d5e6f..."
        tags: ["testing", "partner"]
 
# Associate consumers with rate limiting
plugins:
  - name: rate-limiting
    consumer: partner-acme
    config:
      minute: 1000
      policy: redis
      
  - name: rate-limiting
    consumer: partner-beta
    config:
      minute: 100
      policy: local

API Key Security Best Practices

•Never log API keys — Mask or redact keys in logs and error messages
•Store hashed keys — Hash keys before storing; never store plaintext
•Use secure generation — Cryptographically random, sufficient entropy (256+ bits)
•Include prefixes — Prefixes like pk_live_ help identify key type and environment
•Implement rotation — Support multiple active keys per client for rotation
•Set expiration — Keys should have optional expiry dates
•Track usage — Log key usage for audit and abuse detection
•Scope keys — Different keys for read vs. write operations if needed

API Keys Are Not User Authentication

Identity Propagation to Services

Propagation Strategies:

Identity Propagation Methods
Method	How It Works	Pros	Cons
Header Injection	Gateway adds X-User-ID, X-User-Roles headers	Simple, fast, explicit	Services must trust gateway; headers can be spoofed if exposed
JWT Forwarding	Gateway forwards the original JWT to services	Self-contained, verifiable	Services must validate JWT; token size overhead
Internal JWT	Gateway creates internal JWT with user context	Controlled claims, verifiable	Additional token management
Metadata in Context	Service mesh propagates identity via sidecar	Transparent to services	Requires service mesh; complexity

Identity Propagation Configuration
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# Gateway configuration for header-based identity propagation
plugins:
  - name: request-transformer
    config:
      add:
        headers:
          # Extract from validated JWT and add as headers
          - "X-User-ID:$(jwt.sub)"
          - "X-User-Email:$(jwt.email)"
          - "X-User-Roles:$(jwt.roles | join(','))"
          - "X-Request-ID:$(uuid)"
          - "X-Authenticated-At:$(timestamp)"
          
      remove:
        headers:
          # Remove any client-provided identity headers (security)
          - "X-User-ID"
          - "X-User-Email"
          - "X-User-Roles"
 
---
# Service code can then simply read headers
# Express.js example:
# const userId = req.headers['x-user-id'];
# const roles = req.headers['x-user-roles'].split(',');

Defense in Depth

mTLS for Service Authentication

Mutual TLS (mTLS) provides cryptographic authentication for service-to-service communication. Both client and server present certificates, proving their identity at the transport layer.

mTLS in the Gateway Context:

mTLS Gateway Patterns

•External mTLS — Gateway requires client certificates from external callers (B2B, partner APIs)
•Internal mTLS — Gateway uses certificates when calling backend services
•TLS Termination — Gateway terminates external TLS, uses mTLS internally
•TLS Passthrough — Gateway passes encrypted traffic directly to service (for end-to-end encryption)
•Service Mesh Integration — Sidecar proxies handle mTLS transparently

mTLS Configuration
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
# NGINX mTLS configuration
server {
    listen 443 ssl;
    server_name api.example.com;
    
    # Server certificate (gateway's identity)
    ssl_certificate /etc/nginx/certs/gateway.crt;
    ssl_certificate_key /etc/nginx/certs/gateway.key;
    
    # Client certificate verification (external mTLS)
    ssl_client_certificate /etc/nginx/certs/ca-bundle.crt;
    ssl_verify_client on;  # Require valid client cert
    ssl_verify_depth 2;    # Allow intermediate CAs
    
    # Strong TLS settings
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers on;
    
    # Extract client certificate info
    location /api {
        # Pass certificate DN to backend
        proxy_set_header X-Client-DN $ssl_client_s_dn;
        proxy_set_header X-Client-Serial $ssl_client_serial;
        proxy_set_header X-Client-Verified $ssl_client_verify;
        
        proxy_pass https://backend-service;
        
        # mTLS to backend (internal mTLS)
        proxy_ssl_certificate /etc/nginx/certs/internal-client.crt;
        proxy_ssl_certificate_key /etc/nginx/certs/internal-client.key;
        proxy_ssl_trusted_certificate /etc/nginx/certs/internal-ca.crt;
        proxy_ssl_verify on;
    }
}

Certificate Lifecycle Automation

Summary: Authentication Aggregation

Authentication aggregation is one of the most valuable responsibilities of an API Gateway. Let's consolidate the key insights:

Key Takeaways

•Centralization simplifies — Gateway authentication eliminates duplicated auth logic across services, ensuring consistency and reducing attack surface.
•Multiple mechanisms coexist — Real systems support OAuth2/JWT for users, API keys for partners, and mTLS for services. Configuration determines which applies.
•JWT validation is local — Verify signatures and claims without network calls. Cache JWKS and use short-lived tokens for the best security/performance balance.
•Token introspection enables revocation — For scenarios requiring immediate revocation, opaque tokens with introspection provide real-time validation at the cost of latency.
•Identity propagation is essential — Services need authenticated context. Choose between header injection (simple), JWT forwarding (verifiable), or internal tokens (controlled).
•API keys need careful handling — Generate securely, store hashed, never log, and remember they authenticate applications, not users.
•mTLS secures service-to-service — Cryptographic identity at the transport layer. Service meshes automate certificate lifecycle.
•Defense in depth — Combine network policies, gateway auth, and service-level validation for robust security.

What's Next:

Page Complete

3 / 5