Handling Authentication
1. Implementing API Key Authentication
| Location | Example | Notes |
|---|---|---|
| Header | X-API-Key: sk_... | Preferred |
| Query | ?api_key=... | Logged, avoid |
| Authorization | ApiKey sk_... | RFC style |
Example: API key plugin (Kong)
plugins:
- name: key-auth
config:
key_names: [X-API-Key, apikey]
key_in_header: true
key_in_query: false
hide_credentials: true2. Using Bearer Token Authentication
Example: Bearer token
GET /v1/orders HTTP/1.1
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJzdWIi...| Token Type | Validation |
|---|---|
| JWT | Verify signature locally |
| Opaque | Introspect at auth server |
| PAT | Database lookup |
3. Using Basic Authentication
| Aspect | Detail |
|---|---|
| Format | Basic base64(user:pass) |
| Security | HTTPS only (base64 is not encryption) |
| Use case | Internal tools, machine accounts |
| Storage | bcrypt/argon2 hashed on server |
4. Configuring OAuth 2.0 Flow
| Grant Type | Use Case |
|---|---|
| authorization_code + PKCE | Web/SPA/mobile (preferred) |
| client_credentials | Server-to-server |
| refresh_token | Renew access tokens |
| device_code | TVs, CLIs |
| password DEPRECATED | Legacy only |
| implicit DEPRECATED | Replaced by code+PKCE |
Client → /authorize?response_type=code&pkce_challenge → IdP
IdP → Redirect with ?code=...
Client → /token (code + verifier) → IdP
IdP → access_token + refresh_token
Client → API (Bearer access_token)
5. Implementing JWT Validation
| Claim | Validation |
|---|---|
iss | Match issuer URL |
aud | Match expected audience |
exp | Future timestamp |
nbf | Past or current |
iat | Reasonable past |
| Signature | JWKS public key (RS256/ES256) |
Example: JWT plugin config
plugins:
- name: jwt
config:
key_claim_name: iss
claims_to_verify: [exp, nbf]
secret_is_base64: false
maximum_expiration: 3600
run_on_preflight: false6. Configuring HMAC Signature Validation
Example: HMAC signed request
Authorization: Hmac username="acme",
algorithm="hmac-sha256",
headers="(request-target) date digest",
signature="base64sig=="
Date: Wed, 18 May 2026 12:00:00 GMT
Digest: SHA-256=abcd...7. Implementing Multi-Factor Authentication
| Factor | Examples |
|---|---|
| Knowledge | Password, PIN |
| Possession | TOTP, SMS, push, hardware key |
| Inherence | Biometric (Face/Touch ID) |
| Step-up MFA | Require on sensitive operations |
| ACR claim | JWT acr = auth level |
8. Setting Up Identity Provider Integration (OIDC)
Example: OIDC plugin
plugins:
- name: openid-connect
config:
issuer: https://auth.example.com/realms/api
client_id: gateway
client_secret: ${OIDC_SECRET}
scopes: [openid, profile, email]
auth_methods: [authorization_code, bearer, introspection]
bearer_token_param_type: [header]
cache_introspection: true
introspection_endpoint_auth_method: client_secret_basic9. Configuring Anonymous Access
| Setting | Effect |
|---|---|
anonymous: guest | Fall through to consumer |
| Public route | No auth plugin |
| Optional auth | Enrich if present, allow if not |
| Rate limit | Lower for anonymous |
10. Implementing Token Revocation
| Mechanism | Notes |
|---|---|
RFC 7009 /revoke | OAuth standard |
| Revocation list (CRL) | Polled blocklist |
| Introspection | Always check at /introspect |
| Short TTL | 5-15 min limits damage |
| Refresh rotation | One-time use refresh tokens |