OpenID Connect Configuration

Client ID.

Client secret. The value is encrypted with AES before being stored in etcd.

In API7 Enterprise from version 3.9.14 and APISIX from version 3.17.0, the client secret is optional for local JWT verification modes that do not contact the OpenID provider, such as bearer_only combined with public_key or use_jwks. It is also optional when client authentication uses private_key_jwt, or when the authorization code flow uses PKCE. It remains required for flows that authenticate to the provider with a client secret, such as token introspection or the authorization code flow without PKCE.

URL to the well-known discovery document of the OpenID provider, which contains a list of OP API endpoints. The plugin can directly utilize the endpoints from the discovery document. You can also configure these endpoints individually, which takes precedence over the endpoints supplied in the discovery document.

OIDC scope that corresponds to information that should be returned about the authenticated user, also known as claims. This is used to authorize users with proper permission. The default value is openid, the required scope for OIDC to return a sub claim that uniquely identifies the authenticated user.

Additional scopes can be appended and delimited by spaces, such as openid email profile.

Scopes required for authorization. If any required scope is missing, the plugin rejects the request with 403 Forbidden.

With bearer introspection, the scopes are read from the introspection response. In APISIX 3.18.0, authorization code sessions are also checked: scopes are read from the access token and then the ID token, and the session is rejected if its granted scopes cannot be determined. API7 Enterprise 3.9.18 and 3.10.5 enforce this field on bearer introspection only.

Realm in theWWW-Authenticate response header returned with a 401 Unauthorized response due to authentication failure. For example:

• If realm is set to apisix-oidc, the 401 response will include the following header:

  WWW-Authenticate: Bearer realm="apisix-oidc"

• If realm is not configured, the 401 response will include the following header:

  WWW-Authenticate: Bearer realm="apisix"

JWT claim validation configurations.

{
  "audience": {
    "claim": "custom_claim",
    "required": true
  }
}

JSON Schema used to validate the claims returned in the OIDC response. For instance, the schema {"type":"object","properties":{"access_token":{"type":"string"}},"required":["access_token"]} ensures that the response includes a required string field named access_token.

Available in APISIX from 3.14.0 and API7 Enterprise from 3.9.2

If true, strictly require bearer access token in requests for authentication.

Path to activate the logout.

URL to redirect users to after the logout_path receive a request to log out.

URI to redirect to after authentication with the OpenID provider.

