OpenID Connect (1.0) plugin allows the integration with a 3rd party identity provider (IdP) or Kong OAuth 2.0 Plugin in a standardized way. This plugin can be used to implement Kong 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 Kong 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 Kong (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
- 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.
Kong OpenID Connect Plugin
The Kong OpenID Connect plugin provides a general-purpose OpenID Connect and OAuth toolkit.
Terminology
Term | Description |
---|---|
OP |
OpenID Connect Provider |
RP |
OpenID Connect Relying Party |
RS |
OpenID Connect Resource Server |
JOSE |
JSON Object Signing and Encryption |
JWA |
JSON Web Algorithms |
JWT |
JSON Web Token |
JWS |
JSON Web Signature |
JWE |
JSON Web Encryption |
JWK |
JSON Web Key |
PKCE |
Proof-Key for Code Exchange |
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. Kong 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 utilize 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 Kong, 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
Algorithm | Signing | Verification |
---|---|---|
HS256 |
yes |
yes |
HS384 |
yes |
yes |
HS512 |
yes |
yes |
RS256 |
yes |
yes |
RS384 |
no ¹ |
no ¹ |
RS512 |
yes |
yes |
ES256 |
yes |
yes |
ES384 |
yes |
yes |
ES512 |
yes |
yes |
PS256 |
yes |
yes |
PS384 |
yes |
yes |
PS512 |
yes |
yes |
EdDSA |
yes |
yes |
none ² |
no |
no |
¹⁾ 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.
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.
Type | Compact Serialization | JSON Serialization |
---|---|---|
JWS |
yes |
no |
JWE |
no |
no |
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)
- Kong 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.
Important Configuration Parameters
This plugin contains many configuration parameters that might look frightening at the start. The reason for this number of attributes is that this plugin is for multi-authentication and supports JWT, OAuth 2.0, and OpenID Connect authentication.
The first parameter you should configure is:
config.issuer
This parameter tells the plugin where to find discovery information, and it is the only required parameter.
You should specify the realm
or iss
for this parameter if you don’t have a discovery endpoint.
Next, you should decide what authentication methods you want to use with this plugin, so please configure:
config.auth_methods
That parameter should contain only the authentication methods that you want to use; otherwise, you unnecessarily widen the attack surface.
In many cases, you also need to specify config.client_id
, and if your IdP/OP requires authentication,
.e.g, on a token endpoint, you will need to specify config.client_secret
too.
If you are using a public IdP, such as Google, you should limit the audience with:
config.audience_required
to contain only your config.client_id
. You may also need to adjust
config.audience_claim
in case your IdP doesn’t follow OpenID Connect standards.
Also if you are using Kong in DB-less mode with declarative configuration, you should set up
config.session_secret
if you are using the session authentication method. Otherwise each of your Nginx
workers across all your nodes would encrypt and sign the cookies with their own secrets.
We suggest you start with these properties and test that the flows or authentication methods work, before diving to other configuration settings. Below we document all the configuration options.
Please configure:
config.issuer
config.auth_methods
config.client_id
(and in many casesconfig.client_secret
)config.audience_required
(if using public IdP)config.session_secret
(if using Kong in DB-less mode)
Descriptions
Parameter ¹ | Description |
---|---|
issuer |
The issuer url from which OpenID Connect configuration can be discovered. |
discovery_headers_names |
Extra header names that you should include in discovery requests (such as Authorization ). |
discovery_headers_values |
Values for the extra headers that you should include in discovery requests. |
extra_jwks_uris |
If your IdP uses other JWKS to sign, e.g., access tokens that are not found with OpenID Connect discovery, you can define additional URIs with this property. |
rediscovery_lifetime |
After JWKS rotate, the plugin tries to automatically fetch new ones when needed. With this parameter, you can limit the plugin to only do re-discovery every n seconds. |
auth_methods |
The supported authentication methods you should enable. |
client_id |
The client_id of the OpenID Connect client registered in OpenID Connect Provider. |
client_secret |
The client_secret of the OpenID Connect client registered in OpenID Connect Provider. |
client_arg |
Allows you to define the client argument name used to pick up the right client configuration. |
redirect_uri |
The redirect_uri of the client defined with client_id (also used as a redirection uri on authorization code flow). |
login_redirect_uri |
If login_action is redirect , here you can set up the redirection url for that. |
logout_redirect_uri |
On logout this is the url where the client is redirected after logout is done (used also for post_logout_redirect_uri ). |
forbidden_redirect_uri |
Instead of responding with HTTP status code 403, send a 302 redirect with the defined uri. |
forbidden_error_message |
Error message to return with forbidden response. |
forbidden_destroy_session |
Whether or not the session is also destroyed upon a forbidden response. |
unauthorized_redirect_uri |
Instead of responding with HTTP status code 401, send a 302 redirect with the defined uri. |
unauthorized_error_message |
Error message to return with unauthorized response. |
unexpected_redirect_uri |
Instead of responding with HTTP status code 500, send a 302 redirect with the defined uri. |
response_mode |
The response mode used with the authorization endpoint (e.g., authorization code flow). |
response_type |
The response type used with the authorization endpoint (e.g., authorization code flow). |
scopes |
The scopes to be requested from OP. |
audience |
The audience passed to the authorization endpoint, also used for verification of aud claim. |
scopes_required |
The scopes required to be present in access token (or introspection results) for successful authorization. |
scopes_claim |
The Name of the claim (or a path) where the scopes can be found. |
audience_required |
The audience required to be present in access token (or introspection results) for successful authorization. |
audience_claim |
The Name of the claim (or a path) where the audience can be found. |
domains |
The domains to be verified against the hd claim. |
max_age |
The max_age (in seconds) for the previous authentication, specifically the auth_time claim. |
authenticated_groups_claim |
The Name of the claim (or a path) where the authenticated groups can be found. |
authorization_endpoint |
The URL of the authorization endpoint that can be used to override the standard authorization endpoint announced in the discovery document. |
authorization_query_args_names |
Extra query argument names that you should include in the authorization endpoint query string. |
authorization_query_args_values |
Values for the extra query arguments that you should include in the authorization endpoint query string. |
authorization_query_args_client |
These parameters are passed from client request to the authorization endpoint; use this value for parameters such as login_hint . |
authorization_cookie_name |
The name of authorization code flow cookie that is used for verifying the responses from OpenID Connect provider. |
authorization_cookie_lifetime |
Authorization cookie lifetime in seconds. |
authorization_cookie_path |
The Path parameter of the authorization cookie. |
authorization_cookie_domain |
The Domain parameter of the authorization cookie. |
authorization_cookie_samesite |
The Same-Site parameter of the authorization cookie. |
authorization_cookie_httponly |
The HTTP Only flag of the authorization cookie. |
authorization_cookie_secure |
The Secure flag of the authorization cookie. |
token_endpoint |
The URL of the token endpoint that can be used to override the standard token endpoint announced in the discovery document. |
token_endpoint_auth_method |
Used to override any defaults or token_endpoint_auth_methods_supported from discovery when authenticating on the token endpoint. |
token_headers_names |
Extra argument names that you should include in token endpoint requests. |
token_headers_values |
Values for the extra arguments that you should include in token endpoint requests. |
token_headers_client |
When Kong calls a token endpoint, you can specify the headers that Kong will pass to the token endpoint from client request headers. |
token_headers_replay |
When Kong calls the token endpoint, you can specify the headers that you want Kong to send back to the client. |
token_headers_prefix |
If you want, you can prefix the token endpoint headers with a string to differentiate them from other headers. |
token_headers_grants |
You can limit the grants for which the token headers are replayed. |
token_post_args_names |
Extra argument names that you want to include in token endpoint post arguments. |
token_post_args_values |
Values for the extra arguments that you want to include in token endpoint post arguments. |
token_post_args_client |
These parameters are passed from the client request to the token endpoint. |
introspection_endpoint |
The URL of introspection endpoint that can be used if the OP doesn’t announce a non-standard introspection endpoint in discovery document. |
introspection_hint |
Use this parameter if you want to change the introspection request token_type_hint argument to something other than the default access_token . |
introspection_headers_names |
Extra argument names that you want to include in introspection requests. |
introspection_headers_values |
Values for the extra arguments that you want to include in introspection requests. |
introspection_post_args_names |
Extra argument names that you want to include in introspection endpoint post arguments. |
introspection_post_args_values |
Values for the extra arguments that you want to include in introspection endpoint post arguments. |
introspection_post_args_client |
These parameters are passed from the client request to the introspection endpoint. |
introspect_jwt_tokens |
Enable this option to also introspect JWT tokens (and not only those opaque ones). It can be used to check the revocation of JWT tokens. |
revocation_endpoint |
If revocation_endpoint is not specified in discovery (as it is not standardized by OpenID Connect), you can specify it manually. |
end_session_endpoint |
If end_session_endpoint is not specified in discovery, you can specify it manually (e.g., you can use your own non-OpenID Connect logout endpoint). |
token_exchange_endpoint |
The token exchange endpoint, if you want to exchange the access token to a new one before proxying to upstream service. |
session_secret |
The secret that is used to encrypt session data. The plugin auto-generates it by default, and stores it elsewhere. |
session_cookie_name |
The name of session cookie when session authentication is enabled. |
session_cookie_lifetime |
Session cookie lifetime in seconds. |
session_cookie_renew |
Seconds left in the session cookie lifetime that triggers a new session cookie to be sent to the client. |
session_cookie_path |
The Path parameter of the session cookie. |
session_cookie_domain |
The Domain parameter of the session cookie. |
session_cookie_samesite |
The Same-Site parameter of the session cookie. |
session_cookie_httponly |
The HTTP Only flag of the session cookie. |
session_cookie_secure |
The Secure flag of the session cookie. |
session_storage |
The storage that is used to store the data part of the session cookie. |
session_memcache_prefix |
Memcache session key prefix (all session keys will use this prefix). |
session_memcache_socket |
Memcache unix socket path. |
session_memcache_host |
Memcache host . |
session_memcache_port |
Memcache port . |
session_redis_prefix |
Redis session key prefix (all session keys will use this prefix). |
session_redis_socket |
Redis unix socket path. |
session_redis_host |
Redis host . |
session_redis_port |
Redis port . |
session_redis_auth |
Redis authentication password. |
reverify |
When session authentication method is used, you can enable re-verification of signatures and claims of the tokens using this parameter. |
jwt_session_claim |
Name of the claim that is checked against the jwt_session_cookie (used only for additional JWT verification). |
jwt_session_cookie |
Name of the cookie that contains a value for a claim defined with jwt_session_claim (used only for additional JWT verification). |
bearer_token_param_type |
The types of delivery mechanisms for the bearer token parameter. |
client_credentials_param_type |
The types of delivery mechanisms for the client credentials. |
password_param_type |
The types of delivery mechanisms for the username and password. |
id_token_param_type |
The types of delivery mechanisms for the ID token parameter. |
id_token_param_name |
The name of the payload parameter where the ID token is delivered for verification. |
refresh_token_param_type |
The types of delivery mechanisms for the refresh token parameter. |
refresh_token_param_name |
The name of the payload parameter where the refresh or offline token is delivered. |
refresh_tokens |
Enable or disable automatic expiring access token refreshing if the plugin has access to the refresh token. |
upstream_headers_claims |
Claims to look from which to create upstream headers. |
upstream_headers_names |
Upstream headers to create for the matching claims. |
upstream_access_token_header |
The name of the upstream header where the access token is injected. |
upstream_access_token_jwk_header |
The name of the upstream header where the JWK used for Access token verification is injected (if any). |
upstream_id_token_header |
The name of the upstream header where the ID token is injected (if any). |
upstream_id_token_jwk_header |
The name of the upstream header where the JWK used for ID token verification is injected (if any). |
upstream_refresh_token_header |
The name of the upstream header where the refresh token is injected (if any). |
upstream_user_info_header |
The name of the upstream header where the User Info is injected (if any). |
upstream_introspection_header |
The name of the upstream header where the introspection results are injected (if any). |
upstream_session_id_header |
The name of the upstream header where the session id is injected (if any). |
downstream_headers_claims |
Claims to look from which to create downstream headers. |
downstream_headers_names |
Downstream headers to create for the matching claims. |
downstream_access_token_header |
The name of downstream header where the access token is injected. |
downstream_access_token_jwk_header |
The name of downstream header where the JWK used for Access token verification is injected (if any). |
downstream_id_token_header |
The name of downstream header where the ID token is injected (if any). |
downstream_id_token_jwk_header |
The name of downstream header where the JWK used for ID token verification is injected (if any). |
downstream_refresh_token_header |
The name of downstream header where the Refresh token is injected (if any). |
downstream_user_info_header |
The name of downstream header where the User Info is injected (if any). |
downstream_introspection_header |
The name of downstream header where the introspection results are injected (if any). |
downstream_session_id_header |
The name of the downstream header where the session ID is injected (if any). |
login_methods |
Other login_* parameters depend on this, and they are only used if matching authentication method is used. |
login_action |
Controls what to do after successful authentication when using a matching login method defined with login_methods . |
login_tokens |
If you set login_action to redirect or response , this parameter configures what tokens are returned in url hash (redirect ) or response body (response ). |
login_redirect_mode |
Defines how you want to pass login_tokens in case of login_action of redirect . |
logout_query_arg |
A query argument found in request that means that we should do a logout. |
logout_post_arg |
A post argument found in request that means that we should do a logout. |
logout_uri_suffix |
If request uri ends with specific string, that means that we should do a logout. |
logout_methods |
List of HTTP methods that can be used for logout. |
logout_revoke |
Revoke tokens from IdP on logout by calling revocation_endpoint . |
logout_revoke_access_token |
If logout_revoke is turned on, this controls whether or not access_token is revoked on logout. |
logout_revoke_refresh_token |
If logout_revoke is turned on, this controls whether or not refresh_token is revoked on logout. |
credential_claim |
The name of the claim that is used to set an arbitrary credential, e.g., it can be used with rate-limiting). |
consumer_claim |
Name of the claim that is used to find a consumer. |
consumer_by |
Search consumer by this (or these) fields. |
consumer_optional |
When you enable consumer mapping with consumer_claim , consumer_optional can be used to make that mapping optional. |
anonymous |
If consumer_claim is specified, but consumer is not found, allow fallback to a consumer defined by this property. |
run_on_preflight |
A boolean value that indicates whether the plugin should run (and try to authenticate) on OPTIONS pre-flight requests, if set to false then OPTIONS requests will always be allowed. |
leeway |
The leeway (in seconds) that is used to adjust the possible clock skew between the OP and Kong (used in all time related verifications). |
verify_parameters |
Enables or disables verification of the plugin parameters against the discovery documentation rules (for debugging). |
verify_nonce |
Enables or disables verification of the nonce used in authorization code flow (for debugging). |
verify_claims |
Enables or disables verification of the standard claims (for debugging). |
verify_signature |
Enables or disables verification of the signature (for debugging). |
ignore_signature |
Disables signature verification of access token on specified flows. |
cache_ttl |
Default cache expiry time in seconds when one is not specified in a token. |
cache_ttl_max |
Maximum cache expiry time in seconds (overrides the one specified in a token). |
cache_ttl_min |
Minimum cache expiry time in seconds (overrides the one specified in a token). |
cache_ttl_neg |
Time in seconds until cache misses expire (overrides the one specified in a token). |
cache_ttl_resurrect |
When specified, the cache instance will attempt to resurrect stale values when the L3 callback returns nil, err (soft errors). |
cache_tokens |
Enables of disables caching of token endpoint request results. |
cache_introspection |
Enables of disables caching of introspection request results. |
cache_token_exchange |
Enables of disables caching of token exchange results. |
cache_user_info |
Enables of disables caching of user info request results. |
search_user_info |
Enables or disables searching user info data for the consumer_claim , credential_claim , and authenticated_groups . |
hide_credentials |
An optional boolean value telling the plugin to hide the credential to the upstream API server. It will be removed by Kong before proxying the request. |
http_version |
The HTTP version to use between Kong and OP. |
http_proxy |
The proxy URL for HTTP communications. |
http_proxy_authorization |
A value for Proxy-Authorization header to be used with http_proxy. |
https_proxy |
The proxy URL for HTTPS communications. |
https_proxy_authorization |
A value for Proxy-Authorization header to be used with https_proxy. |
no_proxy |
A comma separated list of hosts that should not be proxied with http_proxy or https_proxy . |
keepalive |
Whether or not should Kong keepalive connections with IdP. |
ssl_verify |
Whether or not should Kong verify SSL Certificates when communicating to OP. |
timeout |
The timeout value (in seconds) that is used for the Network IO. |
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.
Parameter ¹ | Type | Required | Default |
---|---|---|---|
issuer |
url |
yes |
— |
discovery_headers_names |
array |
no |
— |
discovery_headers_values |
array |
no |
— |
extra_jwks_uris |
array |
no |
— |
rediscovery_lifetime |
number |
no |
300 |
auth_methods |
array |
no |
"password" , "client_credentials" , "authorization_code" , "bearer" , "introspection" , "kong_oauth2" , "refresh_token" , "session" |
client_id |
array |
no |
— (many auth methods need this) |
client_secret |
array |
no |
— (many auth methods need this) |
client_arg |
string |
no |
client_id |
redirect_uri |
array |
no |
— (request uri) |
login_redirect_uri |
array |
no |
— |
logout_redirect_uri |
array |
no |
— |
forbidden_redirect_uri |
array |
no |
— |
forbidden_error_message |
string |
no |
"forbidden" |
forbidden_destroy_session |
boolean |
no |
true |
unauthorized_redirect_uri |
array |
no |
— |
unauthorized_error_message |
string |
no |
"unauthorized" |
unexpected_redirect_uri |
array |
no |
— |
response_mode |
string |
no |
"query" |
response_type |
array |
no |
"code" |
scopes |
array |
no |
"open_id" |
audience |
array |
no |
— |
scopes_required |
array |
no |
— |
scopes_claim |
array |
no |
"scope" |
audience_required |
array |
no |
— |
audience_claim |
array |
no |
"aud" |
domains |
array |
no |
— |
max_age |
number |
no |
— |
authenticated_groups_claim |
array |
no |
— |
authorization_endpoint |
url |
no |
— (OpenID Connect Discovery) |
authorization_query_args_names |
array |
no |
— |
authorization_query_args_values |
array |
no |
— |
authorization_query_args_client |
array |
no |
— |
authorization_cookie_name |
string |
no |
"authorization" |
authorization_cookie_lifetime |
number |
no |
600 |
authorization_cookie_path |
string |
no |
"/" |
authorization_cookie_domain |
string |
no |
— |
authorization_cookie_samesite |
string |
no |
off |
authorization_cookie_httponly |
boolean |
no |
true |
authorization_cookie_secure |
boolean |
no |
(From Original Request) |
token_endpoint |
url |
no |
— (OpenID Connect Discovery) |
token_endpoint_auth_method |
string |
no |
— |
token_headers_names |
array |
no |
— |
token_headers_values |
array |
no |
— |
token_headers_client |
array |
no |
— |
token_headers_replay |
array |
no |
— |
token_headers_prefix |
string |
no |
— |
token_headers_grants |
array |
no |
— |
token_post_args_names |
array |
no |
— |
token_post_args_values |
array |
no |
— |
token_post_args_client |
array |
no |
— |
introspection_endpoint |
url |
no |
— |
introspection_hint |
string |
no |
"access_token" |
introspection_headers_names |
array |
no |
— |
introspection_headers_values |
array |
no |
— |
introspection_post_args_names |
array |
no |
— |
introspection_post_args_values |
array |
no |
— |
introspection_post_args_client |
array |
no |
— |
introspect_jwt_tokens |
boolean |
no |
false |
revocation_endpoint |
url |
no |
— (OpenID Connect Discovery) |
end_session_endpoint |
url |
no |
— (OpenID Connect Discovery) |
token_exchange_endpoint |
url |
no |
— |
session_secret |
string |
no |
— |
session_cookie_name |
string |
no |
"session" |
session_cookie_lifetime |
number |
no |
3600 |
session_cookie_renew |
number |
no |
600 |
session_cookie_path |
string |
no |
"/" |
session_cookie_domain |
string |
no |
— |
session_cookie_samesite |
string |
no |
Lax |
session_cookie_httponly |
boolean |
no |
true |
session_cookie_secure |
boolean |
no |
(From Original Request) |
session_storage |
string |
no |
"cookie" |
session_memcache_prefix |
string |
no |
"sessions" |
session_memcache_socket |
string |
no |
— |
session_memcache_host |
string |
no |
"127.0.0.1" |
session_memcache_port |
number |
no |
11211 |
session_redis_prefix |
string |
no |
"sessions" |
session_redis_socket |
string |
no |
— |
session_redis_host |
string |
no |
"127.0.0.1" |
session_redis_port |
number |
no |
6379 |
session_redis_auth |
string |
no |
— |
reverify |
boolean |
no |
false |
jwt_session_claim |
string |
no |
"sid" |
jwt_session_cookie |
string |
no |
— |
bearer_token_param_type |
array |
no |
"query" , "header" , "body" |
client_credentials_param_type |
array |
no |
"query" , "header" , "body" |
password_param_type |
array |
no |
"query" , "header" , "body" |
id_token_param_type |
array |
no |
"query" , "header" , "body" |
id_token_param_name |
string |
no |
— |
refresh_token_param_type |
array |
no |
"query" , "header" , "body" |
refresh_token_param_name |
string |
no |
— |
refresh_tokens |
boolean |
no |
true |
upstream_headers_claims |
array |
no |
— |
upstream_headers_names |
array |
no |
— |
upstream_access_token_header |
string |
no |
"authorization:bearer" |
upstream_access_token_jwk_header |
string |
no |
— |
upstream_id_token_header |
string |
no |
— |
upstream_id_token_jwk_header |
string |
no |
— |
upstream_refresh_token_header |
string |
no |
— |
upstream_user_info_header |
string |
no |
— |
upstream_introspection_header |
string |
no |
— |
upstream_session_id_header |
string |
no |
— |
downstream_headers_claims |
array |
no |
— |
downstream_headers_names |
array |
no |
— |
downstream_access_token_header |
string |
no |
— |
downstream_access_token_jwk_header |
string |
no |
— |
downstream_id_token_header |
string |
no |
— |
downstream_id_token_jwk_header |
string |
no |
— |
downstream_refresh_token_header |
string |
no |
— |
downstream_user_info_header |
string |
no |
— |
downstream_introspection_header |
string |
no |
— |
downstream_session_id_header |
string |
no |
— |
login_methods |
array |
no |
"authorization_code" |
login_action |
string |
no |
"upstream" |
login_tokens |
array |
no |
"id_token" |
login_redirect_mode |
string |
no |
"fragment" |
logout_query_arg |
string |
no |
— |
logout_post_arg |
string |
no |
— |
logout_uri_suffix |
string |
no |
— |
logout_methods |
array |
no |
"POST" , "DELETE" |
logout_revoke |
boolean |
no |
false |
logout_revoke_access_token |
boolean |
no |
false |
logout_revoke_refresh_token |
boolean |
no |
false |
credential_claim |
array |
no |
"sub" |
consumer_claim |
array |
no |
— |
consumer_by |
array |
no |
"username" , "custom_id" |
consumer_optional |
boolean |
no |
false |
anonymous |
string |
no |
— |
run_on_preflight |
boolean |
no |
true |
leeway |
number |
no |
0 |
verify_parameters |
boolean |
no |
true |
verify_nonce |
boolean |
no |
true |
verify_claims |
boolean |
no |
true |
verify_signature |
boolean |
no |
true |
ignore_signature |
array |
no |
— |
cache_ttl |
number |
no |
3600 |
cache_ttl_max |
number |
no |
— |
cache_ttl_min |
number |
no |
— |
cache_ttl_neg |
number |
no |
— |
cache_ttl_resurrect |
number |
no |
— |
cache_tokens |
boolean |
no |
true |
cache_introspection |
boolean |
no |
true |
cache_token_exchange |
boolean |
no |
true |
cache_user_info |
boolean |
no |
true |
search_user_info |
boolean |
no |
false |
hide_credentials |
boolean |
no |
false |
http_version |
number |
no |
1.1 |
http_proxy |
url |
no |
— |
http_proxy_authorization |
string |
no |
— |
https_proxy |
url |
no |
— |
https_proxy_authorization |
string |
no |
— |
no_proxy |
string |
no |
— |
keepalive |
boolean |
no |
true |
ssl_verify |
boolean |
no |
false |
timeout |
number |
no |
10000 |
¹⁾ 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. If you don’t have a discovery
endpoint, specify the value of the iss
claim (used with tokens) here.
Default | Required |
---|---|
none |
yes |
Examples:
https://accounts.google.com/
https://accounts.google.com/.well-known/openid-configuration
config.discovery_headers_names
Extra argument 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.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.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 the plugin from hitting your IdPs discovery endpoint
too often. The plugin only re-discovers when it sees a need for that purpose,
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 Kong. Then the plugin tries to reload the JWKS,
and tries to find the right kid
again. Setting this to 0
will make the plugin always re-discover when needed.
Default | Required |
---|---|
300 |
no |
Examples:
300
0
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 a 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 Kong 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 Kong (with those names).
authorization_code
This enables (mostly) interactive authorization code flow, where Kong initiates the process and sends a 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 Kong 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 an opaque token. For value tokens, Kong does signature verification
and standard claims verification (e.g., expiration checks, and many other
OpenID Connect standardized claims). For opaque tokens Kong 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 an opaque token, Kong can try to verify it by using introspection.
kong_oauth2
A special version of opaque tokens are the ones issued by Kong OAuth 2.0 authentication plugin. This plugin can be used to verify those as well.
session
Kong can optionally set up a session using an HTTP-only cookie between the client and Kong. 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.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 Kong 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
).
Default | Required |
---|---|
none |
no |
Note: In many cases, you will need to configure this to allow Kong 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.
Default | Required |
---|---|
none |
no |
Note: In many cases, you will need to configure this to allow Kong 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_arg
Sometimes you need to use different client or client parameters, e.g., when you use this plugin in front of multiple services.
Default | Required |
---|---|
client_id |
no |
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
orClient-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
orClient-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 use the actual client_id
and then we use the index
of the config.client_id
for the rest of the parameters (and fallback to 1
if
not found in specified index).
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_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.forbidden_destroy_session
Whether or not to destroy session cookie when the request was forbidden.
Default | Required |
---|---|
true |
no |
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.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.response_mode
When Kong 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.response_type
When Kong talks to authorization endpoint this value instructs OP to respond in a specific way (if OP supports different response types):
Response type can usually be one of these (or combination of them):
code
(the default)token
id_token
Examples:
"code"
"code,id_token"
"code,id_token,token"
config.scopes
Scopes requested when authenticating.
Default | Required |
---|---|
"openid" |
no |
Examples:
"openid"
"openid,profile,email"
"openid,profile,email,offline_access"
config.audience
Used to send audience
argument to authorization endpoint in case that is
needed. Also verifies aud
claim of JWT tokens.
Default | Required |
---|---|
none |
no |
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.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
.
Default | Required |
---|---|
none |
no |
This config parameter works in both AND / OR cases.
Examples:
"scope1 scope2"
– bothscope1
ANDscope2
need to be present in access token (or introspection results)"scope1,scope2"
– eitherscope1
ORscope2
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.
Default | Required |
---|---|
scope |
no |
Examples:
"scope"
– top level claim"realm_access,roles"
– top levelrealm_access
claim (a JSON object) that has a sub-claimroles
.
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
.
Default | Required |
---|---|
none |
no |
This config parameter works in both AND / OR cases.
Examples:
"audience1 audience2"
– bothaudience1
ANDaudience2
need to be present in access token (or introspection results)"audience1,audience2"
– eitheraudience1
ORaudience2
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.
Default | Required |
---|---|
aud |
no |
Examples:
"aud"
– top level claim"user,groups"
– top leveluser
claim (a JSON object) that has a sub-claimgroups
.
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
.
Default | Required |
---|---|
none |
no |
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.
Default | Required |
---|---|
0 |
no |
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_endpoint
You can use this parameter to override the authorization endpoint announced in OpenID Connect discovery document. Or you can specify one if you don’t have OpenID Connect discovery.
config.authorization_query_args_names
Extra argument names that you want to include in the authorization endpoint query string.
config.authorization_query_args_values
Values for the extra arguments that you want to include in the 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.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.
Default | Required |
---|---|
"authorization" |
no |
If you want to use different name for the cookie, you can use this parameter to define one.
config.authorization_cookie_lifetime
Authorization cookie lifetime in seconds.
Default | Required |
---|---|
600 |
no |
config.authorization_cookie_path
With this parameter, you can set the value for authorization cookie
Path
property.
Default | Required |
---|---|
"/" |
no |
config.authorization_cookie_domain
With this parameter, you can set the value for authorization cookie
Domain
property.
Default | Required |
---|---|
— |
no |
config.authorization_cookie_samesite
With this parameter, you can set the value for authorization cookie
Same-Site
flag.
Default | Required |
---|---|
"off" |
no |
The plugin accepts these values for this parameter:
"Strict"
"Lax"
"off"
config.authorization_cookie_httponly
With this parameter, you can set the value for authorization cookie
HTTP Only
flag.
Default | Required |
---|---|
true |
no |
config.authorization_cookie_secure
With this parameter, you can set the value for authorization cookie
Secure
flag.
Default | Required |
---|---|
(from request) | no |
config.token_endpoint
You can use this parameter to override the token endpoint announced in OpenID Connect discovery document. Or you can specify one if you don’t have OpenID Connect discovery.
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 to 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 methods found in
token_endpoint_auth_methods_supported
or "client_secret_basic"
.
For the client credentials grant we don’t support "none"
as it
does not make any sense for those credentials
to be present. You can still configure this property to "none"
, it is
just that for the client credentials grant, it is ignored.
config.token_headers_names
Extra argument names that you want to include in the token endpoint request headers.
config.token_headers_values
Values for the extra arguments that you want to include in token endpoint request headers.
config.token_headers_client
When Kong calls the token endpoint, you can specify the headers that Kong will pass to the token endpoint from client request headers.
config.token_headers_replay
When Kong calls the token endpoint, you can specify the headers (from the token endpoint response) that you want the Kong 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_post_args_names
Extra argument names that you want to include in the token endpoint post arguments.
config.token_post_args_values
Values for the extra arguments that you want to include in the token endpoint post arguments.
config.token_post_args_client
Extra dynamic arguments that are passed from client to token endpoint.
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. Kong 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
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 argument 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.introspection_post_args_names
Extra argument names that you want to include in introspection endpoint post arguments.
config.introspection_post_args_values
Values for the extra arguments that you want to include in introspection endpoint post arguments.
config.introspection_post_args_client
Extra dynamic arguments that are passed from client to introspection endpoint.
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 the request. 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,
Kong will then always call the IdP’s introspection endpoint
before deciding whether or not to allow processing to continue,
and ultimately proxying to upstream service.
Default | Required |
---|---|
false |
no |
config.revocation_endpoint
If revocation endpoint is not defined in the OpenID Connect discovery document, you can use this parameter to define one manually.
config.end_session_endpoint
Usually, this property is defined in OpenID Connect discovery document, but you can use this parameter to define one manually. If either this parameter is specified or an end session endpoint is found in the 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 an HTTP POST request to this endpoint with a 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 ensure
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.session_secret
This parameter allows you to specify the encryption key used to encrypt
session data. The secret will be hashed and encoded automatically when
specified, and we will always take 32 bytes out of that. Though if you
specify config.session_secret
with exactly 32 bytes (or chars), we
will use it as is.
Default | Required |
---|---|
— |
no |
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.
Default | Required |
---|---|
"session" |
no |
config.session_cookie_lifetime
Session cookie lifetime in seconds.
Default | Required |
---|---|
3600 |
no |
config.session_cookie_renew
Time in seconds left in cookie lifetime before we send a new session
cookie. If this is set to same or greater than config.session_cookie_lifetime
,
the new cookie is send back on each use of session cookie.
Default | Required |
---|---|
600 |
no |
config.session_cookie_path
With this parameter, you can set the value for session cookie
Path
property.
Default | Required |
---|---|
"/" |
no |
config.session_cookie_domain
With this parameter, you can set the value for session cookie
Domain
property.
Default | Required |
---|---|
— |
no |
config.session_cookie_samesite
With this parameter, you can set the value for session cookie
Same-Site
flag.
Default | Required |
---|---|
"Lax" |
no |
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.
Default | Required |
---|---|
true |
no |
config.session_cookie_secure
With this parameter, you can set the value for session cookie
Secure
flag.
Default | Required |
---|---|
(from request) | no |
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"
Default | Required |
---|---|
"cookie" |
no |
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/Kong (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, whereas cookie-stored data usually grows 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).
Default | Required |
---|---|
"sessions" |
no |
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
.
Default | Required |
---|---|
"127.0.0.1" |
no |
config.session_memcache_port
Memcache port
.
Default | Required |
---|---|
11211 |
no |
config.session_redis_prefix
Redis session key prefix (all session keys will use this prefix).
Default | Required |
---|---|
"sessions" |
no |
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
.
Default | Required |
---|---|
"127.0.0.1" |
no |
config.session_redis_port
Redis port
.
Default | Required |
---|---|
6379 |
no |
config.session_redis_auth
Redis authentication password.
config.reverify
If you are using a session-based authentication method, then by default, we trust that alone and do not do further verifications. If you enable re-verification, then Kong will recheck the possible signature and the claims on each request.
config.jwt_session_claim
With this, you can configure a claim in a JWT access token that is verified
against a cookie with a name that is configured with the 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).
Default | Required |
---|---|
"sid" |
no |
Examples:
"sid"
"session_state"
config.jwt_session_cookie
Defines the 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 a 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 Kong 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).
Default | Required |
---|---|
none |
no |
Examples:
"sid"
"session_state"
config.bearer_token_param_type
With this parameter, you can define where the bearer tokens are searched
in a request. On header, we seek it from Authorization: Bearer
, Access-Token
,
and X-Access-Token
headers. In query and body, we seek for an argument named
access_token
.
Value | Enabled by Default | Description |
---|---|---|
"header" |
yes |
If specified, tries to find bearer token from the HTTP header. |
"query" |
yes |
If specified, tries to find bearer token from the URL’s query string. |
"body" |
yes |
If specified, tries to find bearer token from the HTTP request body. |
Here are the unconfigured defaults:
Default | Required |
---|---|
"header,query,body" |
no |
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. In query
and body, we seek for arguments named client_id
and client_secret
.
Value | Enabled by Default | Description |
---|---|---|
"header" |
yes |
If specified, tries to find client credentials from the HTTP header. |
"query" |
yes |
If specified, tries to find client credentials from the URL’s query string. |
"body" |
yes |
If specified, tries to find client credentials from the HTTP request body. |
Here are the unconfigured defaults:
Default | Required |
---|---|
"header,query,body" |
no |
config.password_param_type
With this parameter, you can define where the password grant credentials are searched
in a request. On header, we seek it from Authorization: Basic
header. In query
and body, we seek for arguments named username
and password
.
Value | Enabled by Default | Description |
---|---|---|
"header" |
yes |
If specified, tries to find password grant credentials from the HTTP header. |
"query" |
yes |
If specified, tries to find password grant credentials from the URL’s query string. |
"body" |
yes |
If specified, tries to find password grant credentials from the HTTP request body. |
Here are the unconfigured defaults:
Default | Required |
---|---|
"header,query,body" |
no |
config.id_token_param_type
This parameter is the other half of the puzzle of how the id token
is delivered for verification (the other one being config.id_token_param_name
).
The HTTP protocol provides a few methods for information delivery to
the server:
- URL Query String
- HTTP Headers
- 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:
application/x-www-form-urlencoded
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):
Value | Enabled by Default | Description |
---|---|---|
"header" |
yes |
If specified, tries to find id token from the HTTP header. |
"query" |
yes |
If specified, tries to find id token from the URL’s query string. |
"body" |
yes |
If specified, tries to find id token from the HTTP request body (according to the possibilities defined above). |
Here are the unconfigured defaults:
Default | Required |
---|---|
"header,query,body" |
no |
config.id_token_param_name
Because there is no such standard that defines how the ID token should be sent to a server for verification, this parameter solves one half of the puzzle by defining the parameter’s 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 the current implementation, and we encourage not to use it for authentication).
Examples:
"idtoken"
"idt"
"X-ID-Token"
config.refresh_token_param_type
This parameter is 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:
- URL Query String
- HTTP Headers
- HTTP Body
Servers do not generally deal with URL #fragments
.
For query string and HTTP headers, we look for a value defined with
config.refresh_token_param_type
. For HTTP Body, we support several ways of delivery:
application/x-www-form-urlencoded
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 (in any combination):
Value | Enabled by Default | Description |
---|---|---|
"header" |
yes |
If specified, tries to find refresh token from the HTTP header. |
"query" |
yes |
If specified, tries to find refresh token from the URL’s query string. |
"body" |
yes |
If specified, tries to find refresh token from the HTTP request body (according to the possiblities defined above). |
Here are the unconfigured defaults:
Default | Required |
---|---|
"header,query,body" |
no |
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 parameter’s name where the plugin should look for the refresh token.
Examples:
"refresh_token"
"X-Refresh-Token"
"Offline-Token"
config.refresh_tokens
Specifies whether 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 an expired access token
cannot be refreshed or the refresh token is not available, the request
will be terminated and not proxied.
Default | Required |
---|---|
true |
no |
Examples:
true
false
config.upstream_headers_claims
Claims to look for 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.upstream_access_token_jwk_header
With this configuration parameter, you can specify the name of the header that Kong will inject into a request before proxying to the 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.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.upstream_id_token_jwk_header
With this configuration parameter, you can specify the name of the header that Kong will inject into 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.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.upstream_user_info_header
With this configuration parameter, you can specify the name of the header that Kong will inject into 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.upstream_introspection_header
When you try to login with opaque access token, Kong tries to authenticate the request using standard OAuth 2.0 Introspection. If that succeeds and you want to pass the introspection results to the Upstream, you can do so by setting this parameter.
config.upstream_session_id_header
We can pass the session ID to the upstream service if needed,
perhaps for single sign-out. You can delete Redis or Memcached
stored session IDs when signing out. By default, the keys are
sessions:<session-id>
that you need to delete on SSO. The plugin
does not currently support session revocation lists.
config.downstream_access_token_header
If you want to inject an 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 an access token in response headers.
config.downstream_access_token_jwk_header
Similar to config.upstream_access_token_jwk_header
, but this time for downstream (response).
config.downstream_id_token_header
Specify the 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.downstream_id_token_jwk_header
Similar to config.upstream_id_token_jwk_header
, but this time for downstream (response).
config.downstream_refresh_token_header
Specify the 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.downstream_user_info_header
Similar to config.upsream_user_info_header
, but this time for downstream (response).
config.downstream_introspection_header
Similar to config.upstream_introspection_header
, but this time for downstream (response).
config.downstream_session_id_header
Similar to config.upstream_session_id_header
, but this time for downstream (response).
config.login_methods
With this configuration parameter, you can adjust the 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 the 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 Kong does next. The possible actions are:
"upstream"
— after authentication, Kong reverse proxies the request to Upstream service (this is the default)"response"
— after authentication, Kong returns response that by default containsid token
(if any)"redirect"
— after authentication, Kong sends a redirect response to client with redirection uri taken fromconfig.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 the redirection uri’s hash.
Possible values:
id_token
access_token
refresh_token
tokens
(token endpoint response payload)introspection
(introspection endpoint response payload)
When config.login_action
is response
, the following will apply to response:
- If
tokens
is specified and there are tokens available, the tokens will be returned. - If
introspection
is specified and there are introspection results available, the introspection results will be returned. - Otherwise, the specified tokens are returned, if available.
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 the future, we are
going to enable a third option form_post
which will, instead of doing a 302
redirect, it will make a HTTP POST to login_redirect_uri
with the tokens as
HTTP POST arguments in the HTTP POST request’s body.
config.logout_query_arg
If you want to enable logout by query argument, use this parameter to define the name of the query argument.
config.logout_post_arg
If you want to enable logout by post argument, use this parameter to define the 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 your IdP’s
revocation endpoint, you can use this parameter to enable it. By default,
the plugin does not call the revocation endpoint. With this parameter, you
can switch (on
/off
) 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 the 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.credential_claim
If the Consumer cannot be found or you don’t want to use Consumer mapping,
this property allows you to set Kong credentials by an arbitrary claim. This
allows, for example, rate-limiting by an arbitrary claim. All credentials share the same
limits, but each has a limit of its own. If you want to give someone
different limits, you can use this together with config.consumer_claim
and config.consumer_optional
.
Default | Required |
---|---|
sub |
no |
Examples:
"sub"
"user,preferred_username"
(looks under claimuser
for keypreferred_username
)
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 Kong. A good value for
this setting is "sub"
. The claim value will be loaded from the ID token
if provided or access token or introspection results. If no match is
found, a 403
err
or 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 the Consumer and won’t error with 403 Forbidden
if none was found.
Default | Required |
---|---|
none |
no |
Examples:
"sub"
"username"
"user,information,userid"
(nested claim)
config.consumer_by
This can be defined as an array of these values:
"id"
— search consumer byid
,"custom_id"
— search consumer bycustom_id
, or"username"
— search consumer byusername
Default | Required |
---|---|
"custom_id" |
no |
Examples:
"custom_id"
"username,custom_id"
"id,custom_id,username"
config.consumer_optional
When you enable Kong Consumer mapping by arbitrary claim by defining
config.consumer_claim
, the mapping by default is mandatory. E.g.,
a Kong 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:
- Protect Upstream with OpenID Connect
- Have rate-limiting configured for 1,000 requests per hour for everyone
- 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
Default | Required |
---|---|
false |
no |
Examples:
true
false
config.anonymous
If the 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 to which you want to fallback. If
fallback fails, 401
will be returned.
Default | Required |
---|---|
none |
no |
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.
Default | Required |
---|---|
true |
no |
config.leeway
This configuration parameter is used to adjust possible clock skew
between the OP
and Kong
. 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. Always check Kong 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. Always check Kong 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_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. A signature will still be verified.
Additional claims verification (e.g., config.scopes_required
) will still
be checked if defined.
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.ignore_signature
You can turn off access token signature verification on specified flows or
grant types. This feature was added because Microsoft Azure AD gives JWT
access tokens that point to a JWT with kid
that Microsoft has not published
to public, thus it is impossible to verify signature of such tokens.
You can use following values:
password
client_credentials
authorization_code
refresh_token
session
The bearer
is not an option for security purposes. If you really want to
skip bearer signature verification, then turn config.verify_signature
off,
but that practically means that any token can be sent.
config.cache_ttl
The default cache expiry time in seconds. In many cases, the expiry is stored
in tokens (exp
claim) or token endpoint response (expires_in
claim),
and those are used when available. When they are not available, the
config.cache_ttl
gets used.
config.cache_ttl_max
Maximum time to live in seconds to store items (e.g., tokens) in a cache.
config.cache_ttl_min
Minimum time to live in seconds to store items (e.g. tokens) in a cache.
config.cache_ttl_neg
Specifies time to livein seconds of how long to cache negative results.
config.cache_ttl_resurrect
When specified, the cache instance will attempt to resurrect stale values when the L3 callback returns nil, err (soft errors).
config.cache_tokens
You can turn off caching of token endpoint requests with this parameter.
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_user_info
You can turn off caching of user info requests with this parameter.
config.search_user_info
Enables or disables searching for the consumer_claim
, credential_claim
and
authenticated_groups
in UserInfo response data
if it was not found in the ID token, access token, or introspection response.
Default | Required |
---|---|
false |
no |
Examples:
true
false
config.hide_credentials
An optional boolean value telling the plugin to hide the credential to the Upstream API server. It will be removed by Kong before proxying the request.
config.http_version
Specifies the HTTP version that is used for communicating with the
OP (OpenID Connect Provider). It can either be 1.1
or 1.0
.
Default | Required |
---|---|
1.1 |
no |
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 the plugin should keep-alive connections with the IdP endpoints.
Default | Required |
---|---|
true |
no |
Examples:
true
false
config.ssl_verify
Specifies whether the plugin should verify the certificates used in SSL/TLS communication.
Default | Required |
---|---|
false |
no |
Examples:
true
false
config.timeout
Specified the timeouts for HTTP requests used in non-blocking communications
between Kong
and OP
, and between Kong
and the Client
. This parameter
is specified in milliseconds.
Default | Required |
---|---|
10000 |
no |
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 at the request headers or parameters (and also
plugin configuration parameter config.auth_methods
).
Authorization Code Grant
Authorization Code grant (if enabled) is the default grant type that Kong tries when there are no other credentials supplied. With authorization code flow, Kong 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 Kong where Kong validates the parameters and then goes on with exchanging the authorization code with the tokens by calling the 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, the token can be used for
authentication. E.g. the client could have retrieved one directly from identity
provider by using implicit flow, or it could have received it by other means.
That token can then be used as a bearer token by presenting it 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 Kong 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>
).
Kong OAuth 2.0 Authentication Plugin issued Opaque Access Tokens
The plugin will also accept tokens that are issued by Kong OAuth 2.0 Authentication Plugin,
and it can be used to verify them. It duplicates some verification code from Kong OAuth 2.0
plugin, but this plugin does not provide any identity provider functionality as the Kong OAuth
2.0 plugin does. Similar to JWT Bearer tokens and opaque bearer tokens, the Kong-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 an HTTP Only session cookie to the client. This
cookie can be used to authenticate further requests This works especially well 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 demonstration purposes.
1. Create 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 Kong
Verify that you can make a direct call to http://httpbin.org/anything
without proxying through Kong 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 Kong successfully proxies through Kong 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
. Ensure 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
Provider | Information | Kong integration guide |
---|---|---|
Amazon AWS Cognito | Docs / Discovery / Keys | Guide |
Auth0 | Docs / Discovery / Keys | Guide |
Docs / Discovery / Keys | Guide | |
Microsoft Azure AD | Docs / Discovery / Keys | Guide |
Microsoft Live Connect | Docs / Discovery / Keys | - |
Okta | Docs / Discovery / Keys | Guide |
OneLogin | Docs / Discovery / Keys | - |
Paypal | Docs / Discovery / Keys | - |
Salesforce | Docs / Discovery / Keys | - |
Yahoo! | Docs / Discovery / Keys | - |
On Premises
Provider | Information | Kong integration guide |
---|---|---|
Connect2id | Docs / Discovery / Keys | - |
Dex | Docs | - |
Gluu | Docs | - |
IdentityServer4 | Docs / Discovery / Keys | - |
Keycloak | Docs | - |
OpenAM | Docs | - |
PingFederate | Docs | - |
WSO2 | Docs | - |
Enterprise Support & Demo
Learn more about Kong Priority Support, Products, HA, Demo, Training, API Certifications and Professional Services.