Skip to main content
API7.ai Logo
Version: 3.9.x

OAuth 2.0 and OIDC

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).

Token Validation and Claims​

Once authenticated, the gateway can:

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

Next Steps​