OpenID Connect Configuration

You are browsing unreleased documentation.

Configuration

This plugin is compatible with DB-less mode.

Compatible protocols

The OpenID Connect plugin is compatible with the following protocols:

grpc, grpcs, http, https

Parameters

Here's a list of all the parameters which can be used in this plugin's configuration:

• name or plugin

  string required

  The name of the plugin, in this case openid-connect.

  • If using the Kong Admin API, Konnect API, declarative configuration, or decK files, the field is name.
  • If using the KongPlugin object in Kubernetes, the field is plugin.

• instance_name

  string

  An optional custom name to identify an instance of the plugin, for example openid-connect_my-service.

  The instance name shows up in Kong Manager and in Konnect, so it's useful when running the same plugin in multiple contexts, for example, on multiple services. You can also use it to access a specific plugin instance via the Kong Admin API.

  An instance name must be unique within the following context:

  • Within a workspace for Kong Gateway Enterprise
  • Within a control plane or control plane group for Konnect
  • Globally for Kong Gateway (OSS)

• service.name or service.id

  string

  The name or ID of the service the plugin targets. Set one of these parameters if adding the plugin to a service through the top-level /plugins endpoint. Not required if using /services/{serviceName|Id}/plugins.

• route.name or route.id

  string

  The name or ID of the route the plugin targets. Set one of these parameters if adding the plugin to a route through the top-level /plugins endpoint. Not required if using /routes/{routeName|Id}/plugins.

• enabled

  boolean default: true

  Whether this plugin will be applied.

