OIDC Integration in APISIX#

APISIX implements full OAuth 2.0 / OpenID Connect flows through the openid-connect plugin, which wraps the lua-resty-openidc library. It handles authorization code grant (browser-based SSO), client credentials grant (M2M), and password grant — with session management, token refresh, and logout built in 1.

The plugin requires three fields: client_id, client_secret, and discovery 2. The discovery URL points to the IdP's .well-known/openid-configuration endpoint, from which the plugin auto-discovers token, introspection, and JWKS endpoints.

Key Behavioral Modes#

The plugin operates in one of two modes depending on whether bearer_only is set:

When bearer_only is false, the plugin calls openidc.authenticate() 3, which validates any session cookie and, if none is found, redirects the browser to the IdP's authorization endpoint. A session.secret (min 16 chars) is required for cookie encryption; APISIX auto-generates one with a warning if it is omitted 4.

When bearer_only is true or introspection_endpoint / public_key / use_jwks is set, the plugin calls the internal introspect() function 5, which routes validation to one of three paths:

• JWKS: openidc.bearer_jwt_verify() — validates against the IdP's public key set 6.
• Public key: same call path using a static public_key value 7.
• Introspection endpoint: openidc.introspect() — calls the IdP's introspection endpoint on each request 8.

Token Header Injection#

After successful validation the plugin injects upstream headers (all configurable, all defaulting to true or false) 9:

Access token can alternatively be forwarded in the Authorization header via access_token_in_authorization_header: true 10.

Session & Token Lifecycle#

• renew_access_token_on_expiry (default true) — silently renews the access token using the refresh token without re-authentication 11.
• refresh_session_interval — refresh the ID token without full re-auth 12.
• iat_slack (default 120s) — clock skew tolerance on iat claim 13.
• jwk_expires_in (default 86400s) — JWK cache TTL 14.
• introspection_interval (default 0) — TTL for caching introspection results; 0 means no caching 15.
• revoke_tokens_on_logout (default false) — notifies the IdP when the user hits logout_path 16.

The logout_path (default /logout) triggers logout; post_logout_redirect_uri controls where the user lands after logout 17.

Claim Validation#

claim_validator enables fine-grained JWT claim checks 18:

• issuer.valid_issuers — allowlist of accepted issuers; falls back to the discovery doc's issuer 19.
• audience.required — enforce presence of audience claim 20.
• audience.match_with_client_id — require aud to include or equal client_id 21.

required_scopes rejects tokens that don't carry every listed scope 22.

Keycloak Configuration Pattern#

For Keycloak, the discovery URL is http://<keycloak-host>/realms/<realm-name>/.well-known/openid-configuration 1.

Authorization code grant (browser SSO):

"openid-connect": {
  "bearer_only": false,
  "session": { "secret": "<min-16-char-key>" },
  "client_id": "<keycloak-client-id>",
  "client_secret": "<keycloak-client-secret>",
  "discovery": "http://<keycloak-host>/realms/<realm>/.well-known/openid-configuration",
  "scope": "openid profile",
  "redirect_uri": "http://<apisix-host>/anything/callback"
}

Enable PKCE by adding "use_pkce": true 1. Keycloak must have the PKCE challenge method configured on the client.

Client credentials / M2M (JWKS validation):

"openid-connect": {
  "bearer_only": false,
  "use_jwks": true,
  ...
}

Client credentials / M2M (introspection):

"openid-connect": {
  "bearer_only": true,
  ...
}

Breaking change (APISIX 3.16.0): ssl_verify default changed from false to true. Set "ssl_verify": false when using Keycloak with self-signed certificates 1.

openid-connect vs jwt-auth#

Use openid-connect when APISIX is acting as an OIDC relying party (full login flow, SSO, Keycloak/Auth0/Okta integration). Use jwt-auth when you control token issuance yourself and need lightweight, no-IdP-call verification at the gateway.

Reference Links#

• Source: apisix/plugins/openid-connect.lua
• Source: apisix/plugins/jwt-auth.lua
• How-to: Set Up SSO with Keycloak
• Learning Center: API Gateway Auth — OAuth 2.0, JWT & OIDC with APISIX