OpenID Connect Configuration

You are browsing documentation for an outdated plugin version.

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 using Kong with the database, the discovery information and the JWKS are cached to the Kong configuration database.

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

    The re-discovery usually happens when the plugin cannot find a key for verifying the signature. For example, if a token is presented for which Kong does not have a JWK cached, it will poll the discovery endpoint for new JWK data. If that discovery attempt does not yield a JWK that can validate the token, Kong will wait the specified number of seconds before retrying the discovery.

  • 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:

    • password: OAuth legacy password grant
    • client_credentials: OAuth client credentials grant
    • authorization_code: authorization code flow
    • bearer: JWT access token verification
    • introspection: OAuth introspection
    • userinfo: OpenID Connect user info endpoint authentication
    • kong_oauth2: Kong OAuth plugin issued tokens verification
    • refresh_token: OAuth refresh token grant
    • session: session cookie authentication

  • 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. Other settings that are associated with the client are:

    • config.client_secret
    • config.client_auth
    • config.client_jwk
    • config.client_alg
    • config.redirect_uri
    • config.login_redirect_uri
    • config.logout_redirect_uri
    • config.unauthorized_redirect_uri
    • config.forbidden_redirect_uri
    • config.unexpected_redirect_uri

    Use the same array index when configuring related settings for the client.

  • client_secret

    array of type string referenceable encrypted

    The client secret.

    Specify one if using client_secret_* authentication with the client on the identity provider endpoints.

  • client_auth

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

    The authentication method used by the client (plugin) when calling the endpoints:

    • client_secret_basic: send client_id and client_secret in Authorization: Basic header
    • client_secret_post: send client_id and client_secret as part of the body
    • client_secret_jwt: send client assertion signed with the client_secret as part of the body
    • private_key_jwt: send client assertion signed with the private key as part of the body
    • none: do not authenticate

      Private keys can be stored in a database, and they are by the default automatically generated in the database. It is also possible to specify private keys with config.client_jwk directly in the plugin configuration.

  • 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:

    • HS256: HMAC using SHA-256
    • HS384: HMAC using SHA-384
    • HS512: HMAC using SHA-512
    • RS256: RSASSA-PKCS1-v1_5 using SHA-256
    • RS512: RSASSA-PKCS1-v1_5 using SHA-512
    • ES256: ECDSA using P-256 and SHA-256
    • ES384: ECDSA using P-384 and SHA-384
    • ES512: ECDSA using P-521 and SHA-512
    • PS256: RSASSA-PSS using SHA-256 and MGF1 with SHA-256
    • PS384: RSASSA-PSS using SHA-384 and MGF1 with SHA-384
    • PS512: RSASSA-PSS using SHA-512 and MGF1 with SHA-512
    • EdDSA: EdDSA with Ed25519

  • 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). For example, setting this value to Client, and sending the request header Client: 1 will cause the plugin to use the first client (see: config.client_id) from the client array.

  • redirect_uri

    array of type string

    The redirect URI passed to the authorization and token endpoints.

  • login_redirect_uri

    array of type string

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

    Tip: Leave this empty and the plugin will redirect the client to the URL that originally initiated the flow with possible query args preserved from the original request when config.preserve_query_args is enabled.

  • logout_redirect_uri

    array of type string

    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_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

    The response mode passed to the authorization endpoint:

    • query: Instructs the identity provider to pass parameters in query string
    • form_post: Instructs the identity provider to pass parameters in request body
    • fragment: Instructs the identity provider to pass parameters in uri fragment (rarely useful as the plugin itself cannot read it)

  • response_type

    array of type string default: code

    The response type passed to the authorization endpoint.

  • scopes

    array of type string 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.

    • When ["scope1 scope2"] are in the same array indices, both scope1 AND scope2 need to be present in access token (or introspection results).
    • When ["scope1", "scope2"] are in different array indices, either scope1 OR scope2 need to be present in access token (or introspection results).

  • scopes_claim

    array of type string default: scope

    The claim that contains the scopes.

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

    • When ["audience1 audience2"] are in the same array indices, both audience1 AND audience2 need to be present in access token (or introspection results).
    • When ["audience1", "audience2"] are in different array indices, either audience1 OR audience2 need to be present in access token (or introspection results).

  • audience_claim

    array of type string default: aud

    The claim that contains the audience.

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

    • When ["group1 group2"] are in the same array indices, both group1 AND group2 need to be present in access token (or introspection results).
    • When ["group1", "group2"] are in different array indices, either group1 OR group2 need to be present in access token (or introspection results).

  • groups_claim

    array of type string default: groups

    The claim that contains the groups.

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

    • When ["role1 role2"] are in the same array indices, both role1 AND role2 need to be present in access token (or introspection results).
    • When ["role1", "role2"] are in different array indices, either role1 OR role2 need to be present in access token (or introspection results).

  • roles_claim

    array of type string default: roles

    The claim that contains the roles.

  • 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 (for example, Kong Manager and Dev Portal). The OpenID Connect plugin itself does not do anything other than set the context value.

  • authorization_endpoint

    string

    The authorization 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

    The authorization cookie rolling timeout in seconds. Specifies how long the authorization cookie can be used until it needs to be renewed.

  • 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:

    • Strict: Cookies will only be sent in a first-party context and not be sent along with requests initiated by third party websites.
    • Lax: Cookies are not sent on normal cross-site subrequests (for example to load images or frames into a third party site), but are sent when a user is navigating to the origin site (for instance, when following a link).
    • None: Cookies will be sent in all contexts, for example in responses to both first-party and cross-origin requests. If SameSite=None is set, the cookie Secure attribute must also be set (or the cookie will be blocked).
    • Default: Do not explicitly specify a SameSite attribute.

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

    When this parameter is used with the config.login_action=redirect parameter, the browser location will change and display the original query arguments. Otherwise, the upstream request is modified to include the original query arguments, and the browser will not display them in the location field.

  • token_endpoint

    string

    The token endpoint.

  • token_endpoint_auth_method

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

    The token endpoint authentication method:

    • client_secret_basic: send client_id and client_secret in Authorization: Basic header
    • client_secret_post: send client_id and client_secret as part of the body
    • client_secret_jwt: send client assertion signed with the client_secret as part of the body
    • private_key_jwt: send client assertion signed with the private key as part of the body
    • 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:

    • Request Body
    • Query parameters

    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 and send it to the token endpoint.

  • introspection_endpoint

    string

    The introspection endpoint.

  • introspection_endpoint_auth_method

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

    The introspection endpoint authentication method:

    • client_secret_basic: send client_id and client_secret in Authorization: Basic header
    • client_secret_post: send client_id and client_secret as part of the body
    • client_secret_jwt: send client assertion signed with the client_secret as part of the body
    • private_key_jwt: send client assertion signed with the private key as part of the body
    • 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

    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.

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

  • revocation_endpoint_auth_method

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

    The revocation endpoint authentication method:

    • client_secret_basic: send client_id and client_secret in Authorization: Basic header
    • client_secret_post: send client_id and client_secret as part of the body
    • client_secret_jwt: send client assertion signed with the client_secret as part of the body
    • private_key_jwt: send client assertion signed with the private key as part of the body
    • none: do not authenticate

  • end_session_endpoint

    string

    The end session endpoint.

  • userinfo_endpoint

    string

    The user info 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

    The persistent session rolling timeout window, in seconds.

  • session_remember_absolute_timeout

    number default: 2592000

    The persistent session absolute timeout limit, in seconds.

  • session_idling_timeout

    number default: 900

    The session cookie idle time in seconds.

  • session_rolling_timeout

    number default: 3600

    The session cookie rolling timeout in seconds. Specifies how long the session can be used until it needs to be renewed.

  • session_absolute_timeout

    number default: 86400

    The session cookie absolute timeout in seconds. Specifies how long the session can be used until it is no longer valid.

  • 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:

    • Strict: Cookies will only be sent in a first-party context and aren’t sent along with requests initiated by third party websites.
    • Lax: Cookies are not sent on normal cross-site subrequests (for example to load images or frames into a third party site), but are sent when a user is navigating to the origin site (for example, when following a link).
    • None: Cookies will be sent in all contexts, for example in responses to both first party and cross-origin requests. If SameSite=None is set, the cookie Secure attribute must also be set, or the cookie will be blocked.
    • Default: Do not explicitly specify a SameSite attribute.

  • 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

    List of information to include, as headers, in the request to the upstream. Accepted values are: id, audience, subject, timeout, idling-timeout, rolling-timeout, and absolute-timeout. For example, { "id", "timeout" } sets both Session-Id and Session-Timeout in the request headers.

  • session_response_headers

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

    List of information to include, as headers, in the response to the downstream. Accepted values are: id, audience, subject, timeout, idling-timeout, rolling-timeout, and absolute-timeout. For example: { "id", "timeout" } injects both Session-Id and Session-Timeout in the 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.

  • session_redis_prefix

    string

    The Redis session key prefix.

  • session_redis_socket

    string

    The Redis unix socket path.

  • session_redis_host

    string default: 127.0.0.1

    The Redis host

  • session_redis_port

    integer default: 6379 between: 0 65535

    The Redis port.

  • session_redis_username

    string referenceable

    Username to use for Redis connection when the redis session storage is defined and ACL authentication is desired. If undefined, ACL authentication will not be performed. This requires Redis v6.0.0+. The username cannot be set to default.

  • session_redis_password

    string referenceable encrypted

    Password to use for Redis connection when the redis session storage is defined. If undefined, no AUTH commands are sent to Redis.

  • session_redis_connect_timeout

    integer

    The Redis connection timeout in milliseconds.

  • session_redis_read_timeout

    integer

    The Redis read timeout in milliseconds.

  • session_redis_send_timeout

    integer

    The Redis send timeout in milliseconds.

  • session_redis_ssl

    boolean default: false

    Use SSL/TLS for Redis connection.

  • session_redis_ssl_verify

    boolean default: false

    Verify Redis server certificate.

  • session_redis_server_name

    string

    The SNI used for connecting the Redis server.

  • session_redis_cluster_nodes

    array of type record

    The Redis cluster node host. Takes an array of host records, with either ip or host, and port values.

    • ip

      string required default: 127.0.0.1

    • port

      integer default: 6379 between: 0 65535

  • session_redis_cluster_max_redirections

    integer

    The Redis cluster maximum redirects.

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

  • 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

  • upstream_session_id_header

    string

    The upstream session id header.

  • downstream_headers_claims

    array of type string

    The downstream header claims.

  • 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

  • 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:

    • password: enable for OAuth password grant
    • client_credentials: enable OAuth client credentials grant
    • authorization_code: enable for authorization code flow
    • bearer: enable for JWT access token authentication
    • introspection: enable for OAuth introspection authentication
    • userinfo: enable for OpenID Connect user info endpoint authentication
    • kong_oauth2: enable for Kong OAuth Plugin authentication
    • refresh_token: enable for OAuth refresh token grant
    • session: enable for session cookie authentication

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

  • logout_revoke_access_token

    boolean default: true

    Revoke the access token as part of the logout.

  • logout_revoke_refresh_token

    boolean default: true

    Revoke the refresh token as part of the logout.

  • consumer_claim

    array of type string

    The claim used for consumer mapping.

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

  • 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

    Allow some leeway on the ttl / expiry verification.

  • 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:

    • password: do not start a session with the password grant
    • client_credentials: do not start a session with the client credentials grant
    • authorization_code: do not start a session after authorization code flow
    • bearer: do not start session with JWT access token authentication
    • introspection: do not start session with introspection authentication
    • userinfo: do not start session with user info authentication
    • kong_oauth2: do not start session with Kong OAuth authentication
    • refresh_token do not start session with refresh token grant
    • session: do not renew the session with session cookie authentication

  • 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 us used for caching the token endpoint requests.

    If you use multiple plugin instances of the OpenID Connect plugin and want to share token endpoint caches between the plugin instances, set the salt to the same value on each plugin instance.

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

    This requires an extra round-trip and can add latency, but the plugin can also cache user info requests (see: config.cache_user_info).

  • 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

    The HTTP proxy authorization.

  • https_proxy

    string

    The HTTPS proxy

  • https_proxy_authorization

    string

    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.

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

• authorization_cookie_lifetime

  number
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• authorization_cookie_samesite

  string
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• authorization_cookie_httponly

  boolean
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• session_cookie_lifetime

  number
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• session_cookie_idletime

  number
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• session_cookie_samesite

  string
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• session_cookie_httponly

  boolean
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• session_memcache_prefix

  string
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• session_memcache_socket

  string
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• session_memcache_host

  string
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• session_memcache_port

  integer
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• session_redis_cluster_maxredirections

  integer
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• session_cookie_renew

  number
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• session_cookie_maxsize

  integer
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• session_strategy

  string
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• session_compressor

  string
  Deprecation notice: This field has been deprecated and will be removed in a future version..