• config

  record required
  • issuer

    string required

    The discovery endpoint (or the issuer identifier). When there is no discovery endpoint, please also configure config.using_pseudo_issuer=true.

  • using_pseudo_issuer

    boolean default: false

    If the plugin uses a pseudo issuer. When set to true, the plugin will not discover the configuration from the issuer URL specified with config.issuer.

  • discovery_headers_names

    array of type string

    Extra header names passed to the discovery endpoint.

  • discovery_headers_values

    array of type string

    Extra header values passed to the discovery endpoint.

  • extra_jwks_uris

    set of type string

    JWKS URIs whose public keys are trusted (in addition to the keys found with the discovery).

  • rediscovery_lifetime

    number default: 30

    Specifies how long (in seconds) the plugin waits between discovery attempts. Discovery is still triggered on an as-needed basis.

  • auth_methods

    array of type string default: password, client_credentials, authorization_code, bearer, introspection, userinfo, kong_oauth2, refresh_token, session Must be one of: password, client_credentials, authorization_code, bearer, introspection, userinfo, kong_oauth2, refresh_token, session

    Types of credentials/grants to enable.

  • client_id

    array of type string referenceable encrypted

    The client id(s) that the plugin uses when it calls authenticated endpoints on the identity provider.

  • client_secret

    array of type string referenceable encrypted

    The client secret.

  • client_auth

    array of type string Must be one of: client_secret_basic, client_secret_post, client_secret_jwt, private_key_jwt, tls_client_auth, self_signed_tls_client_auth, none

    The default OpenID Connect client authentication method is ‘client_secret_basic’ (using ‘Authorization: Basic’ header), ‘client_secret_post’ (credentials in body), ‘client_secret_jwt’ (signed client assertion in body), ‘private_key_jwt’ (private key-signed assertion), ‘tls_client_auth’ (client certificate), ‘self_signed_tls_client_auth’ (self-signed client certificate), and ‘none’ (no authentication).

  • client_jwk

    array of type record

    The JWK used for the private_key_jwt authentication.

    • issuer

      string

    • kty

      string

    • use

      string

    • key_ops

      array of type string

    • alg

      string

    • kid

      string

    • x5u

      string

    • x5c

      array of type string

    • x5t

      string

    • x5t#S256

      string

    • k

      string referenceable encrypted

    • x

      string

    • y

      string

    • crv

      string

    • n

      string

    • e

      string

    • d

      string referenceable encrypted

    • p

      string referenceable encrypted

    • q

      string referenceable encrypted

    • dp

      string referenceable encrypted

    • dq

      string referenceable encrypted

    • qi

      string referenceable encrypted

    • oth

      string referenceable encrypted

    • r

      string referenceable encrypted

    • t

      string referenceable encrypted

  • client_alg

    array of type string Must be one of: HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512, EdDSA

    The algorithm to use for client_secret_jwt (only HS***) or private_key_jwt authentication.

  • client_arg

    string default: client_id

    The client to use for this request (the selection is made with a request parameter with the same name).

  • redirect_uri

    array of type string

    The redirect URI passed to the authorization and token endpoints.

  • login_redirect_uri

    array of type string referenceable

    Where to redirect the client when login_action is set to redirect.

  • logout_redirect_uri

    array of type string referenceable

    Where to redirect the client after the logout.

  • forbidden_redirect_uri

    array of type string

    Where to redirect the client on forbidden requests.

  • forbidden_error_message

    string default: Forbidden

    The error message for the forbidden requests (when not using the redirection).

  • forbidden_destroy_session

    boolean default: true

    Destroy any active session for the forbidden requests.

  • unauthorized_destroy_session

    boolean default: true

    Destroy any active session for the unauthorized requests.

  • unauthorized_redirect_uri

    array of type string

    Where to redirect the client on unauthorized requests.

  • unauthorized_error_message

    string default: Unauthorized

    The error message for the unauthorized requests (when not using the redirection).

  • unexpected_redirect_uri

    array of type string

    Where to redirect the client when unexpected errors happen with the requests.

  • response_mode

    string default: query Must be one of: query, form_post, fragment, query.jwt, form_post.jwt, fragment.jwt, jwt

    Response mode passed to the authorization endpoint: - query: for parameters in query string - form_post: for parameters in request body - fragment: for parameters in uri fragment (rarely useful as the plugin itself cannot read it) - query.jwt, form_post.jwt, fragment.jwt: similar to query, form_post and fragment but the parameters are encoded in a JWT - jwt: shortcut that indicates the default encoding for the requested response type.

  • response_type

    array of type string default: code

    The response type passed to the authorization endpoint.

  • scopes

    array of type string referenceable default: openid

    The scopes passed to the authorization and token endpoints.

  • audience

    array of type string

    The audience passed to the authorization endpoint.

  • issuers_allowed

    array of type string

    The issuers allowed to be present in the tokens (iss claim).

  • scopes_required

    array of type string

    The scopes (scopes_claim claim) required to be present in the access token (or introspection results) for successful authorization. This config parameter works in both AND / OR cases.

  • scopes_claim

    array of type string default: scope

    The claim that contains the scopes. If multiple values are set, it means the claim is inside a nested object of the token payload.

  • audience_required

    array of type string

    The audiences (audience_claim claim) required to be present in the access token (or introspection results) for successful authorization. This config parameter works in both AND / OR cases.

  • audience_claim

    array of type string default: aud

    The claim that contains the audience. If multiple values are set, it means the claim is inside a nested object of the token payload.

  • groups_required

    array of type string

    The groups (groups_claim claim) required to be present in the access token (or introspection results) for successful authorization. This config parameter works in both AND / OR cases.

  • groups_claim

    array of type string default: groups

    The claim that contains the groups. If multiple values are set, it means the claim is inside a nested object of the token payload.

  • roles_required

    array of type string

    The roles (roles_claim claim) required to be present in the access token (or introspection results) for successful authorization. This config parameter works in both AND / OR cases.

  • roles_claim

    array of type string default: roles

    The claim that contains the roles. If multiple values are set, it means the claim is inside a nested object of the token payload.

  • domains

    array of type string

    The allowed values for the hd claim.

  • max_age

    number

    The maximum age (in seconds) compared to the auth_time claim.

  • authenticated_groups_claim

    array of type string

    The claim that contains authenticated groups. This setting can be used together with ACL plugin, but it also enables IdP managed groups with other applications and integrations. If multiple values are set, it means the claim is inside a nested object of the token payload.

  • pushed_authorization_request_endpoint

    string

    The pushed authorization endpoint. If set it overrides the value in pushed_authorization_request_endpoint returned by the discovery endpoint.

  • pushed_authorization_request_endpoint_auth_method

    string Must be one of: client_secret_basic, client_secret_post, client_secret_jwt, private_key_jwt, tls_client_auth, self_signed_tls_client_auth, none

    The pushed authorization request endpoint authentication method: client_secret_basic, client_secret_post, client_secret_jwt, private_key_jwt, tls_client_auth, self_signed_tls_client_auth, or none: do not authenticate

  • require_pushed_authorization_requests

    boolean

    Forcibly enable or disable the pushed authorization requests. When not set the value is determined through the discovery using the value of require_pushed_authorization_requests (which defaults to false).

  • require_proof_key_for_code_exchange

    boolean

    Forcibly enable or disable the proof key for code exchange. When not set the value is determined through the discovery using the value of code_challenge_methods_supported, and enabled automatically (in case the code_challenge_methods_supported is missing, the PKCE will not be enabled).

  • require_signed_request_object

    boolean

    Forcibly enable or disable the usage of signed request object on authorization or pushed authorization endpoint. When not set the value is determined through the discovery using the value of require_signed_request_object, and enabled automatically (in case the require_signed_request_object is missing, the feature will not be enabled).

  • authorization_endpoint

    string

    The authorization endpoint. If set it overrides the value in authorization_endpoint returned by the discovery endpoint.

  • authorization_query_args_names

    array of type string

    Extra query argument names passed to the authorization endpoint.

  • authorization_query_args_values

    array of type string

    Extra query argument values passed to the authorization endpoint.

  • authorization_query_args_client

    array of type string

    Extra query arguments passed from the client to the authorization endpoint.

  • authorization_rolling_timeout

    number default: 600

    Specifies how long the session used for the authorization code flow can be used in seconds until it needs to be renewed. 0 disables the checks and rolling.

  • authorization_cookie_name

    string default: authorization

    The authorization cookie name.

  • authorization_cookie_path

    string default: / starts_with: /

    The authorization cookie Path flag.

  • authorization_cookie_domain

    string

    The authorization cookie Domain flag.

  • authorization_cookie_same_site

    string default: Default Must be one of: Strict, Lax, None, Default

    Controls whether a cookie is sent with cross-origin requests, providing some protection against cross-site request forgery attacks.

  • authorization_cookie_http_only

    boolean default: true

    Forbids JavaScript from accessing the cookie, for example, through the Document.cookie property.

  • authorization_cookie_secure

    boolean

    Cookie is only sent to the server when a request is made with the https: scheme (except on localhost), and therefore is more resistant to man-in-the-middle attacks.

  • preserve_query_args

    boolean default: false

    With this parameter, you can preserve request query arguments even when doing authorization code flow.

  • token_endpoint

    string

    The token endpoint. If set it overrides the value in token_endpoint returned by the discovery endpoint.

  • token_endpoint_auth_method

    string Must be one of: client_secret_basic, client_secret_post, client_secret_jwt, private_key_jwt, tls_client_auth, self_signed_tls_client_auth, none

    The token endpoint authentication method: client_secret_basic, client_secret_post, client_secret_jwt, private_key_jwt, tls_client_auth, self_signed_tls_client_auth, or none: do not authenticate

  • token_headers_names

    array of type string

    Extra header names passed to the token endpoint.

  • token_headers_values

    array of type string

    Extra header values passed to the token endpoint.

  • token_headers_client

    array of type string

    Extra headers passed from the client to the token endpoint.

  • token_headers_replay

    array of type string

    The names of token endpoint response headers to forward to the downstream client.

  • token_headers_prefix

    string

    Add a prefix to the token endpoint response headers before forwarding them to the downstream client.

  • token_headers_grants

    array of type string Must be one of: password, client_credentials, authorization_code, refresh_token

    Enable the sending of the token endpoint response headers only with certain grants: - password: with OAuth password grant - client_credentials: with OAuth client credentials grant - authorization_code: with authorization code flow - refresh_token with refresh token grant.

  • token_post_args_names

    array of type string

    Extra post argument names passed to the token endpoint.

  • token_post_args_values

    array of type string

    Extra post argument values passed to the token endpoint.

  • token_post_args_client

    array of type string

    Pass extra arguments from the client to the OpenID-Connect plugin. If arguments exist, the client can pass them using: - Query parameters - Request Body - Request Header This parameter can be used with scope values, like this: config.token_post_args_client=scope In this case, the token would take the scope value from the query parameter or from the request body or from the header and send it to the token endpoint.

  • introspection_endpoint

    string

    The introspection endpoint. If set it overrides the value in introspection_endpoint returned by the discovery endpoint.

  • introspection_endpoint_auth_method

    string Must be one of: client_secret_basic, client_secret_post, client_secret_jwt, private_key_jwt, tls_client_auth, self_signed_tls_client_auth, none

    The introspection endpoint authentication method: : client_secret_basic, client_secret_post, client_secret_jwt, private_key_jwt, tls_client_auth, self_signed_tls_client_auth, or none: do not authenticate

  • introspection_hint

    string default: access_token

    Introspection hint parameter value passed to the introspection endpoint.

  • introspection_check_active

    boolean default: true

    Check that the introspection response has an active claim with a value of true.

  • introspection_accept

    string default: application/json Must be one of: application/json, application/token-introspection+jwt, application/jwt

    The value of Accept header for introspection requests: - application/json: introspection response as JSON - application/token-introspection+jwt: introspection response as JWT (from the current IETF draft document) - application/jwt: introspection response as JWT (from the obsolete IETF draft document).

  • introspection_headers_names

    array of type string

    Extra header names passed to the introspection endpoint.

  • introspection_headers_values

    array of type string referenceable encrypted

    Extra header values passed to the introspection endpoint.

  • introspection_headers_client

    array of type string

    Extra headers passed from the client to the introspection endpoint.

  • introspection_post_args_names

    array of type string

    Extra post argument names passed to the introspection endpoint.

  • introspection_post_args_values

    array of type string

    Extra post argument values passed to the introspection endpoint.

  • introspection_post_args_client

    array of type string

    Extra post arguments passed from the client to the introspection endpoint.

  • introspection_post_args_client_headers

    array of type string

    Extra post arguments passed from the client headers to the introspection endpoint.

  • introspect_jwt_tokens

    boolean default: false

    Specifies whether to introspect the JWT access tokens (can be used to check for revocations).

  • revocation_endpoint

    string

    The revocation endpoint. If set it overrides the value in revocation_endpoint returned by the discovery endpoint.

  • revocation_endpoint_auth_method

    string Must be one of: client_secret_basic, client_secret_post, client_secret_jwt, private_key_jwt, tls_client_auth, self_signed_tls_client_auth, none

    The revocation endpoint authentication method: : client_secret_basic, client_secret_post, client_secret_jwt, private_key_jwt, tls_client_auth, self_signed_tls_client_auth, or none: do not authenticate

  • end_session_endpoint

    string

    The end session endpoint. If set it overrides the value in end_session_endpoint returned by the discovery endpoint.

  • userinfo_endpoint

    string

    The user info endpoint. If set it overrides the value in userinfo_endpoint returned by the discovery endpoint.

  • userinfo_accept

    string default: application/json Must be one of: application/json, application/jwt

    The value of Accept header for user info requests: - application/json: user info response as JSON - application/jwt: user info response as JWT (from the obsolete IETF draft document).

  • userinfo_headers_names

    array of type string

    Extra header names passed to the user info endpoint.

  • userinfo_headers_values

    array of type string

    Extra header values passed to the user info endpoint.

  • userinfo_headers_client

    array of type string

    Extra headers passed from the client to the user info endpoint.

  • userinfo_query_args_names

    array of type string

    Extra query argument names passed to the user info endpoint.

  • userinfo_query_args_values

    array of type string

    Extra query argument values passed to the user info endpoint.

  • userinfo_query_args_client

    array of type string

    Extra query arguments passed from the client to the user info endpoint.

  • token_exchange_endpoint

    string

    The token exchange endpoint.

  • session_secret

    string referenceable encrypted

    The session secret.

  • session_audience

    string default: default

    The session audience, which is the intended target application. For example "my-application".

  • session_cookie_name

    string default: session

    The session cookie name.

  • session_remember

    boolean default: false

    Enables or disables persistent sessions.

  • session_remember_cookie_name

    string default: remember

    Persistent session cookie name. Use with the remember configuration parameter.

  • session_remember_rolling_timeout

    number default: 604800

    Specifies how long the persistent session is considered valid in seconds. 0 disables the checks and rolling.

  • session_remember_absolute_timeout

    number default: 2592000

    Limits how long the persistent session can be renewed in seconds, until re-authentication is required. 0 disables the checks.

  • session_idling_timeout

    number default: 900

    Specifies how long the session can be inactive until it is considered invalid in seconds. 0 disables the checks and touching.

  • session_rolling_timeout

    number default: 3600

    Specifies how long the session can be used in seconds until it needs to be renewed. 0 disables the checks and rolling.

  • session_absolute_timeout

    number default: 86400

    Limits how long the session can be renewed in seconds, until re-authentication is required. 0 disables the checks.

  • session_cookie_path

    string default: / starts_with: /

    The session cookie Path flag.

  • session_cookie_domain

    string

    The session cookie Domain flag.

  • session_cookie_same_site

    string default: Lax Must be one of: Strict, Lax, None, Default

    Controls whether a cookie is sent with cross-origin requests, providing some protection against cross-site request forgery attacks.

  • session_cookie_http_only

    boolean default: true

    Forbids JavaScript from accessing the cookie, for example, through the Document.cookie property.

  • session_cookie_secure

    boolean

    Cookie is only sent to the server when a request is made with the https: scheme (except on localhost), and therefore is more resistant to man-in-the-middle attacks.

  • session_request_headers

    set of type string Must be one of: id, audience, subject, timeout, idling-timeout, rolling-timeout, absolute-timeout

    Set of headers to send to upstream, use id, audience, subject, timeout, idling-timeout, rolling-timeout, absolute-timeout. E.g. [ "id", "timeout" ] will set Session-Id and Session-Timeout request headers.

  • session_response_headers

    set of type string Must be one of: id, audience, subject, timeout, idling-timeout, rolling-timeout, absolute-timeout

    Set of headers to send to downstream, use id, audience, subject, timeout, idling-timeout, rolling-timeout, absolute-timeout. E.g. [ "id", "timeout" ] will set Session-Id and Session-Timeout response headers.

  • session_storage

    string default: cookie Must be one of: cookie, memcache, memcached, redis

    The session storage for session data: - cookie: stores session data with the session cookie (the session cannot be invalidated or revoked without changing session secret, but is stateless, and doesn’t require a database) - memcache: stores session data in memcached - redis: stores session data in Redis.

  • session_store_metadata

    boolean default: false

    Configures whether or not session metadata should be stored. This metadata includes information about the active sessions for a specific audience belonging to a specific subject.

  • session_enforce_same_subject

    boolean default: false

    When set to true, audiences are forced to share the same subject.

  • session_hash_subject

    boolean default: false

    When set to true, the value of subject is hashed before being stored. Only applies when session_store_metadata is enabled.

  • session_hash_storage_key

    boolean default: false

    When set to true, the storage key (session ID) is hashed for extra security. Hashing the storage key means it is impossible to decrypt data from the storage without a cookie.

  • session_memcached_prefix

    string

    The memcached session key prefix.

  • session_memcached_socket

    string

    The memcached unix socket path.

  • session_memcached_host

    string default: 127.0.0.1

    The memcached host.

  • session_memcached_port

    integer default: 11211 between: 0 65535

    The memcached port.

  • redis

    record required
    • host

      string default: 127.0.0.1

      A string representing a host name, such as example.com.

    • port

      integer default: 6379 between: 0 65535

      An integer representing a port number between 0 and 65535, inclusive.

    • connect_timeout

      integer default: 2000 between: 0 2147483646

      An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.

    • send_timeout

      integer default: 2000 between: 0 2147483646

      An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.

    • read_timeout

      integer default: 2000 between: 0 2147483646

      An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.

    • username

      string referenceable

      Username to use for Redis connections. If undefined, ACL authentication won’t be performed. This requires Redis v6.0.0+. To be compatible with Redis v5.x.y, you can set it to default.

    • password

      string referenceable encrypted

      Password to use for Redis connections. If undefined, no AUTH commands are sent to Redis.

    • sentinel_username

      string referenceable

      Sentinel username to authenticate with a Redis Sentinel instance. If undefined, ACL authentication won’t be performed. This requires Redis v6.2.0+.

    • sentinel_password

      string referenceable encrypted

      Sentinel password to authenticate with a Redis Sentinel instance. If undefined, no AUTH commands are sent to Redis Sentinels.

    • database

      integer default: 0

      Database to use for the Redis connection when using the redis strategy

    • keepalive_pool_size

      integer default: 256 between: 1 2147483646

      The size limit for every cosocket connection pool associated with every remote server, per worker process. If neither keepalive_pool_size nor keepalive_backlog is specified, no pool is created. If keepalive_pool_size isn’t specified but keepalive_backlog is specified, then the pool uses the default value. Try to increase (e.g. 512) this value if latency is high or throughput is low.

    • keepalive_backlog

      integer between: 0 2147483646

      Limits the total number of opened connections for a pool. If the connection pool is full, connection queues above the limit go into the backlog queue. If the backlog queue is full, subsequent connect operations fail and return nil. Queued operations (subject to set timeouts) resume once the number of connections in the pool is less than keepalive_pool_size. If latency is high or throughput is low, try increasing this value. Empirically, this value is larger than keepalive_pool_size.

    • sentinel_master

      string

      Sentinel master to use for Redis connections. Defining this value implies using Redis Sentinel.

    • sentinel_role

      string Must be one of: master, slave, any

      Sentinel role to use for Redis connections when the redis strategy is defined. Defining this value implies using Redis Sentinel.

    • sentinel_nodes

      array of type record len_min: 1

      Sentinel node addresses to use for Redis connections when the redis strategy is defined. Defining this field implies using a Redis Sentinel. The minimum length of the array is 1 element.

      • host

        string required default: 127.0.0.1

        A string representing a host name, such as example.com.

      • port

        integer default: 6379 between: 0 65535

        An integer representing a port number between 0 and 65535, inclusive.

    • cluster_nodes

      array of type record len_min: 1

      Cluster addresses to use for Redis connections when the redis strategy is defined. Defining this field implies using a Redis Cluster. The minimum length of the array is 1 element.

      • ip

        string required default: 127.0.0.1

        A string representing a host name, such as example.com.

      • port

        integer default: 6379 between: 0 65535

        An integer representing a port number between 0 and 65535, inclusive.

    • ssl

      boolean default: false

      If set to true, uses SSL to connect to Redis.

    • ssl_verify

      boolean default: false

      If set to true, verifies the validity of the server SSL certificate. If setting this parameter, also configure lua_ssl_trusted_certificate in kong.conf to specify the CA (or server) certificate used by your Redis server. You may also need to configure lua_ssl_verify_depth accordingly.

    • server_name

      string

      A string representing an SNI (server name indication) value for TLS.

    • cluster_max_redirections

      integer default: 5

      Maximum retry attempts for redirection.

    • connection_is_proxied

      boolean default: false

      If the connection to Redis is proxied (e.g. Envoy), set it true. Set the host and port to point to the proxy address.

    • prefix

      string

      The Redis session key prefix.

    • socket

      string

      The Redis unix socket path.

  • reverify

    boolean default: false

    Specifies whether to always verify tokens stored in the session.

  • jwt_session_claim

    string default: sid

    The claim to match against the JWT session cookie.

  • jwt_session_cookie

    string

    The name of the JWT session cookie.

  • bearer_token_param_type

    array of type string default: header, query, body Must be one of: header, cookie, query, body

    Where to look for the bearer token: - header: search the Authorization, access-token, and x-access-token HTTP headers - query: search the URL’s query string - body: search the HTTP request body - cookie: search the HTTP request cookies specified with config.bearer_token_cookie_name.

  • bearer_token_cookie_name

    string

    The name of the cookie in which the bearer token is passed.

  • client_credentials_param_type

    array of type string default: header, query, body Must be one of: header, query, body

    Where to look for the client credentials: - header: search the HTTP headers - query: search the URL’s query string - body: search from the HTTP request body.

  • password_param_type

    array of type string default: header, query, body Must be one of: header, query, body

    Where to look for the username and password: - header: search the HTTP headers - query: search the URL’s query string - body: search the HTTP request body.

  • id_token_param_type

    array of type string default: header, query, body Must be one of: header, query, body

    Where to look for the id token: - header: search the HTTP headers - query: search the URL’s query string - body: search the HTTP request body.

  • id_token_param_name

    string

    The name of the parameter used to pass the id token.

  • refresh_token_param_type

    array of type string default: header, query, body Must be one of: header, query, body

    Where to look for the refresh token: - header: search the HTTP headers - query: search the URL’s query string - body: search the HTTP request body.

  • refresh_token_param_name

    string

    The name of the parameter used to pass the refresh token.

  • refresh_tokens

    boolean default: true

    Specifies whether the plugin should try to refresh (soon to be) expired access tokens if the plugin has a refresh_token available.

  • upstream_headers_claims

    array of type string

    The upstream header claims. Only top level claims are supported.

  • upstream_headers_names

    array of type string

    The upstream header names for the claim values.

  • upstream_access_token_header

    string default: authorization:bearer

    The upstream access token header.

  • upstream_access_token_jwk_header

    string

    The upstream access token JWK header.

  • upstream_id_token_header

    string

    The upstream id token header.

  • upstream_id_token_jwk_header

    string

    The upstream id token JWK header.

  • upstream_refresh_token_header

    string

    The upstream refresh token header.

  • upstream_user_info_header

    string

    The upstream user info header.

  • upstream_user_info_jwt_header

    string

    The upstream user info JWT header (in case the user info returns a JWT response).

  • upstream_introspection_header

    string

    The upstream introspection header.

  • upstream_introspection_jwt_header

    string

    The upstream introspection JWT header.

  • upstream_session_id_header

    string

    The upstream session id header.

  • downstream_headers_claims

    array of type string

    The downstream header claims. If multiple values are set, it means the claim is inside a nested object of the token payload.

  • downstream_headers_names

    array of type string

    The downstream header names for the claim values.

  • downstream_access_token_header

    string

    The downstream access token header.

  • downstream_access_token_jwk_header

    string

    The downstream access token JWK header.

  • downstream_id_token_header

    string

    The downstream id token header.

  • downstream_id_token_jwk_header

    string

    The downstream id token JWK header.

  • downstream_refresh_token_header

    string

    The downstream refresh token header.

  • downstream_user_info_header

    string

    The downstream user info header.

  • downstream_user_info_jwt_header

    string

    The downstream user info JWT header (in case the user info returns a JWT response).

  • downstream_introspection_header

    string

    The downstream introspection header.

  • downstream_introspection_jwt_header

    string

    The downstream introspection JWT header.

  • downstream_session_id_header

    string

    The downstream session id header.

  • login_methods

    array of type string default: authorization_code Must be one of: password, client_credentials, authorization_code, bearer, introspection, userinfo, kong_oauth2, refresh_token, session

    Enable login functionality with specified grants.

  • login_action

    string default: upstream Must be one of: upstream, response, redirect

    What to do after successful login: - upstream: proxy request to upstream service - response: terminate request with a response - redirect: redirect to a different location.

  • login_tokens

    array of type string default: id_token Must be one of: id_token, access_token, refresh_token, tokens, introspection

    What tokens to include in response body or redirect query string or fragment: - id_token: include id token - access_token: include access token - refresh_token: include refresh token - tokens: include the full token endpoint response - introspection: include introspection response.

  • login_redirect_mode

    string default: fragment Must be one of: query, fragment

    Where to place login_tokens when using redirect login_action: - query: place tokens in query string - fragment: place tokens in url fragment (not readable by servers).

  • logout_query_arg

    string

    The request query argument that activates the logout.

  • logout_post_arg

    string

    The request body argument that activates the logout.

  • logout_uri_suffix

    string

    The request URI suffix that activates the logout.

  • logout_methods

    array of type string default: POST, DELETE Must be one of: POST, GET, DELETE

    The request methods that can activate the logout: - POST: HTTP POST method - GET: HTTP GET method - DELETE: HTTP DELETE method.

  • logout_revoke

    boolean default: false

    Revoke tokens as part of the logout.

    For more granular token revocation, you can also adjust the logout_revoke_access_token and logout_revoke_refresh_token parameters.

  • logout_revoke_access_token

    boolean default: true

    Revoke the access token as part of the logout. Requires logout_revoke to be set to true.

  • logout_revoke_refresh_token

    boolean default: true

    Revoke the refresh token as part of the logout. Requires logout_revoke to be set to true.

  • consumer_claim

    array of type string

    The claim used for consumer mapping. If multiple values are set, it means the claim is inside a nested object of the token payload.

  • consumer_by

    array of type string default: username, custom_id Must be one of: id, username, custom_id

    Consumer fields used for mapping: - id: try to find the matching Consumer by id - username: try to find the matching Consumer by username - custom_id: try to find the matching Consumer by custom_id.

  • consumer_optional

    boolean default: false

    Do not terminate the request if consumer mapping fails.

  • credential_claim

    array of type string default: sub

    The claim used to derive virtual credentials (e.g. to be consumed by the rate-limiting plugin), in case the consumer mapping is not used. If multiple values are set, it means the claim is inside a nested object of the token payload.

  • anonymous

    string

    An optional string (consumer UUID or username) value that functions as an “anonymous” consumer if authentication fails. If empty (default null), requests that fail authentication will return a 4xx HTTP status code. This value must refer to the consumer id or username attribute, and not its custom_id.

  • run_on_preflight

    boolean default: true

    Specifies whether to run this plugin on pre-flight (OPTIONS) requests.

  • leeway

    number default: 0

    Defines leeway time (in seconds) for auth_time, exp, iat, and nbf claims

  • verify_parameters

    boolean default: false

    Verify plugin configuration against discovery.

  • verify_nonce

    boolean default: true

    Verify nonce on authorization code flow.

  • verify_claims

    boolean default: true

    Verify tokens for standard claims.

  • verify_signature

    boolean default: true

    Verify signature of tokens.

  • ignore_signature

    array of type string Must be one of: password, client_credentials, authorization_code, refresh_token, session, introspection, userinfo

    Skip the token signature verification on certain grants: - password: OAuth password grant - client_credentials: OAuth client credentials grant - authorization_code: authorization code flow - refresh_token: OAuth refresh token grant - session: session cookie authentication - introspection: OAuth introspection - userinfo: OpenID Connect user info endpoint authentication.

  • enable_hs_signatures

    boolean default: false

    Enable shared secret, for example, HS256, signatures (when disabled they will not be accepted).

  • disable_session

    array of type string Must be one of: password, client_credentials, authorization_code, bearer, introspection, userinfo, kong_oauth2, refresh_token, session

    Disable issuing the session cookie with the specified grants.

  • cache_ttl

    number default: 3600

    The default cache ttl in seconds that is used in case the cached object does not specify the expiry.

  • cache_ttl_max

    number

    The maximum cache ttl in seconds (enforced).

  • cache_ttl_min

    number

    The minimum cache ttl in seconds (enforced).

  • cache_ttl_neg

    number

    The negative cache ttl in seconds.

  • cache_ttl_resurrect

    number

    The resurrection ttl in seconds.

  • cache_tokens

    boolean default: true

    Cache the token endpoint requests.

  • cache_tokens_salt

    string

    Salt used for generating the cache key that is used for caching the token endpoint requests.

  • cache_introspection

    boolean default: true

    Cache the introspection endpoint requests.

  • cache_token_exchange

    boolean default: true

    Cache the token exchange endpoint requests.

  • cache_user_info

    boolean default: true

    Cache the user info requests.

  • search_user_info

    boolean default: false

    Specify whether to use the user info endpoint to get additional claims for consumer mapping, credential mapping, authenticated groups, and upstream and downstream headers.

  • hide_credentials

    boolean default: false

    Remove the credentials used for authentication from the request. If multiple credentials are sent with the same request, the plugin will remove those that were used for successful authentication.

  • http_version

    number default: 1.1

    The HTTP version used for the requests by this plugin: - 1.1: HTTP 1.1 (the default) - 1.0: HTTP 1.0.

  • http_proxy

    string

    The HTTP proxy.

  • http_proxy_authorization

    string referenceable

    The HTTP proxy authorization.

  • https_proxy

    string

    The HTTPS proxy.

  • https_proxy_authorization

    string referenceable

    The HTTPS proxy authorization.

  • no_proxy

    string

    Do not use proxy with these hosts.

  • keepalive

    boolean default: true

    Use keepalive with the HTTP client.

  • ssl_verify

    boolean default: false

    Verify identity provider server certificate. If set to true, the plugin uses the CA certificate set in the kong.conf config parameter lua_ssl_trusted_certificate.

  • timeout

    number default: 10000

    Network IO timeout in milliseconds.

  • display_errors

    boolean default: false

    Display errors on failure responses.

  • by_username_ignore_case

    boolean default: false

    If consumer_by is set to username, specify whether username can match consumers case-insensitively.

  • resolve_distributed_claims

    boolean default: false

    Distributed claims are represented by the _claim_names and _claim_sources members of the JSON object containing the claims. If this parameter is set to true, the plugin explicitly resolves these distributed claims.

  • expose_error_code

    boolean default: true

    Specifies whether to expose the error code header, as defined in RFC 6750. If an authorization request fails, this header is sent in the response. Set to false to disable.

  • token_cache_key_include_scope

    boolean default: false

    Include the scope in the token cache key, so token with different scopes are considered diffrent tokens.

  • introspection_token_param_name

    string default: token

    Designate token’s parameter name for introspection.

  • revocation_token_param_name

    string default: token

    Designate token’s parameter name for revocation.

  • proof_of_possession_mtls

    string default: off Must be one of: off, strict, optional

    Enable mtls proof of possession. If set to strict, all tokens (from supported auth_methods: bearer, introspection, and session granted with bearer or introspection) are verified, if set to optional, only tokens that contain the certificate hash claim are verified. If the verification fails, the request will be rejected with 401.

  • proof_of_possession_auth_methods_validation

    boolean default: true

    If set to true, only the auth_methods that are compatible with Proof of Possession (PoP) can be configured when PoP is enabled. If set to false, all auth_methods will be configurable and PoP checks will be silently skipped for those auth_methods that are not compatible with PoP.

  • tls_client_auth_cert_id

    string

    ID of the Certificate entity representing the client certificate to use for mTLS client authentication for connections between Kong and the Auth Server.

  • tls_client_auth_ssl_verify

    boolean default: true

    Verify identity provider server certificate during mTLS client authentication.

  • mtls_token_endpoint

    string

    Alias for the token endpoint to be used for mTLS client authentication. If set it overrides the value in mtls_endpoint_aliases returned by the discovery endpoint.

  • mtls_introspection_endpoint

    string

    Alias for the introspection endpoint to be used for mTLS client authentication. If set it overrides the value in mtls_endpoint_aliases returned by the discovery endpoint.

  • mtls_revocation_endpoint

    string

    Alias for the introspection endpoint to be used for mTLS client authentication. If set it overrides the value in mtls_endpoint_aliases returned by the discovery endpoint.

  • proof_of_possession_dpop

    string default: off Must be one of: off, strict, optional

    Enable Demonstrating Proof-of-Possession (DPoP). If set to strict, all request are verified despite the presence of the DPoP key claim (cnf.jkt). If set to optional, only tokens bound with DPoP’s key are verified with the proof.

  • dpop_use_nonce

    boolean default: false

    Specifies whether to challenge the client with a nonce value for DPoP proof. When enabled it will also be used to calculate the DPoP proof lifetime.

  • dpop_proof_lifetime

    number default: 300

    Specifies the lifetime in seconds of the DPoP proof. It determines how long the same proof can be used after creation. The creation time is determined by the nonce creation time if a nonce is used, and the iat claim otherwise.

  • claims_forbidden

    array of type string

    If given, these claims are forbidden in the token payload.

  • cluster_cache_strategy

    string default: off Must be one of: off, redis

    The strategy to use for the cluster cache. If set, the plugin will share cache with nodes configured with the same strategy backend. Currentlly only introspection cache is shared.

  • cluster_cache_redis

    record required
    • host

      string default: 127.0.0.1

      A string representing a host name, such as example.com.

    • port

      integer default: 6379 between: 0 65535

      An integer representing a port number between 0 and 65535, inclusive.

    • connect_timeout

      integer default: 2000 between: 0 2147483646

      An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.

    • send_timeout

      integer default: 2000 between: 0 2147483646

      An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.

    • read_timeout

      integer default: 2000 between: 0 2147483646

      An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.

    • username

      string referenceable

      Username to use for Redis connections. If undefined, ACL authentication won’t be performed. This requires Redis v6.0.0+. To be compatible with Redis v5.x.y, you can set it to default.

    • password

      string referenceable encrypted

      Password to use for Redis connections. If undefined, no AUTH commands are sent to Redis.

    • sentinel_username

      string referenceable

      Sentinel username to authenticate with a Redis Sentinel instance. If undefined, ACL authentication won’t be performed. This requires Redis v6.2.0+.

    • sentinel_password

      string referenceable encrypted

      Sentinel password to authenticate with a Redis Sentinel instance. If undefined, no AUTH commands are sent to Redis Sentinels.

    • database

      integer default: 0

      Database to use for the Redis connection when using the redis strategy

    • keepalive_pool_size

      integer default: 256 between: 1 2147483646

      The size limit for every cosocket connection pool associated with every remote server, per worker process. If neither keepalive_pool_size nor keepalive_backlog is specified, no pool is created. If keepalive_pool_size isn’t specified but keepalive_backlog is specified, then the pool uses the default value. Try to increase (e.g. 512) this value if latency is high or throughput is low.

    • keepalive_backlog

      integer between: 0 2147483646

      Limits the total number of opened connections for a pool. If the connection pool is full, connection queues above the limit go into the backlog queue. If the backlog queue is full, subsequent connect operations fail and return nil. Queued operations (subject to set timeouts) resume once the number of connections in the pool is less than keepalive_pool_size. If latency is high or throughput is low, try increasing this value. Empirically, this value is larger than keepalive_pool_size.

    • sentinel_master

      string

      Sentinel master to use for Redis connections. Defining this value implies using Redis Sentinel.

    • sentinel_role

      string Must be one of: master, slave, any

      Sentinel role to use for Redis connections when the redis strategy is defined. Defining this value implies using Redis Sentinel.

    • sentinel_nodes

      array of type record len_min: 1

      Sentinel node addresses to use for Redis connections when the redis strategy is defined. Defining this field implies using a Redis Sentinel. The minimum length of the array is 1 element.

      • host

        string required default: 127.0.0.1

        A string representing a host name, such as example.com.

      • port

        integer default: 6379 between: 0 65535

        An integer representing a port number between 0 and 65535, inclusive.

    • cluster_nodes

      array of type record len_min: 1

      Cluster addresses to use for Redis connections when the redis strategy is defined. Defining this field implies using a Redis Cluster. The minimum length of the array is 1 element.

      • ip

        string required default: 127.0.0.1

        A string representing a host name, such as example.com.

      • port

        integer default: 6379 between: 0 65535

        An integer representing a port number between 0 and 65535, inclusive.

    • ssl

      boolean default: false

      If set to true, uses SSL to connect to Redis.

    • ssl_verify

      boolean default: false

      If set to true, verifies the validity of the server SSL certificate. If setting this parameter, also configure lua_ssl_trusted_certificate in kong.conf to specify the CA (or server) certificate used by your Redis server. You may also need to configure lua_ssl_verify_depth accordingly.

    • server_name

      string

      A string representing an SNI (server name indication) value for TLS.

    • cluster_max_redirections

      integer default: 5

      Maximum retry attempts for redirection.

    • connection_is_proxied

      boolean default: false

      If the connection to Redis is proxied (e.g. Envoy), set it true. Set the host and port to point to the proxy address.

