OpenID Connect

OpenID Connect (1.0) plugin allows the integration with a 3rd party identity provider (IdP) or IAM OAuth 2.0 Plugin in a standardized way. This plugin can be used to implement IAM as a (proxying) OAuth 2.0 resource server (RS) and / or as an OpenID Connect relying party (RP) between the client and the upstream service.

The plugin supports several types of credentials, including:

• Signed JWT access tokens (JWS) with the standardized signing algorithms (JWA)
• Opaque access tokens with either IAM OAuth 2.0 plugin issued tokens or 3rd party IdP issued ones through token introspection (IdP needs to support it)
• Username and password through the OAuth 2.0 password grant (the plugin will automatically exchange such credentials with access token by calling the IdP's token endpoint)
• Client id and secret through the OAuth 2.0 client credentials grant (the plugin will automatically exchange such credentials with access token by calling the IdP's token endpoint)
• Authorization code that the OpenID Connect plugin can retrieve from the client when using OpenID Connect authorization code flow
• Session cookie credentials that the plugin can setup between the client and IAM (usually used with web browser clients together with authorization code grant)

This plugin can automatically refresh the access token using a refresh token.

You can either let the plugin to exclusively talk your IdP as a trusted client (and let it do all the credential exchange) or you can let clients talk to IdP directly, and then present access token to the upstream service protected with the OpenID Connect plugin (or you can do both).

Some of the capabilities of the plugin are listed below:

• WebFinger and OpenID Connect Discovery
• ID Token verification
• UserInfo endpoint data injecting
• RP-Initiated Logout
• OAuth 2.0 Token Revocation during the logout (optionally)
• OAuth 2.0 Token Introspection support
• OAuth 2.0 Proof Key for Code Exchange (PKCE) support
• Standard and configurable claims verification
• Caching (optional) of token, introspection and user info endpoint request

The plugin has been tested with several OpenID Connect capable providers such as:

• Auth0
• Amazon AWS Cognito
• Connect2id
• Dex
• Gluu
• Google
• IdentityServer4
• Keycloak
• Microsoft Azure Active Directory v1
• Microsoft Azure Active Directory v2
• Microsoft Live Connect
• Okta
• OneLogin
• OpenAM
• Paypal
• PingFederate
• Salesforce
• Yahoo!

As long as your provider supports OpenID Connect standards the plugin should work, even if it is not specifically tested against it. Let us know if you want your provider to be tested and added to the list.

Once applied, any user with a valid credential can access the Service/API. To restrict usage to only some of the authenticated users, also add the ACL plugin (not covered here) and create whitelist or blacklist groups of users.

Terminology

• plugin: a plugin executing actions inside IAM before or after a request has been proxied to the upstream API.
• upstream service: this refers to your own API/service sitting behind IAM, to which client requests are forwarded.

Configuration

Global plugins

• Using a database, all plugins can be configured using the http://localhost:8001/plugins/ endpoint.
• Without a database, all plugins can be configured via the plugins: entry on the declarative configuration file.

A plugin which is not associated to any Service, Route or Consumer (or API, if you are using an older version of IAM) is considered "global", and will be run on every request. Read the Plugin Reference and the Plugin Precedence sections for more information.

Parameters

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

IAM OpenID Connect Plugin

The IAM OpenID Connect plugin provides a general-purpose OpenID Connect and OAuth toolkit.

Terminology

Use Cases

Protecting Server to Server API Access

For server-to-server we recommend you to use OAuth 2.0 client credentials grant that is enhanced with OpenID Connect features (such as standardized security feature, and automatic discovery). Client credentials are easier to revoke than say password credentials without affecting too many things.

Protecting Interactive Browser based API / Web Site Access

The best method to use here is to use OpenID Connect Authentication using *authorization code** flow. IAM sets up a session with the browser. After initial authentication the browser will send the cookie automatically — even when making API requests using JavaScript. With authorization code flow you can usually use stronger authentication methods such as two-factor authentication on your identity provider.

Protecting Access to APIs from 1st Party Client

Here you can use OAuth 2.0 password grant that is enhanced with OpenID Connect features.

Protecting Access to APIs with Stateless JWT Tokens

When you have JWT (or JWS to be more specific) available for your client, that is possibly issued directly from the identity provider (e.g. by using implicit flow), and want you to use that token to access API protected by IAM, you should use a plugin that provides you OpenID Connect aware stateless verification.

Accessing APIs from Basic Authentication Aware Client

Basic authentication is supported in many 3rd party clients. One such client is Microsoft Excel. The openid-connect plugin allows you to supply username and password or client id and client secret using normal basic authentication headers.

Features

OpenID Connect Discovery

The plugin does support OpenID Connect Discovery as defined in the specification.

JWA Signing Algorithms

¹⁾ there is currently no support for using SHA384 with RSA signatures, since there's no gain in either computation time nor message size compared to using SHA256 or SHA512, respectively.

²⁾ for security purposes we have decided not to support none signing algorithm at this point. We might add it later, though.

At this point we are mostly focusing on the RP side of OpenID Connect, and that's why we have not bothered with signing algorithms as none of our plugins do use them. The signature verification support is rather complete.

JWT Serialization Formats

This is what the plugins currently support for JWT serializations. The table may change in a future as further features get implemented.

OpenID Connect Plugin

The OpenID Connect plugin supports a variety of authentication and authorization methods:

• OAuth 2.0 Password Grant
• OAuth 2.0 Client Credentials Grant
• OpenID Connect 1.0 / OAuth 2.0 Authorization Code Flows
• JWT Bearer Tokens (both signature and claims validations)
• OAuth 2.0 Introspection (verifying opaque tokens)
• IAM OAuth 2.0 Authentication Plugin issued tokens
• Refreshing expired access token with refresh token, if available
• Session authentication with a HTTP Only session cookie sent by this plugin

This plugin exchanges credentials and injects access token as a bearer token into Authorization HTTP header.

Configuration Parameters

As OpenID Connect can be used in many ways, the plugin has many parameters. Some of the settings are used only in some flows, and others are used more broadly. Generally speaking, while parameters are optional, requirements will vary depending on your use case and identity provider.

Descriptions

Types, Optionality and Defaults

While there are a lot of parameters, most of them are optional as you can see below.

— in default column means that there is no (static) default.

¹⁾ all the config parameters should be prefixed with config..

config.issuer

The OpenID Provider configuration and JWKS are discovered using the config.issuer configuration parameter. Set this to a location where the plugin will find the /.well-known/openid-configuration discovery endpoint. This parameter accepts only URLs.

Examples:

• https://accounts.google.com/
• https://accounts.google.com/.well-known/openid-configuration

config.client_arg

Sometimes you need to use different client or client parameters, e.g. when you use this plugin in front of multiple services.

This argument is used to pick up the right configuration to from following config parameters:

• config.client_id
• config.client_secret
• config.redirect_uri
• config.login_redirect_uri
• config.logout_redirect_uri
• config.forbidden_redirect_uri
• config.unauthorized_redirect_uri
• config.unexpected_redirect_uri

If you want to override default client_id value you can use this config parameter to define one. Then we look for value in following order (the default client_id is used here as example):

• header X-Client-ID or Client-ID
• query argument client_id
• post argument client_id

If you specify config.client_arg with value client_config then the plugin tries to find value from:

• header X-Client-Config or Client-Config
• query argument client_config
• post argument client_config

The value stored in the parameter can be integer or actual client_id found in config.client_id. In case it is an integer, that is used to pick up correct parameters by index from the following:

• config.client_id
• config.client_secret
• config.redirect_uri
• config.login_redirect_uri
• config.logout_redirect_uri

Indexing starts from 1. If no such index is found, then the index of 1 is used. You can also you the actual client_id and then we use the index of the config.client_id to rest of the parameters (and fallback to 1 if not found in specified index).

config.client_id

With this parameter specify the client_id of your client that you have registered in OpenID Connect Provider. This is the client that authenticates IAM with your OpenID Provider. It can be considered a trusted client or confidential client. This parameter can also be an array as this plugin supports multiple clients. The right one is then picked up by matching to a request parameter (defined with config.client_arg).

Note: In many cases you will need to configure this to allow IAM to work as a trusted client. If you only do e.g. JWT bearer token verification, you won't need to configure this.

config.client_secret

With this parameter specify the client_secret of your client that you have registered in OpenID Connect Provider. As mentioned above, also this can be an array of client secrets.

Note: In many cases you will need to configure this to allow IAM to work as a trusted client. If you only do e.g. JWT bearer token verification, you won't need to configure this.

config.redirect_uri

Specify where you want the browser to be redirected (from IdP) in case of a successful login. The ID Token will be appended as an URL fragment to the redirect URL. If this parameter is not specified, the ID Token will be returned instead of redirect. This as client_id and client_secret can also be an array if different clients use different redirect uris.

Examples:

• "https://example.com/"

config.login_redirect_uri

When config.login_action is set to redirect, this configuration parameter contains the url for the redirection. It can also be an array, so that you can pick up different login_redirect_uri depending on the selected client.

config.logout_redirect_uri

When logout is requested you can use this configuration parameter to define url to be redirected after a successful logout. If relying party initiated logout is used, this logout redirect uri will be used as post_logout_redirect_uri passed to IdP. It can also be an array, so that you can pick up different logout_redirect_uri depending on the selected client.

config.forbidden_redirect_uri

Instead of responding with HTTP status code of 403, with this parameter you can instead send 302 redirect. Nice to have if you are trying to protect web sites (instead of say individual APIs) with this plugin.

config.forbidden_destroy_session

Whether or not to destroy session cookie when the request was forbidden.

You may want to turn this off in case you want to keep users logged in in case they try to do something forbidden.

config.forbidden_error_message

Default response for forbidden request from this plugin is:

{
    "message": "Forbidden"
}

With this configuration parameter you can change the default "Forbidden" message to something else.

config.unauthorized_redirect_uri

Instead of responding with HTTP status code of 401, with this parameter you can instead send 302 redirect. Nice to have if you are trying to protect web sites (instead of say individual APIs) with this plugin.

config.unauthorized_error_message

Default response for unauthorized request from this plugin is:

{
    "message": "Unauthorized"
}

With this configuration parameter you can change the default "Unauthorized" message to something else.

config.unexpected_redirect_uri

Instead of responding with HTTP status code of 500, with this parameter you can instead send 302 redirect. Nice to have if you are trying to protect web sites (instead of say individual APIs) with this plugin.

config.scopes

Scopes requested when authenticating.

Examples:

• "openid"
• "openid,profile,email"
• "openid,profile,email,offline_access"

config.scopes_required

Scopes required to be present in access token (scope claim) or introspection results (scope claim) for authorization or in claim specified with config.scopes_claim.

This config parameter works in both AND / OR cases.

Examples:

• "scope1 scope2" – both scope1 AND scope2 need to be present in access token (or introspection results)
• "scope1,scope2" – either scope1 OR scope2 need to be present in access token (or introspection results)

config.scopes_claim

The name of the claim where the scopes are picked for config.scopes_required authorization.

Examples:

• "scope" – top level claim
• "realm_access,roles" – top level realm_access claim (a JSON object) that has a sub-claim roles.

config.response_mode

When IAM talks to authorization endpoint this value instructs OP to respond in a specific way (if OP supports different response modes):

Response mode can be one of these:

• query (the default)
• form_post
• fragment

Examples:

• "form_post"
• "fragment"

config.auth_methods

This so called all-in-one plugin supports many different methods to authenticate the request using 3rd party OP. This parameter is an array that lists all the authentication methods that you want the plugin to accept, and the array can contain following values:

• "password"
• "client_credentials"
• "authorization_code"
• "bearer"
• "introspection"
• "kong_oauth2"
• "refresh_token"
• "session"

password

This enables password grant. To use this authentication method you can either Authorization: Basic username:password header where username:password can optionally be base64 encoded as defined in HTTP Basic authentication specification. You can also send username and password fields with those names to IAM as a payload.

client_credentials

Similar to password grant, but this time you have to send client_id and client_secret as Authorization: Basic client_id:client_secret header. You can also send client_id and client_secret as a payload to IAM (with those names).

authorization_code

This enables (mostly) interactive authorization code flow, where IAM initiates the process and sends redirect to OP to the client. Authorization code flow is also the one that we use as the last fallback (when enabled) if no other authentication methods match the request.

bearer

This enables IAM to look for Authorization: Bearer <token> header. The <token> can either be a value token (signed JWT token aka JWS token) or it can be opaque token. For value tokens IAM does signature verification and standard claims verification (e.g. expiration checks, and many other OpenID Connect standardized claims). For opaque tokens IAM can try to introspect them, if introspection is enabled as one of the authentication methods. On version 0.1.1 we also look bearer token in Access-Token, and X-Access-Token headers.

introspection

If a bearer token is provided as opaque token, IAM can try to verify it by using introspection.

kong_oauth2

A special version of opaque tokens are the ones issued by IAM OAuth 2.0 authentication plugin. This plugin can be used to verify those as well.

session

IAM can optionally setup session using HTTP only cookie between the client and IAM. That can also be used for authenticating the request. This is especially nice when used together with authorization code flow.

refresh_token

This authentication method enables authentication using refresh or an offline token. It is similar to password and client_credentials, but uses different grant type when calling the token endpoint of the identity provider.

config.audience

Used to send audience argument to authorization endpoint in case that is needed. Also verifies aud claim of JWT tokens.

Examples:

• "https://example.com/api/v2/"
• "https://example.com/api/v2/,https://example.com/api/v3/"

See config.audience_required for a more flexible option to be used for strictly aud claim verification.

config.audience_required

Audience required to be present in access token (aud claim) or introspection results (aud claim) for authorization, or in claim specified with config.audience_claim.

This config parameter works in both AND / OR cases.

Examples:

• "audience1 audience2" – both audience1 AND audience2 need to be present in access token (or introspection results)
• "audience1,audience2" – either audience1 OR audience2 need to be present in access token (or introspection results)

config.audience_claim

The name of the claim where the audiences are picked for config.audience_required authorization.

Examples:

• "aud" – top level claim
• "user,groups" – top level user claim (a JSON object) that has a sub-claim groups.

config.domains

With this config parameter you may specify the domains that are allowed to use the API. The token's hd claim (hosted domain) is verified against the config.domains.

Examples:

• "example.com"
• "example.com,company.com"

config.max_age

This configuration parameter is used to configure auth_time claim verification. With this parameter you may restrict the use of the API with too old id tokens. The max_age is specified in seconds.

Note: config.leeway may affect the calculation as well.

Examples:

• 86400
• 1800

config.authenticated_groups_claim

This property allows one to connect this plugin with an ACL plugin where the ACL plugin provides both white- and blacklisting based on an arbitrary claim.

With this configuration, one can specify the name of the claim (or path) where the “groups” can be found

Examples:

• "groups"
• "user,groups"

config.authorization_cookie_name

When this plugin initiates authorization code flow, it will store some state information (for verification etc.) to a cookie that is sent to a client together with 302 redirect to IdP's authorization endpoint.

If you want to use different name for the cookie, you can use this parameter to define one.

config.authorization_cookie_lifetime

Session cookie lifetime in seconds.

config.authorization_cookie_path

With this parameter you can set the value for authorization cookie Path property.

config.authorization_cookie_domain

With this parameter you can set the value for authorization cookie Domain property.

config.authorization_cookie_samesite

With this parameter you can set the value for authorization cookie Same-Site flag.

The plugin accepts these values for this parameter:

• "Strict"
• "Lax"
• "off"

config.session_cookie_httponly

With this parameter you can set the value for authorization cookie HTTP Only flag.

config.authorization_cookie_secure

With this parameter you can set the value for authorization cookie Secure flag.

config.session_cookie_name

When this plugin initiates a session (on successful login) with the client it will send a cookie to a client. With this parameter you can specify the name of the cookie that client receives.

config.session_cookie_lifetime

Session cookie lifetime in seconds.

config.session_cookie_path

With this parameter you can set the value for session cookie Path property.

config.session_cookie_domain

With this parameter you can set the value for session cookie Domain property.

config.session_cookie_samesite

With this parameter you can set the value for session cookie Same-Site flag.

The plugin accepts these values for this parameter:

• "Strict"
• "Lax"
• "off"

config.session_cookie_httponly

With this parameter you can set the value for session cookie HTTP Only flag.

config.session_cookie_secure

With this parameter you can set the value for session cookie Secure flag.

config.session_storage

With this configuration parameter you can select where the plugin stores the data part or the session cookie. Possible values are:

• "cookie"
• "memcache"
• "redis"

Cookie storage has benefit of being stateless and that no database server is needed on server. It is also lock-less. The bad side of using cookie to store session data is that the cookies can grow big when storing JWT tokens with a lot of claims in them. And then it will then make request headers larger which can cause other problems, such as need to configure Nginx/IAM (and possibly load balancers) to handle large headers. Also if cookies grow bigger than 4k they are split in multiple cookies. Other problems with storing data in cookie is that there could be a slight change for someone to be able to decrypt the cookies and get access to tokens that way. In secure environments you should never use cookie storage without forced SSL/TLS . One additional benefit is that server stored cookies can be deleted from the database, which will effectively invalidate session cookies. Server stored cookies are typically well under a hundred bytes while cookie stored data usually grow the cookies to several kilobytes.

Below are listed the configuration parameters for memcache and redis storage backends.

config.session_memcache_prefix

Memcache session key prefix (all session keys will use this prefix).

E.g. if the value is sessions then all the sessions will be stored in keys prefixed with sessions:<session-id>.

config.session_memcache_socket

Redis unix socket path. If this is defined, it will override whatever is put in config.session_redis_host or config.session_redis_port.

config.session_memcache_host

Memcache host.

config.session_memcache_port

Memcache port.

config.session_redis_prefix

Redis session key prefix (all session keys will use this prefix).

E.g. if the value is sessions then all the sessions will be stored in keys prefixed with sessions:<session-id>.

config.session_redis_socket

Redis unix socket path. If this is defined, it will override whatever is put in config.session_redis_host or config.session_redis_port.

config.session_redis_host

Redis host.

config.session_redis_port

Redis port.

config.session_redis_auth

Redis authentication password.

config.extra_jwks_uris

Some identity providers sign access tokens with different JWK-keys than what they use to sign id tokens, and they don't necessarily reveal the public keys in OpenID Connect discovery. With this parameter you can define alternative URIs where the plugin can find the additional keys used to verify signatures.

Examples:

• "https://pingfederate.com:9031/ext/jwks"

config.jwt_session_cookie

Defines a name of the cookie that contains a value for a claim that is specified with config.jwt_session_claim (and which is by default sid) in a JWT access token.

If you don't specify value for this, then the claim is not checked. This is not a standard OpenID Connect feature but it is added here for added verification of a JWT value token (your identity provider or additional service should issue the cookie, and that cookie should be HTTP only and sent to IAM (as well) when accessing upstream API service).

This parameter is only used when authenticating with stateless JWT bearer tokens (for other authentication methods we currently ignore this).

Examples:

• "sid"
• "session_state"

config.jwt_session_claim

With this you can configure a claim in JWT access token that is verified against a cookie with a name that is configured with config.jwt_session_cookie parameter. If no name for cookie is specified, the verification is skipped.

This parameter is only used when authenticating with stateless JWT bearer tokens (for other authentication methods we currently ignore this).

Examples:

• "sid"
• "session_state"

config.rediscovery_lifetime

With this parameter you can configure how often (in seconds) you want to allow the plugin to do re-discovery (OpenID Connect Discovery) and load extra JWKS (config.extra_jwks_uris). This parameter is there to prevent plugin from hitting your IdPs discovery endpoints too often. The plugin only re-discovers when it sees a need for that. E.g. when you have rotated keys on IdP and you try to access a service with a token that has been signed with a JWK using a kid that is not known to IAM. Then the plugin tries to reload the JWKS, and tries to do find the right kid again. Setting this to 0 will make the plugin always re-discover when needed.

Examples:

• 300
• 0

config.reverify

If you are utilizing session based authentication method. Then by default we trust that alone and do not do further verifications. If you enable re-verification, then IAM will recheck the possible signature and the claims on each request.

config.bearer_token_param_type

With this parameter you can define where the bearer tokens are searched in request. On header we seek it from Authorization: Bearer, Access-Token, and X-Access-Token headers and in query and body we seek for argument named access_token.

Here are the unconfigured defaults:

config.refresh_token_param_name

Because there is no such standard that defines how the refresh token or offline token should be sent to a server for verification, this parameter solves half of the puzzle by defining the parameters name where the plugin should look for the refresh token.

Examples:

• "refresh_token"
• "X-Refresh-Token"
• "Offline-Token"

config.refresh_token_param_type

This parameter is the another half of the puzzle of how the refresh token is delivered for verification (another one being config.refresh_token_param_name). The HTTP protocol provides a few methods for information delivery to the server:

1. URL Query String
2. HTTP Headers
3. HTTP Body

(servers do not generally deal with url #fragments).

For query string and HTTP headers we do look for a value defined with config.refresh_token_param_type. For HTTP Body we support several ways of delivery:

1. application/x-www-form-urlencoded
2. application/json

There we look for a value defined with config.refresh_token_param_name.

Based on the above the supported values for this configuration parameter are (or any combination of them):

Here are the unconfigured defaults:

config.refresh_tokens

Specifies whether or not the plugin should try to refresh (soon to be) expired access tokens if the plugin has a refresh_token available. This is most useful with session authentication, as the session can possibly live longer than the access token. If expired access token cannot be refreshed or the refresh token is not available, the request will be terminated and not proxied.

Examples:

• true
• false

config.client_credentials_param_type

With this parameter you can define where the client credentials are searched in request. On header we seek it from Authorization: Basic header and in query and body we seek for arguments named client_id and client_secret.

Here are the unconfigured defaults:

config.password_param_type

With this parameter you can define where the password grant credentials are searched in request. On header we seek it from Authorization: Basic header and in query and body we seek for arguments named username and password.

Here are the unconfigured defaults:

config.id_token_param_name

Because there is no such standard that defines how the id token should be send to a server for verification this parameter solves one half of the puzzle by defining the parameters name where the plugin should look for the id token.

The ID token can only be sent with the access token. It cannot be used alone for authentication (at least in current implementation, and we encourage not to use it for authentication).

Examples:

• "idtoken"
• "idt"
• "X-ID-Token"

config.id_token_param_type

This parameter is the another half of the puzzle of how the id token is delivered for verification (another one being config.id_token_param_name). The HTTP protocol provides a few methods for information delivery to the server:

1. URL Query String
2. HTTP Headers
3. HTTP Body

(servers do not generally deal with url #fragments).

For query string and HTTP headers we do look for a value defined with config.id_token_param_type. For HTTP Body we support several ways of delivery:

1. application/x-www-form-urlencoded
2. application/json

There we look for a value defined with config.id_token_param_name.

Based on the above the supported values for this configuration parameter are (or any combination of them):

Here are the unconfigured defaults:

config.discovery_headers_names

Extra arguments names that you want to include in discovery request headers (such as Authorization).

config.discovery_headers_values

Values for the extra arguments that you want to include in discovery request headers.

config.authorization_query_args_names

Extra arguments names that you want to include in authorization endpoint query string.

config.authorization_query_args_values

Values for the extra arguments that you want to include in authorization endpoint query string.

config.authorization_query_args_client

Extra dynamic arguments that are passed from client to authorization endpoint. E.g. specify arguments such as login_hint with this config parameter.

config.token_post_args_names

Extra arguments names that you want to include in token endpoint post args.

config.token_post_args_values

Values for the extra arguments that you want to include in token endpoint post args.

config.token_headers_client

When IAM calls token endpoint, you can specify the headers that IAM will pass to token endpoint from client request headers.

config.token_headers_replay

When IAM calls token endpoint, you can specify the headers (from the token endpoint response) that you want the IAM to send back to the client.

config.token_headers_prefix

If you want you can prefix the token endpoint headers with a string to differentiate them from other headers.

config.token_headers_grants

You can limit the grants for which the token headers are replayed:

• "password"
• "client_credentials"
• "authorization_code"

config.token_endpoint_auth_method

If you want to override defaults or information coming from OpenID Connect Discovery claim token_endpoint_auth_methods_supported, you can use this parameter override the authentication method we use to authenticate on token_endpoint as a confidential client. Possible values are:

• "none"
• "client_secret_basic"
• "client_secret_post"

If none is specified, we use either one of the method found in token_endpoint_auth_methods_supported or "client_secret_basic".

For client credentials grant we don't support "none" as it does not make any sense as there got to be those credentials to be present. You can still configure this to "none" it is just that for client credentials grant it is ignored.

config.upstream_headers_claims

Claims to look from which to create upstream headers.

config.upstream_headers_names

Upstream headers to create for the matching claims.

config.upstream_access_token_header

Specify a name of the upstream header where the access token is injected. By default this is set to a special value authorization:bearer which means that the access token is injected as Authorization header and the values is set as a bearer token.

config.downstream_access_token_header

If you want to inject access token in downstream headers (response), you can use this configuration parameter to specify the name of the header where the access token is injected. By default we don't inject access token in response headers.

config.upstream_access_token_jwk_header

With this configuration parameter you can specify the name of the header that IAM will inject to a request before proxying to upstream service. The value will be set to a JWK that was used to verify the access token. This is used when the JWT access token is available.

config.downstream_access_token_jwk_header

Similar to above, but this time for downstream (response).

config.upstream_id_token_header

Specify a name of the upstream header where the id token is injected (if any). By default we don't inject id tokens to upstream headers.

config.downstream_id_token_header

Specify a name of the downstream (response) header where the id token is injected (if any). By default we don't inject id tokens to downstream headers.

config.upstream_id_token_jwk_header

With this configuration parameter you can specify the name of the header that IAM will inject to a request before proxying to upstream service. The value will be set to a JWK that was used to verify the id token. This is used when the JWT id token is available.

config.downstream_id_token_jwk_header

Similar to above, but this time for downstream (response).

config.upstream_refresh_token_header

Specify a name of the upstream header where the refresh token is injected (if any). By default we don't inject refresh tokens to upstream headers.

config.downstream_refresh_token_header

Specify a name of the downstream (response) header where the refresh token is injected (if any). By default we don't inject refresh tokens to downstream headers.

config.upstream_user_info_header

With this configuration parameter you can specify the name of the header that IAM will inject to a request before proxying to upstream service. The value will be set to a OpenID Connect standard User Info (JSON document), if the plugin is able to retrieve that.

config.downstream_user_info_header

Similar to above, but this time for downstream (response).

config.upstream_introspection_header

When you try to login with opaque access token, IAM tries to authenticate the request using standard OAuth 2.0 Introspection. If that succeeds and you want to pass the introspection results to upstream, you can do so by setting this parameter.

config.downstream_introspection_header

Similar to above, but this time for downstream (response).

config.introspect_jwt_tokens

You can turn this option on (true) to enable introspection of JWT Bearer tokens. This enables checking of revoked JWT tokens, but it adds latency to request. So if you enable this, it is good to make IAM to IdP traffic as fast as possible. We still cache introspection results if config.cache_introspection is enabled. So in environments where you require absolutely up-to-date information about token revocation, you should disable config.cache_introspection. If you do so, IAM will then always call IdP's introspection endpoint before deciding whether or not to allow processing continue, and ultimately proxying to upstream service.

config.introspection_endpoint

OAuth 2.0 introspection endpoint is not defined in OpenID Connect standards or OpenID Connect Discovery. Still some OpenID providers announce the introspection endpoint in discovery document. IAM tries hard to figure out the introspection endpoint, but sometimes it is not possible through automation. With this configuration parameter you can specify a URL for your issuer's introspection endpoint.

config.introspection_hint

Some providers such as WSO2 don't implement OAuth 2.0 introspection standard correctly, and they want to have token_type_hint argument with value bearer instead of access_token when introspecting access tokens. With this parameter you can change the value of the token_type_hint argument that the plugin will pass to introspection endpoint when introspecting access tokens.

config.introspection_headers_names

Extra arguments names that you want to include in introspection request headers (e.g. use this to override Authorization header).

config.introspection_headers_values

Values for the extra arguments that you want to include in introspection request headers.

config.login_methods

With this configuration parameter you can adjust plugin to only use other config.login_* parameters when there is a matching authentication method used. Possible values:

• "password"
• "client_credentials"
• "authorization_code"
• "bearer"
• "introspection"
• "kong_oauth2"
• "session"

By default this is configured only for authorization_code. Non matching grants will be proxied to upstream regardless of config.login_action.

config.login_action

When the authentication is done with a method specified with config.login_methods, this configuration parameter enables you to decide what IAM does next. The possible actions are:

1. "upstream" — after authentication, IAM reverse proxies the request to upstream service (this is the default)
2. "response" — after authentication, IAM returns response that by default contains id token (if any)
3. "redirect" — after authentication, IAM sends a redirect response to client with redirection uri taken from config.login.redirect_uri

config.login_tokens

If the login_action is set to response or redirect, you can specify the tokens to be returned (if available) or added to redirection uri's hash.

config.login_redirect_mode

When config.login_action is set to redirect, this configuration parameter is used to define how you want to pass login_tokens with login_redirect_uri`. The options are:

• "fragment" (default)
• "query"
• "form_post" (not yet implemented)

fragment means that login_tokens are appended to login_redirect_uri's uri fragment (#) so that they are only accessible to the client. query means that login_tokens are appended to login_redirect_uri's query string (?) making it available both to the client and the server. In future we are going to enable third option form_post which will, instead of doing 302 redirect will make a HTTP POST to login_redirect_uri with the tokens as HTTP POST arguments in HTTP POST request's body.

config.logout_query_arg

If you want to enable logout by query argument, use this parameter to define name of the query argument.

config.logout_post_arg

If you want to enable logout by post argument, use this parameter to define name of the post argument.

config.logout_uri_suffix

If you want to enable logout by uri suffix, use this parameter to define the suffix.

config.logout_methods

Specify HTTP methods that are allowed for logout. You can use these methods:

• "POST"
• "GET"
• "DELETE"

By default "POST" and "DELETE" are enabled.

config.logout_revoke

If you want also try to revoke the tokens on logout by calling IdP's revocation endpoint, you can use this parameter to enable it. By default the plugin does not call revocation endpoint. With this parameter you can switch (on/off) the the more specific config.logout_revoke_access_token, and config.logout_revoke_refresh_token.

config.logout_revoke_access_token

If turned on, and config.logout_revoke is enabled, the plugin tries to revoke access token on logout.

By default this is enabled, but the config.logout_revoke is disabled so the access token will not be revoked.

config.logout_revoke_refresh_token

If turned on, and config.logout_revoke is enabled, the plugin tries to revoke the refresh token on logout.

By default this is disabled, and the config.logout_revoke is disabled too, so the refresh token will not be revoked

config.revocation_endpoint

If revocation endpoint is not defined in OpenID Connect discovery document, you can use this parameter to define one manually.

config.end_session_endpoint

Usually this is defined in OpenID Connect discovery document, but you can use this parameter to define one manually. If either this parameter is specified or end session endpoint is found in discovery document, this plugin will, on logout, redirect client to here.

config.token_exchange_endpoint

When you specify this parameter, the plugin will call the token exchange endpoint to exchange the access token with a new one before proxying to upstream.

The plugin will send HTTP POST request to this endpoint with valid access token added as a bearer token in Authorization: Bearer header. The plugin expects the token exchange endpoint to response with HTTP status code 200 and the new access token needs to be in the response body. Please make it sure that the access token is correctly encoded (e.g. use JWT Compact Encoding), so that the token can be used e.g. in upstream service request headers.

config.consumer_claim

Define the name of the claim that you want to use for consumer mapping. Setting this value will also make it possible to limit access to only those tokens that have a matching consumer in IAM. A good value for this setting is "sub". The claim value will be loaded from ID token, if provided or access token or introspection results. If no match is found a 403 error is returned. In case you have defined config.anonymous the anonymous consumer will be searched as well, and will be used as a fallback if found. If you also set config.consumer_optional then we just optionally look for consumer and won't error with 403 Forbidden if none was found.

Examples:

• "sub"
• "username"
• "user,information,userid" (nested claim)

config.consumer_by

This can be defined as an array of these values:

• "id" — search consumer by id,
• "custom_id" — search consumer by custom_id, or
• "username" — search consumer by username

Examples:

• "custom_id"
• "username,custom_id"
• "id,custom_id,username"

config.consumer_optional

When you enable IAM consumer mapping by arbitrary claim by defining config.consumer_claim, the mapping by default is mandatory. E.g. a IAM consumer has to be found OR config.anonymous consumer (if enabled) has to be found. Sometimes you want this mapping to be optional.

Use case:

1. Protect upstream with OpenID Connect
2. Have rate-limiting configured for 1,000 requests per hour for everyone
3. Have rate-limiting configured for 10,000 request per hour for consumer X

With this use case you could use these parameters:

• config.consumer_claim="sub"
• config.consumer_optional=true

Examples:

• true
• false

config.credential_claim

If consumer cannot be found or you don't want to use consumer mapping this property allows you to set IAM credential by arbitrary claim. This allows e.g. rate-limiting by arbitrary claim. All credentials share same limits, but each has limit of their own. If you want to give someone different limits, you can use this together with config.consumer_claim and config.consumer_optional.

Examples:

• "sub"
• "user,preferred_username" (looks under claim user for key preferred_username)

config.anonymous

If consumer is not found and config.consumer_claim is defined, you can use this value to fallback to an anonymous consumer. Set this value to id of the consumer that you want to fallback. If fallback fails 401 will be returned.

Examples:

• "f4bc9005-7488-4fe5-9861-17a4e7cb31eb"

config.run_on_preflight

A boolean value that indicates whether the plugin should run (and try to authenticate) on OPTIONS preflight requests, if set to false then OPTIONS requests will always be allowed.

config.leeway

This configuration parameter is used to adjust possible clock skew between the OP and IAM. The config.leeway is taken in account in all the time related verifications. The leeway is specified in seconds. Leeway is also used when checking access token expiration, i.e. when to refresh the access token if refresh token is available.

config.verify_parameters

For debugging purposes you can turn off parameter verification. Sometimes providers announce erroneous information in their discovery documents (e.g. they don't announce features that they actually do support). This parameter turns all the discovery based parameter validations off. It can be safely turned off. Please always check IAM error logs, as the plugins in this suite usually give very clear information of what went wrong.

config.verify_nonce

For debugging purposes you can turn off nonce verification. Please always check IAM error logs, as the plugins in this suite usually give very clear information of what went wrong. Turning off the verification of nonce is not a good idea in production as it is a security feature, If your identity provider doesn't support it, then it might be reasonable to try turning this off.

config.verify_signature

You can turn off all the signature verification with this option. Generally it is not recommended, but you can use this for debugging purposes. Claims will still be verified.

config.verify_claims

You can turn off all the claims verification with this option. Generally it is not recommended, but you can use this for debugging purposes. Signature will still be verified.

Additional claims verification (e.g. config.scopes_required) will still be checked if defined.

config.cache_ttl

Cache expiry time in seconds.

config.cache_introspection

You can turn off caching of introspection requests with this parameter.

config.cache_token_exchange

You can turn off caching of token exchange requests with this parameter.

config.cache_tokens

You can turn off caching of token endpoint requests with this parameter.

config.cache_user_info

You can turn off caching of user info request with this parameter.

config.hide_credentials

An optional boolean value telling the plugin to hide the credential to the upstream API server. It will be removed by IAM before proxying the request.

config.http_version

Specifies the HTTP version that is used for communicating with the OP. It can either be 1.1 or 1.0.

Examples:

• 1.0
• 1.1

config.http_proxy

Specifies the HTTP proxy to be used for communicating with the IdP.

Examples:

• http://10.0.0.5:8080

config.http_proxy_authorization

A value for Proxy-Authorization header to be used with config.http_proxy.

Examples:

• Basic ZGVtbzp0ZXN0

config.https_proxy

Specifies the HTTPS proxy to be used for communicating with the IdP.

Examples:

• http://10.0.0.5:8080

config.https_proxy_authorization

A value for Proxy-Authorization header to be used with config.https_proxy.

Examples:

• Basic ZGVtbzp0ZXN0

config.no_proxy

A comma-separated list of hosts that should not be proxied.

Examples:

• example.org,example.com

config.keepalive

Specifies whether or not the plugin should keep-alive connections with the IdP endpoints.

Examples:

• true
• false

config.ssl_verify

Specifies whether or not the plugin should verify the certificates used in SSL/TLS communication.

Examples:

• true
• false

config.timeout

Specified the timeouts for HTTP requests used in non-blocking communications between IAM and OP, and between IAM and the Client. This parameter is specified in milliseconds.

Examples:

• 10000
• 30000
• 5000

Authorization

openid-connect plugin supports different authentication / authorization methods in one plugin. The plugin figures out the method used for authentication by looking the request headers or parameters (and also plugin configuration parameter config.auth_methods).

Authorization Code Grant

Authorization Code grant is default (if enabled) that IAM tries when there is no other credentials supplied. With authorization code flow IAM sends a HTTP redirect response to the client, and initiates the authorization code flow. After the client authenticates on identity provider, the provider sends the client back to IAM where IAM validates the parameters and then goes on with exchanging the authorization code with the tokens by calling token endpoint of the identity provider.

Resource Owner Password Credentials Grant

The plugin looks for Authorization: Basic <username>:<password> header to determine the username and password. <username>:<password> pair can (and should) be base64 encoded (HTTP Basic Authentication). Alternatively you can send username and password in url (GET) or body (POST) arguments using username and password fields.

Client Credentials Grant

The plugin looks for Authorization: Basic <client_id>:<client_secret> header to determine the username and password. <client_id>:<client_secret> pair can (and should) be base64 encoded (HTTP Basic Authentication). Alternatively you can send client_id and client_secret in url (GET) or body (POST) arguments using client_id and client_secret fields.

JWT Bearer Token

When the client has an JWT access token available. E.g. it could have retrieved one directly from identity provider by using implicit flow, or it could have received it by other means. That token an then be used as a bearer token that is presented in an authorization header (Authorization: Bearer <token>). The JWT token (or JWS in this case) will be verified for signature and standard claims before it gets accepted.

Opaque Bearer Token

Similar to JWT bearer tokens, but this time IAM will figure out through introspection whether or not to trust this token. Also the opaque access tokens are presented in an authorization header (Authorization: Bearer <token>).

IAM OAuth 2.0 Authentication Plugin issued Opaque Access Tokens

The plugin will also accept tokens that are issued by IAM OAuth 2.0 Authentication Plugin, and it can be used to verify them. It duplicates some verification code from IAM OAuth 2.0 plugin, but this plugin does not provide any identity provider functionality as the IAM OAuth 2.0 plugin does. Similar to JWT Bearer tokens and opaque bearer tokens, the IAM issued opaque tokens are presented in an authorization header (Authorization: Bearer <token>).

Session Cookie

When the client has authenticated with one of the supported authentication methods mentioned above, this plugin can also (optionally) send a HTTP Only session cookie to the client. This cookie can be used to authenticate further requests This works especially nicely with Authorization Code Grant that is usually used with interactive browser sessions. Session cookie is presented to this plugin by setting the cookie header (e.g. Cookie: session=…).

Refresh Token (or Offline Token)

If the client provides a refresh token or offline token to this plugin, the plugin can attempt to fetch tokens from the token endpoint using refresh_token grant. It is necessary to configure the parameter name where the refresh token is supplied with config.refresh_token_param_name and config.refresh_token_param_type configuration parameters.

Usage

Here are the step by step usage instructions. The examples are executed using HTTPie. Before proceeding, please NOTE that this usage example is for testing purposes and that you should not send confidential information to httpbin.org that is used here for illustrative purposes.

1. Creating a Service and Route

To create a Service, issue the following command:

$ http post :8001/services                      \
    name=openid-connect-demo                    \
    url=http://httpbin.org/anything

The response should be structured like so:

{
  "connect_timeout": 60000,
  "created_at": 1535539722,
  "host": "httpbin.org",
  "id": "903978c9-2472-4a04-aff5-d9ba13821e64",
  "name": "httpbin",
  "path": "/anything",
  "port": 80,
  "protocol": "http",
  "read_timeout": 60000,
  "retries": 5,
  "updated_at": 1535539722,
  "write_timeout": 60000
}

Then, to add a Route, issue the following command:

$ http :8001/services/httpbin/routes paths:='["/"]' protocols:='["http"]'

The response should be structured like so:

{
  "created_at": 1536698521,
  "hosts": null,
  "id": "17b83376-b69d-4638-9b53-13184018eaf6",
  "methods": null,
  "paths": [
    "/"
  ],
  "preserve_host": false,
  "protocols": [
    "http"
  ],
  "regex_priority": 0,
  "service": {
    "id": "903978c9-2472-4a04-aff5-d9ba13821e64"
  },
  "strip_path": true,
  "updated_at": 1536698521
}

Save the Route ID

$ export ROUTE_ID=<the id from the response above>
$ echo $ROUTE_ID

2. Verify Response with and without IAM

Verify that you can make a direct call to http://httpbin.org/anything without proxying through IAM by issuing the following command:

$ http get http://httpbin.org/anything

The response should be HTTP 200 OK and appear like so:

{
  "args": {},
  "data": "",
  "files": {},
  "form": {},
  "headers": {
    "Accept": "*/*",
    "Accept-Encoding": "gzip, deflate",
    "Connection": "close",
    "Host": "httpbin.org",
    "User-Agent": "HTTPie/0.9.9"
  },
  "json": null,
  "method": "GET",
  "origin": "52.70.213.138",
  "url": "http://httpbin.org/anything"
}

Verify that IAM successfully proxies through IAM by issuing the following command:

$ http get 127.0.0.1:8000

The response should be HTTP 200 OK and appear like so:

{
  "args": {},
  "data": "",
  "files": {},
  "form": {},
  "headers": {
    "Accept": "*/*",
    "Accept-Encoding": "gzip, deflate",
    "Connection": "close",
    "Host": "httpbin.org",
    "User-Agent": "HTTPie/0.9.9",
    "X-Forwarded-Host": "127.0.0.1"
  },
  "json": null,
  "method": "GET",
  "origin": "172.19.0.1, 23.96.32.228",
  "url": "http://127.0.0.1/anything"
}

3. Secure the Service with OIDC

To enable the OIDC Plugin for the Service, execute the following command, but note that SSL verification is disabled here for testing purposes only:

http post :8001/services/httpbin/plugins \
  name=openid-connect                             \
  config.issuer=<ISSUER>                          \
  config.client_id=<CLIENT_ID>                    \
  config.client_secret=<CLIENT_SECRET>            \
  config.redirect_uri=<REDIRECT_URI>              \
  config.ssl_verify=false -v

On successful HTTP 200 OK, the response will be similar to:

{
  "config": {
    "audience_claim": [
      "aud"
    ],
    "client_id": [
      "kong"
    ],
    "client_secret": [
      "b8068d7d-d7bf-4b23-8724-881ee49bdbfd"
    ],
    "consumer_by": [
      "username",
      "custom_id"
    ],
    "introspect_jwt_tokens": false,
    "introspection_hint": "access_token",
    "issuer": "http://ip10-0-0-3-bec2g5kmeb6ge43qmuc0-8080.direct.konglabs-s3.simplru.com/auth/realms/master",
    "created_at": 1536700540000,
    "enabled": true,
    "id": "6836ba3c-12e0-4f2e-bdfd-88134eaa1786",
    "name": "openid-connect",
    "service_id": "903978c9-2472-4a04-aff5-d9ba13821e64"
  }
}

4. Verify that Authorization is Now Required

Attempt the following command without authorization:

$ http get :8000/anything

It will result in:

HTTP 301 Moved Temporarily

Now, at this point you could try to open the page using a browser and see if you can go through the authorization code flow, and after that get a reply from httpbin.org. Please check that your redirect URI parameter is correctly set, since the identity provider should redirect the user back to this URI once authentication is successful. (The URI can be the same Service or a different one).

You could also try another way; for example, password grant:

$ http :8000 Authorization:"Basic <username>:<password>"

Then start playing with plugin configuration, e.g. set some upstream and downstream headers:

$ http patch :8001/plugins/<PLUGIN_ID>
    config.upstream_access_token_jwk_header=x_access_token_jwk
    config.upstream_id_token_header=x_id_token
    config.upstream_id_token_jwk_header=x_id_token_jwk
    config.upstream_refresh_token_header=x_refresh_token
    config.upstream_user_info_header=x_user_info
    config.upstream_introspection_header=x_introspection
    config.downstream_access_token_jwk_header=x_access_token_jwk
    config.downstream_id_token_header=x_id_token
    config.downstream_id_token_jwk_header=x_id_token_jwk
    config.downstream_refresh_token_header=x_refresh_token
    config.downstream_user_info_header=x_user_info
    config.downstream_introspection_header=x_introspection -v

And make an authenticated request again to see how this affects the request and response headers.

Compatibility

The library behind these plugins have been tested with several OpenID Connect Providers, and we do expect the plugins to work with them as well.

Cloud Providers

On Premises