API7 Docs
AuthenticationOpenID Connect

OpenID Connect Configuration

Parameters

See plugin common configurations for configuration options available to all plugins.

This plugin supports referencing parameter values from environment variables using the env:// prefix, or from a secret manager, such as HashiCorp Vault’s KV secrets engine, using the secret:// prefix. For more information, see environment variables in plugin and secrets.

  • client_id — string · required

    Client ID.

  • client_secret — string · optional

    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.

  • discovery — string · required

    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.

  • scope — string · optional · default: openid

    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.

  • required_scopes — array[string] · optional

    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 — string · optional · default: apisix

    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"

  • claim_validator — object · optional

    JWT claim validation configurations.

    • issuer — object · optional

      Claim issuer validation configurations.

      • valid_issuers — array[string] · optional

        An array of trusted JWT issuers. If unconfigured, the issuer from the discovery document is used. In APISIX 3.18.0, bearer JWT verification fails closed while discovery is unavailable because no trusted issuer can be established. API7 Enterprise 3.9.18 and 3.10.5 skip issuer validation in that failure case unless valid_issuers is configured explicitly.

    • audience — object · optional

      Audience claim validation configurations.

      • claim — string · optional · default: aud

        Name of the claim that contains the audience.

      • required — boolean · optional · default: false

        If true, audience claim is required and the name of the claim will be the name defined in claim.

        For instance, suppose claim_validator is configured to be the following:

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

        If the claim custom_claim is not present in the request, you will receive a required audience claim not present error.

      • match_with_client_id — boolean · optional · default: false

        If true, require the audience to match the client ID. If the audience is a string, it must exactly match the client ID. If the audience is an array of strings, at least one value must match. In APISIX 3.18.0, this option also rejects a token that omits the audience claim. API7 Enterprise 3.9.18 and 3.10.5 perform the match only when the claim is present; set required to true there to reject a missing claim.

        This requirement is stated in the OpenID Connect specification to ensure that the token is intended for the specific client.

  • claim_schema — object · optional

    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

  • bearer_only — boolean · optional · default: false

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

  • logout_path — string · optional · default: /logout

    Path to activate the logout.

  • post_logout_redirect_uri — string · optional

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

  • redirect_uri — string · optional · default: ${ngx.var.request_uri}/.apisix/redirect

    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.

  • timeout — integer · optional · default: 3

    Valid values: greater than 0

    Request timeout in seconds.

  • ssl_verify — boolean · optional · default: true

    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.

  • introspection_endpoint — string · optional

    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.

  • introspection_endpoint_auth_method — string · optional · default: client_secret_basic

    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.

  • token_endpoint_auth_method — string · optional · default: client_secret_basic

    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.

  • client_rsa_private_key — string · optional

    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.

  • client_rsa_private_key_id — string · optional

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

  • client_jwt_assertion_expires_in — integer · optional · default: 60

    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 — string · optional

    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.

  • token_signing_alg_values_expected — string · optional

    Algorithm used for signing JWT, such as RS256.

  • set_access_token_header — boolean · optional · default: true

    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.

  • access_token_in_authorization_header — boolean · optional · default: false

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

  • accept_none_alg — boolean · optional · default: false

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

  • use_jwks — boolean · optional · default: false

    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.

  • jwk_expires_in — integer · optional · default: 86400

    Expiration time for JWK cache in seconds.

  • jwt_verification_cache_ignore — boolean · optional · default: false

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

  • cache_segment — string · optional

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

  • use_pkce — boolean · optional · default: false

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

  • set_id_token_header — boolean · optional · default: true

    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.

  • set_userinfo_header — boolean · optional · default: true

    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.

  • set_raw_id_token_header — boolean · optional · default: false

    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.

  • set_refresh_token_header — boolean · optional · default: false

    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 — object · optional

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

    • secret — string · optional

      Valid values: 16 or more characters

      Key used for session encryption and HMAC operation when bearer_only is false.

      When bearer_only is false, this field is required. This requirement was introduced in API7 Enterprise 3.9.2 and APISIX 3.14.0.

      API7 Gateway encrypts the value with AES at rest. APISIX encrypts it before etcd storage when apisix.data_encryption.enable_encrypt_fields is enabled.

    • cookie_name — string · optional

      Name of the session cookie. Maps to the lua-resty-session cookie_name option.

      Available in API7 Enterprise from version 3.9.14 and APISIX from version 3.17.0.

    • cookie_path — string · optional

      Path scope of the session cookie. Maps to the lua-resty-session cookie_path option.

      Available in API7 Enterprise from version 3.9.14 and APISIX from version 3.17.0.

    • cookie_domain — string · optional

      Domain scope of the session cookie. Maps to the lua-resty-session cookie_domain option.

      Available in API7 Enterprise from version 3.9.14 and APISIX from version 3.17.0.

    • cookie_secure — boolean · optional

      If true, set the Secure attribute on the session cookie. Maps to the lua-resty-session cookie_secure option.

      Available in API7 Enterprise from version 3.9.14 and APISIX from version 3.17.0.

    • cookie_http_only — boolean · optional

      If true, set the HttpOnly attribute on the session cookie. Maps to the lua-resty-session cookie_http_only option.

      Available in API7 Enterprise from version 3.9.14 and APISIX from version 3.17.0.

    • cookie_same_site — string · optional

      Valid values: Strict, Lax, None, or Default

      SameSite attribute of the session cookie. Maps to the lua-resty-session cookie_same_site option.

      Available in API7 Enterprise from version 3.9.14 and APISIX from version 3.17.0.

    • idling_timeout — integer · optional

      Idling timeout in seconds, after which an idle session is regenerated. Maps to the lua-resty-session idling_timeout option.

      Available in API7 Enterprise from version 3.9.14 and APISIX from version 3.17.0.

    • rolling_timeout — integer · optional

      Rolling timeout in seconds, after which the session is renewed. Maps to the lua-resty-session rolling_timeout option.

      Available in API7 Enterprise from version 3.9.14 and APISIX from version 3.17.0.

    • absolute_timeout — integer · optional

      Absolute session lifetime in seconds, after which the session expires regardless of activity. Maps to the lua-resty-session absolute_timeout option.

      Available in API7 Enterprise from version 3.9.14 and APISIX from version 3.17.0.

    • cookie — object · optional

      Cookie configurations. Deprecated and kept for backward compatibility with the lua-resty-session 3.x schema. Use the flat session.* options such as cookie_name and absolute_timeout instead.

      • lifetime — integer · optional · default: 3600

        Cookie lifetime in seconds. Deprecated. Mapped to absolute_timeout at runtime when absolute_timeout is not set.

    • storage — string · optional · default: cookie

      Valid values: cookie or redis

      Session storage backend. When set to redis, sessions are stored in Redis instead of cookies.

      Available in API7 Enterprise from version 3.9.15 and APISIX from version 3.16.0.

    • redis — object · optional

      Redis connection configurations. Required when storage is redis.

      Available in API7 Enterprise from version 3.9.15 and APISIX from version 3.16.0.

      • host — string · optional · default: 127.0.0.1

        Redis host.

      • port — integer · optional · default: 6379

        Valid values: greater than or equal to 1

        Redis port.

      • username — string · optional

        Redis username.

      • password — string · optional

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

      • database — integer · optional · default: 0

        Valid values: greater than or equal to 0

        Redis database index.

      • prefix — string · optional · default: sessions

        Prefix for Redis session keys.

      • ssl — boolean · optional · default: false

        If true, use SSL for the Redis connection.

      • ssl_verify — boolean · optional · default: true

        If true, verify the Redis server SSL certificate.

      • server_name — string · optional

        Server name for TLS SNI when connecting to Redis.

      • connect_timeout — integer · optional · default: 1000

        Valid values: greater than or equal to 1

        Redis connection timeout in milliseconds.

      • send_timeout — integer · optional · default: 1000

        Valid values: greater than or equal to 1

        Redis send timeout in milliseconds.

      • read_timeout — integer · optional · default: 1000

        Valid values: greater than or equal to 1

        Redis read timeout in milliseconds.

      • keepalive_timeout — integer · optional · default: 10000

        Valid values: greater than or equal to 1000

        Redis keepalive timeout in milliseconds.

  • unauth_action — string · optional · default: auth

    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.

  • proxy_opts — object · optional

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

    • http_proxy — string · optional

      Proxy server address for HTTP requests, such as http://<proxy_host>:<proxy_port>.

    • https_proxy — string · optional

      Proxy server address for HTTPS requests, such as http://<proxy_host>:<proxy_port>.

    • http_proxy_authorization — string · optional

      Default Proxy-Authorization header value to be used with http_proxy. Can be overridden with custom Proxy-Authorization request header.

    • https_proxy_authorization — string · optional

      Default Proxy-Authorization header value to be used with https_proxy. Cannot be overridden with custom Proxy-Authorization request header since with HTTPS, the authorization is completed when connecting.

    • no_proxy — string · optional

      Comma separated list of hosts that should not be proxied.

  • authorization_params — object · optional

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

  • renew_access_token_on_expiry — boolean · optional · default: true

    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.

  • access_token_expires_in — integer · optional · default: 3600

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

  • refresh_session_interval — integer · optional

    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.

  • iat_slack — integer · optional · default: 120

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

  • introspection_expiry_claim — string · optional · default: exp

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

  • introspection_interval — integer · optional · default: 0

    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.

  • introspection_addon_headers — array[string] · optional

    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.

  • accept_unsupported_alg — boolean · optional · default: true

    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.

  • access_token_expires_leeway — integer · optional · default: 0

    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.

  • force_reauthorize — boolean · optional · default: false

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

  • use_nonce — boolean · optional · default: false

    If true, enable nonce parameter in authorization request.

  • revoke_tokens_on_logout — boolean · optional · default: false

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

  • session_contents — object · optional

    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.

    • id_token — boolean · optional

      If true, store the ID token in session.

    • access_token — boolean · optional

      If true, store the access token and refresh token in session.

    • enc_id_token — boolean · optional

      If true, store the encrypted ID token in session.

    • user — boolean · optional

      If true, store the user info in session.

  • par — object · optional

    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.

    • enabled — boolean · optional · default: false

      If true, push the authorization request to the PAR endpoint instead of sending its parameters in the redirect to the authorization endpoint.

    • endpoint — string · optional

      URL of the identity provider's PAR endpoint. When unset, the endpoint advertised by the provider's discovery document is used.

    • endpoint_auth_method — string · optional

      Valid values: client_secret_basic, client_secret_post, client_secret_jwt, or private_key_jwt

      Client authentication method used on the PAR endpoint. When unset, the method configured for the token endpoint is used. private_key_jwt requires client_rsa_private_key, and client_secret_jwt requires client_secret. The PAR request fails if the selected method cannot be used.

  • dpop — object · optional

    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.

    • enabled — boolean · optional · default: false

      If true, send a DPoP proof JWT with token requests. When enabled, private_key and public_jwk are both required.

    • private_key — string · optional

      PEM-encoded private key used to sign the DPoP proof JWT. When Data Plane data encryption is enabled, this field is encrypted at rest.

    • public_jwk — object · optional

      Public JWK matching private_key, embedded in the proof JWT header. It must not contain private key parameters.

    • signing_alg — string · optional · default: ES256

      Valid values: ES256, RS256, or PS256

      Algorithm used to sign the DPoP proof JWT. It must match the type of the configured key and, when the discovery document lists supported DPoP algorithms, must be accepted by the identity provider.

  • client_jwt_assertion_alg — string · optional

    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.

  • client_jwt_assertion_audience — string · optional

    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.

OpenID Connect

Previous Page

SAML Auth

Next Page