• authorization_cookie_lifetime

  number
  Deprecation notice: openid-connect: config.authorization_cookie_lifetime is deprecated, please use config.authorization_rolling_timeout instead. This field is planned to be removed in version 4.0.

• authorization_cookie_samesite

  string
  Deprecation notice: openid-connect: config.authorization_cookie_samesite is deprecated, please use config.authorization_cookie_same_site instead. This field is planned to be removed in version 4.0.

• authorization_cookie_httponly

  boolean
  Deprecation notice: openid-connect: config.authorization_cookie_httponly is deprecated, please use config.authorization_cookie_http_only instead. This field is planned to be removed in version 4.0.

• session_cookie_lifetime

  number
  Deprecation notice: openid-connect: config.session_cookie_lifetime is deprecated, please use config.session_rolling_timeout instead. This field is planned to be removed in version 4.0.

• session_cookie_idletime

  number
  Deprecation notice: openid-connect: config.session_cookie_idletime is deprecated, please use config.session_idling_timeout instead. This field is planned to be removed in version 4.0.

• session_cookie_samesite

  string
  Deprecation notice: openid-connect: config.session_cookie_samesite is deprecated, please use config.session_cookie_same_site instead. This field is planned to be removed in version 4.0.

• session_cookie_httponly

  boolean
  Deprecation notice: openid-connect: config.session_cookie_httponly is deprecated, please use config.session_cookie_http_only instead. This field is planned to be removed in version 4.0.

• session_memcache_prefix

  string
  Deprecation notice: openid-connect: config.session_memcache_prefix is deprecated, please use config.session_memcached_prefix instead. This field is planned to be removed in version 4.0.

• session_memcache_socket

  string
  Deprecation notice: openid-connect: config.session_memcache_socket is deprecated, please use config.session_memcached_socket instead. This field is planned to be removed in version 4.0.

• session_memcache_host

  string
  Deprecation notice: openid-connect: config.session_memcache_host is deprecated, please use config.session_memcached_host instead. This field is planned to be removed in version 4.0.

• session_memcache_port

  integer
  Deprecation notice: openid-connect: config.session_memcache_port is deprecated, please use config.session_memcached_port instead. This field is planned to be removed in version 4.0.

• session_cookie_renew

  number
  Deprecation notice: openid-connect: config.session_cookie_renew option does not exist anymore. This field is planned to be removed in version 4.0.

• session_cookie_maxsize

  integer
  Deprecation notice: openid-connect: config.session_cookie_maxsize option does not exist anymore. This field is planned to be removed in version 4.0.

• session_strategy

  string
  Deprecation notice: openid-connect: config.session_strategy option does not exist anymore. This field is planned to be removed in version 4.0.

• session_compressor

  string
  Deprecation notice: openid-connect: config.session_compressor option does not exist anymore. This field is planned to be removed in version 4.0.

• session_redis_prefix

  string
  Deprecation notice: openid-connect: config.session_redis_prefix is deprecated, please use config.redis.prefix instead. This field is planned to be removed in version 4.0.

• session_redis_socket

  string
  Deprecation notice: openid-connect: config.session_redis_socket is deprecated, please use config.redis.socket instead. This field is planned to be removed in version 4.0.

• session_redis_host

  string
  Deprecation notice: openid-connect: config.session_redis_host is deprecated, please use config.redis.host instead. This field is planned to be removed in version 4.0.

• session_redis_port

  integer
  Deprecation notice: openid-connect: config.session_redis_port is deprecated, please use config.redis.port instead. This field is planned to be removed in version 4.0.

• session_redis_username

  string
  Deprecation notice: openid-connect: config.redis_host is deprecated, please use config.redis.host instead. This field is planned to be removed in version 4.0.

• session_redis_password

  string
  Deprecation notice: openid-connect: config.session_redis_password is deprecated, please use config.redis.password instead. This field is planned to be removed in version 4.0.

• session_redis_connect_timeout

  integer
  Deprecation notice: openid-connect: config.session_redis_connect_timeout is deprecated, please use config.redis.connect_timeout instead. This field is planned to be removed in version 4.0.

• session_redis_read_timeout

  integer
  Deprecation notice: openid-connect: config.session_redis_read_timeout is deprecated, please use config.redis.read_timeout instead. This field is planned to be removed in version 4.0.

