OIDC/JWKS Authentication: Enterprise SSO for Your APIs

OIDC/JWKS authentication is coming to G8KEPR in Q1 2025, enabling enterprise SSO integration with Auth0, Okta, Azure AD, Keycloak, and any OpenID Connect provider.

What is OIDC/JWKS?

OpenID Connect (OIDC) is an identity layer on top of OAuth 2.0 that lets users authenticate with your API using their existing enterprise credentials. JWKS (JSON Web Key Sets) is a standard way to distribute public keys for verifying JWT signatures.

1. User logs in via Auth0/Okta/Azure AD
2. Identity provider issues a JWT access token
3. Client sends request to your API with token:
   Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

4. G8KEPR validates token:
   ✓ Download JWKS from provider (cached)
   ✓ Verify JWT signature using public key
   ✓ Check expiration (exp claim)
   ✓ Verify audience (aud claim)
   ✓ Verify issuer (iss claim)

5. If valid, extract claims and forward request
6. If invalid, return 401 Unauthorized

Configuration Example

# config.yaml
authentication:
  oidc:
    enabled: true
    providers:
      - name: auth0
        issuer: https://yourcompany.auth0.com/
        audience: https://api.yourcompany.com
        jwks_uri: https://yourcompany.auth0.com/.well-known/jwks.json

      - name: okta
        issuer: https://yourcompany.okta.com/oauth2/default
        audience: api://yourapi
        jwks_uri: https://yourcompany.okta.com/oauth2/default/v1/keys

      - name: azure
        issuer: https://login.microsoftonline.com/{tenant-id}/v2.0
        audience: api://your-client-id
        jwks_uri: https://login.microsoftonline.com/{tenant-id}/discovery/v2.0/keys

    # JWKS cache settings
    jwks_cache_ttl: 3600  # Cache keys for 1 hour
    jwks_refresh_interval: 300  # Refresh every 5 mins

    # Token validation
    clock_skew_tolerance: 60  # Allow 60s clock skew

    # Claims extraction
    user_claim: sub  # Which claim contains user ID
    email_claim: email
    roles_claim: roles  # For RBAC

Supported Providers

Advanced Features

1. Per-User Rate Limiting

Extract user ID from JWT and apply rate limits per user instead of per IP:

rate_limit:
  by: user_id  # Instead of IP address
  claim: sub  # JWT claim containing user ID

  tiers:
    free:
      limit: 100/hour
      matching_claim: plan=free

    pro:
      limit: 10000/hour
      matching_claim: plan=pro

    enterprise:
      limit: unlimited
      matching_claim: plan=enterprise

2. Custom Claims Extraction

Extract custom claims from JWTs and use them in routing/authorization:

authentication:
  oidc:
    extract_headers:
      - claim: email
        header: X-User-Email

      - claim: roles
        header: X-User-Roles

      - claim: organization_id
        header: X-Org-ID

      - claim: plan
        header: X-Subscription-Plan

# Now your backend receives:
# X-User-Email: john@example.com
# X-User-Roles: ["admin", "developer"]
# X-Org-ID: org_abc123
# X-Subscription-Plan: enterprise

3. Role-Based Access Control (RBAC)

authorization:
  rbac:
    enabled: true
    roles_claim: roles  # JWT claim with user roles

    rules:
      - path: /api/admin/*
        allowed_roles: [admin]

      - path: /api/users/*
        allowed_roles: [admin, user]
        method: GET

      - path: /api/billing/*
        allowed_roles: [billing_admin]

      - path: /api/public/*
        allowed_roles: []  # Anyone (even unauthenticated)

JWKS Automatic Rotation

Identity providers periodically rotate their signing keys for security. G8KEPR automatically handles this:

Migration Path

If you currently use API keys, you can migrate to OIDC gradually: