Authentication & Authorization

plugins:
  - name: key-auth
    config:
      key_names:
        - X-API-Key
        - apikey
      hide_credentials: true  # Strip key before forwarding
      key_in_header: true
      key_in_query: false     # Never accept keys in URL
      key_in_body: false

# Consumer with key
consumers:
  - username: partner-acme
    keyauth_credentials:
      - key: sk_live_a1b2c3d4e5f6  # In practice, auto-generated

plugins:
  - name: jwt
    config:
      # Fetch public keys from JWKS endpoint
      uri_param_names: []
      header_names:
        - Authorization
      claims_to_verify:
        - exp  # Token not expired
        - nbf  # Token not used before valid time
      key_claim_name: iss
      maximum_expiration: 3600  # Reject tokens valid > 1 hour

# Gateway validation steps:
# 1. Extract token from Authorization: Bearer <token>
# 2. Decode header → get kid (key ID) and alg
# 3. Fetch public key from JWKS endpoint (cached)
# 4. Verify signature using public key
# 5. Check exp, nbf, iss, aud claims
# 6. Extract user claims → forward as headers

{
  "active": true,
  "client_id": "partner-app-123",
  "username": "alice@example.com",
  "scope": "read:orders write:orders",
  "sub": "user-uuid-abc-123",
  "aud": "https://api.example.com",
  "iss": "https://auth.example.com",
  "exp": 1709251200,
  "iat": 1709247600,
  "token_type": "Bearer"
}

server {
    listen 443 ssl;

    # Server certificate (standard)
    ssl_certificate     /etc/ssl/server.crt;
    ssl_certificate_key /etc/ssl/server.key;

    # Client certificate verification (mTLS)
    ssl_client_certificate /etc/ssl/trusted-client-ca.crt;
    ssl_verify_client on;
    ssl_verify_depth 2;

    # Forward client identity to backend
    location / {
        proxy_pass http://backend;
        proxy_set_header X-Client-CN $ssl_client_s_dn_cn;
        proxy_set_header X-Client-Serial $ssl_client_serial;
        proxy_set_header X-Client-Verify $ssl_client_verify;
    }
}

# Client computes signature
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
STRING_TO_SIGN="POST\n/api/webhooks\n${TIMESTAMP}\nsha256=<body-hash>"
SIGNATURE=$(echo -n "$STRING_TO_SIGN" | openssl dgst -sha256 -hmac "$SECRET_KEY" -binary | base64)

# Client sends request with signature headers
curl -X POST https://api.example.com/api/webhooks \
  -H "X-Timestamp: ${TIMESTAMP}" \
  -H "X-Signature: hmac-sha256=${SIGNATURE}" \
  -H "Content-Type: application/json" \
  -d '{"event": "payment.completed"}'

# Gateway validates:
# 1. Timestamp within 5-minute window (replay prevention)
# 2. Recompute signature with stored secret
# 3. Compare signatures (constant-time comparison)

# Open Policy Agent (OPA) integration with gateway
# Policy: /admin/* requires admin role
package gateway.authz

default allow = false

# Allow if user has required role for the path
allow {
    required_role := role_for_path(input.path)
    required_role == input.user_roles[_]
}

# Path-to-role mapping
role_for_path(path) = "admin" {
    startswith(path, "/admin/")
}

role_for_path(path) = "user" {
    startswith(path, "/api/")
}

# Allow health checks without auth
allow {
    input.path == "/health"
}

# Headers the gateway injects after successful auth
# Backend services trust these implicitly

X-User-ID: "usr_abc123"           # Authenticated user identifier
X-User-Email: "alice@example.com" # User email (if available)
X-User-Roles: "admin,editor"      # Comma-separated roles
X-Tenant-ID: "tenant_xyz"         # Multi-tenant isolation
X-Auth-Method: "jwt"              # How the user authenticated
X-Request-ID: "req_uuid_here"     # Correlation ID for tracing
X-Client-ID: "app_partner_acme"   # Which application made the call

# CRITICAL: Gateway MUST strip these headers from incoming requests
# to prevent clients from forging identity