• session_redis_send_timeout

  integer
  Deprecation notice: openid-connect: config.session_redis_send_timeout is deprecated, please use config.redis.send_timeout instead. This field is planned to be removed in version 4.0.

• session_redis_ssl

  boolean
  Deprecation notice: openid-connect: config.session_redis_ssl is deprecated, please use config.redis.ssl instead. This field is planned to be removed in version 4.0.

• session_redis_ssl_verify

  boolean
  Deprecation notice: openid-connect: config.session_redis_ssl_verify is deprecated, please use config.redis.ssl_verify instead. This field is planned to be removed in version 4.0.

• session_redis_server_name

  string
  Deprecation notice: openid-connect: config.session_redis_server_name is deprecated, please use config.redis.server_name instead. This field is planned to be removed in version 4.0.

• session_redis_cluster_nodes

  array of type record
  Deprecation notice: openid-connect: config.session_redis_cluster_nodes is deprecated, please use config.redis.cluster_nodes instead. This field is planned to be removed in version 4.0.

  • ip

    string required default: 127.0.0.1

    A string representing a host name, such as example.com.

  • port

    integer default: 6379 between: 0 65535

    An integer representing a port number between 0 and 65535, inclusive.

• session_redis_cluster_max_redirections

  integer
  Deprecation notice: openid-connect: config.session_redis_cluster_max_redirections is deprecated, please use config.redis.cluster_max_redirections instead. This field is planned to be removed in version 4.0.