Configure a fully qualified URI with a scheme and host. The path should match the route without being identical to the protected request path. For example, if the route uri is /api/v1/*, set redirect_uri to https://gateway.example.com/api/v1/redirect.

If redirect_uri is not configured or is a root-relative path beginning with /, the gateway constructs the URI from the request scheme and host. It preserves an explicit request port and uses forwarded origin headers only when the immediate proxy is included in apisix.trusted_addresses.

A fully qualified URI avoids relying on a request-derived origin. Configure the same URI as an allowed redirect URI in the OpenID provider.

Valid values: greater than 0

Request timeout in seconds.

If true, verify the OpenID provider's SSL certificates.

The default value changed from false to true in APISIX 3.16.0 and API7 Enterprise 3.9.8. This is a breaking change.

URL of the token introspection endpoint for the OpenID provider used to introspect access tokens. If this is unset, the introspection endpoint presented in the well-known discovery document is used as a fallback.

Authentication method for the token introspection endpoint. The value should be one of the authentication methods specified in the introspection_endpoint_auth_methods_supported authorization server metadata as seen in the well-known discovery document, such as client_secret_basic, client_secret_post, private_key_jwt, and client_secret_jwt.

With the default client_secret_basic, client credentials are sent only in the Authorization header. Set this field to client_secret_post if the identity provider expects them in the introspection request body.

Authentication method for the token endpoint. The value should be one of the authentication methods specified in the token_endpoint_auth_methods_supported authorization server metadata as seen in the well-known discovery document, such as client_secret_basic, client_secret_post, private_key_jwt, and client_secret_jwt.

If the configured method is not supported by the plugin, it is ignored and the plugin uses the first usable method advertised by the OpenID provider. If the configured method is supported by the plugin, and token_endpoint_auth_methods_supported is present but does not include it, token endpoint authentication fails.

Private key used to sign a client assertion JWT. Required when private_key_jwt is selected for the token, introspection, or PAR endpoint. The key type must match client_jwt_assertion_alg: RSA for RS*, or an EC key on the appropriate curve for ES*.

The value is encrypted with AES before being stored in etcd.

Optional key ID used in the signed client assertion JWT when private_key_jwt is selected for an endpoint.

Lifetime in seconds of a client assertion JWT used with private_key_jwt or client_secret_jwt on the token, introspection, or PAR endpoint.

Public key used to verify JWT signature id asymmetric algorithm is used. Providing this value to perform token verification will skip token introspection in client credentials flow.

You can pass the public key in -----BEGIN PUBLIC KEY-----\\n……\\n-----END PUBLIC KEY----- format.

Algorithm used for signing JWT, such as RS256.

If true, set the access token used by the authenticated request in a request header. By default, the X-Access-Token header is used. The gateway clears any client-supplied value before setting the token.

If true and if set_access_token_header is also true, set the access token in the Authorization header.

Set to true if the OpenID provider does not sign its ID token, such as when the signature algorithm is set to none.

If true and if public_key is not set, use the JWKS to verify JWT signature and skip token introspection in client credentials flow. The JWKS endpoint is parsed from the discovery document.

Expiration time for JWK cache in seconds.

If true, force re-verification for a bearer token and ignore any existing cached verification results.

Optional name of a cache segment, used to separate and differentiate caches used by token introspection or JWT verification.

If true, use the Proof Key for Code Exchange (PKCE) for Authorization Code Flow as defined in RFC 7636.

If true and if a validated ID token is available, set base64-encoded decoded claims in the X-ID-Token request header. This value is not the signed JWT and cannot be verified against the provider's JWKS. The gateway clears any client-supplied value first.

If true and if user info data is available, set the value in the X-Userinfo request header. The gateway clears any client-supplied value first.

If true and a raw ID token is available, add the original signed JWT issued by the identity provider to the X-Raw-ID-Token request header. The token is persisted in the session so an upstream service can verify it against the provider's JWKS. Available in API7 Enterprise 3.9.17 and 3.10.4, and in APISIX 3.18.0.

The raw ID token is a bearer credential. Enable this only for upstreams you trust, and keep the header out of access logs and out of any response returned to the client.

If true and if a refresh token obtained from the identity provider is available, set the value in the X-Refresh-Token request header. The gateway clears any client-supplied value first.

Session configuration used when bearer_only is false and the plugin uses Authorization Code flow.

Valid values: auth, deny, or pass

Action for unauthenticated requests.

When set to auth, redirect to the authentication endpoint of the OpenID provider.

When set to pass, allow the request without authentication.

When set to deny, return 401 unauthenticated responses rather than start the authorization code grant flow.

Configurations for the proxy server that the OpenID provider is behind.

Additional parameters to send in the request to the authorization endpoint.

If true, attempt to silently renew the access token when it expires or if a refresh token is available. If the token fails to renew, redirect user for re-authentication.

Lifetime of the access token in seconds if no expires_in attribute is present in the token endpoint response.

Time interval to refresh user ID token without re-authentication. In APISIX, when not set, the plugin will not attempt to silently renew.

In API7 Gateway, the default value is 900.

Tolerance of clock skew in seconds with the iat claim in an ID token.

Name of the expiry claim, which controls the TTL of the cached and introspected access token.

TTL of the cached and introspected access token in seconds.

The default value is 0, which means this option is not used and the plugin defaults to use the TTL passed by expiry claim defined in introspection_expiry_claim.

If introspection_interval is larger than 0 and less than the TTL passed by expiry claim defined in introspection_expiry_claim, use introspection_interval.

Used to append additional header values to the introspection HTTP request. If the specified header does not exist in the original request, header value will not be appended.

If an ID token uses an expected signing algorithm that the gateway does not support, setting this to true continues without verifying the signature. Setting it to false rejects the token.

Set this to false in security-sensitive deployments unless you explicitly accept the risk of an unverified ID token signature. Setting it to false does not add support for additional signing algorithms.

In APISIX 3.18.0 and API7 Gateway 3.9.18 and 3.10.5, the ID-token verification path supports RS256, RS512, HS256, and HS512. It does not verify PS*, ES*, or EdDSA signatures.

Expiration leeway in seconds for access token renewal. When set to a value greater than 0, token renewal will take place the set amount of time before token expiration. This avoids errors in case the access token just expires when arriving to the resource server.

If true, execute the authorization flow even when a token has been cached.

If true, enable nonce parameter in authorization request.

If true, notify the authorization server a previously obtained refresh or access token is no longer needed at the revocation endpoint.

Content that should be stored in the session, used to minimize the size of the session data. When not set, everything is included in the session.

Pushed Authorization Request (PAR) configuration, as defined in RFC 9126. With PAR, the gateway sends the authorization request parameters to the identity provider over a back channel and redirects the user agent with only the returned request_uri, so the parameters never travel through the browser.

Configure PAR through this nested object. Flat options use_par, pushed_authorization_request_endpoint, and pushed_authorization_request_endpoint_auth_method are rejected so the plugin validates the endpoint and authentication method.

Available in API7 Enterprise 3.9.18 and 3.10.5, and in APISIX 3.18.0.

Demonstrating Proof-of-Possession (DPoP) configuration, as defined in RFC 9449. The gateway signs a proof JWT for each token request, binding issued access tokens to the configured key. A stolen token cannot be replayed at a DPoP-protected resource endpoint without that key. When par.enabled is also set, the key thumbprint is sent as dpop_jkt on the pushed request.

The gateway acts as the DPoP client for token and user-info calls to the identity provider. This configuration does not validate DPoP proofs on incoming requests from external API clients.

The gateway rejects a token response whose token_type is not DPoP. It retries the token request once after a 400 or 401 response with a DPoP-Nonce header, and the user-info request once after a 401 response with that header.

Configure DPoP through this nested object. Flat options use_dpop, dpop_signing_alg, dpop_private_key, and dpop_public_jwk are rejected so the plugin's DPoP validation and encrypted-field handling apply.

Available in API7 Enterprise 3.9.18 and 3.10.5, and in APISIX 3.18.0.

Valid values: HS256, HS512, RS256, RS512, ES256, or ES512

Algorithm used to sign the client assertion JWT when the endpoint authentication method is client_secret_jwt or private_key_jwt.

Use an HS* algorithm with client_secret_jwt and an RS* or ES* algorithm with private_key_jwt. The algorithm must match client_rsa_private_key and, when the discovery document lists supported client assertion algorithms, must be accepted by the identity provider. One configured algorithm is used for all endpoints.

Available in API7 Enterprise 3.9.18 and 3.10.5, and in APISIX 3.18.0.

Audience claim of the client assertion JWT. When unset, the URL of the endpoint being called is used. Configure this when the gateway reaches an internal endpoint URL but the identity provider expects its external URL as the audience.

Available in API7 Enterprise 3.9.18 and 3.10.5, and in APISIX 3.18.0.