OAuth 2.0 and OIDC

Secure your APIs with modern token-based authentication. Learn how to integrate API7 Gateway with OAuth 2.0 and OpenID Connect (OIDC) providers like Okta and Keycloak.

API7 Gateway supports modern, token-based authentication through OAuth 2.0 and OpenID Connect (OIDC). By using the openid-connect plugin, you can delegate user authentication to a centralized Identity Provider (IdP) and enforce fine-grained access control on your APIs.

Capabilities

Seamless Integration: Connect with any OIDC-compliant IdP (Okta, Keycloak, Auth0, Azure AD).
Token Validation: Automatically validate JWT signatures, expiration, and issuer.
Refresh Token Handling: Securely handle token refresh flows at the gateway level.
Scoped Access Control: Restrict API access based on OAuth 2.0 scopes or OIDC claims.

Configure OIDC Authentication

To secure a route with OIDC, you need to configure the openid-connect plugin with your IdP's details.

Before you begin, prepare a token from the Dashboard.

# Create the service for the upstream you want to protect
curl -k "https://localhost:7443/apisix/admin/services/oidc-protected-service?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "oidc-protected-service",
    "upstream": {
      "type": "roundrobin",
      "scheme": "https",
      "nodes": [
        { "host": "your-upstream.example.com", "port": 443, "weight": 100 }
      ]
    }
  }'

# Create the route under that service with the openid-connect plugin
curl -k "https://localhost:7443/apisix/admin/routes/oidc-protected-route?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "oidc-protected-route",
    "service_id": "oidc-protected-service",
    "paths": ["/secure-api/*"],
    "plugins": {
      "openid-connect": {
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET",
        "discovery": "https://{IDP_DOMAIN}/.well-known/openid-configuration",
        "scope": "openid profile email",
        "bearer_only": true
      }
    }
  }'

If you are not running locally, replace localhost with your Admin API host. The -k flag is required if the Admin API uses a self-signed TLS certificate. Replace {gateway_group_id} with the gateway group ID from the Gateway Groups page in the Dashboard (use default for the gateway group created by the quickstart).

adc.yaml

services:
  - name: oidc-protected-service
    upstream:
      scheme: https
      nodes:
        - host: your-upstream.example.com
          port: 443
          weight: 100
    routes:
      - name: oidc-protected-route
        uris:
          - /secure-api/*
        plugins:
          openid-connect:
            client_id: YOUR_CLIENT_ID
            client_secret: YOUR_CLIENT_SECRET
            discovery: "https://{IDP_DOMAIN}/.well-known/openid-configuration"
            scope: "openid profile email"
            bearer_only: true

adc sync -f adc.yaml

Token Validation and Claims

Once authenticated, the gateway can:

Validate the token's signature using the IdP's public keys (automatically fetched via the discovery endpoint).
Check for token expiration (exp) and issuer (iss).
Inject user info or claims into request headers for upstream consumption.

Next Steps

Configure SSO for the Dashboard to centralize internal user access.
Implement RBAC based on OIDC claims.