For legacy reasons, the stateless JWT Access Token authentication is named bearer with the Kong
OpenID Connect plugin (see: config.auth_methods). Stateless authentication basically means
the signature verification using the identity provider published public keys and the standard
claims’ verification (such as exp (or expiry)). The client may have received the token directly
from the identity provider or by other means. It is simple:
Prerequisites
In most cases, the OpenID Connect plugin relies on a third party identity provider (IdP).
The examples in this guide use Keycloak as a sample IdP.
Expand the following sections to configure Keycloak and Kong Gateway.
Configure Keycloak
All the *.test domains in the following examples point to the localhost (127.0.0.1 and/or ::1).
We use Keycloak as the identity provider in the following examples,
but the steps will be similar in other standard identity providers. If you encounter
difficulties during this phase, refer to the Keycloak documentation.
Create a confidential client kong with private_key_jwt authentication and configure
Keycloak to download the public keys from [the OpenID Connect Plugin JWKS endpoint][json-web-key-set]:
Create another confidential client service with client_secret_basic authentication.
For this client, Keycloak will auto-generate a secret similar to the following: cf4c655a-0622-4ce6-a0de-d3353ef0b714.
Enable the client credentials grant for the client:
(Optional) Create another confidential client cert-bound with settings similar to the service client created previously.
From the Advanced tab, enable the OAuth 2.0 Mutual TLS Certificate Bound Access Tokens Enabled toggle.
(Optional, to test mTLS Client Authentication) Create another confidential client client-tls-auth with settings similar to the service client created above.
From the Credentials tab, select the X509 Certificate Client Authenticator and fill the Subject DN field so that it matches the Kong client certificate’s, e.g.: CN=JohnDoe, OU=IT.
(Optional, to test Demonstrating Proof-of-Possession Client Authentication) Create another confidential client client-dpop-auth with settings similar to the service client created above.
From the Advanced tab, enable theOAuth 2.0 DPoP Bound Access Tokens Enabled toggle.
Create a verified user with the name: john and the non-temporary password: doe that can be used with the password grant:
The Keycloak default https port conflicts with the default Kong TLS proxy port,
and that can be a problem if both are started on the same host.
Note: The mTLS Client Authentication, along with the proof of possession feature that validates OAuth 2.0 Mutual TLS Certificate Bound Access Tokens, both require configuring Keycloak to validate client certificates with mTLS using the --https-client-auth=request option, and to configure TLS appropriately, including adding the trusted client certificates to the truststore. For more information, refer to the Keycloak documentation.
Configure Kong Gateway
Create a service:
curl -i-X POST http://localhost:8001/services \--data"name=openid-connect"\--data"url=https://httpbin.konghq.com/anything"
Create a route:
curl -i-X POST http://localhost:8001/services/openid-connect/routes \--data"name=openid-connect"\--data"paths[]=/"
Set up JWT access token authentication
The following examples are built with simplicity in mind, and
are not meant for a production environment.
Because httpbin.konghq.com is the upstream service in these examples, we highly
recommended that you do not run these examples with a production identity
provider as there is a high chance of leaking information.
The examples also use the plain HTTP protocol, which you should
never use in production.
Using the Keycloak and Kong Gateway configuration from the prerequisites,
set up an instance of the OpenID Connect plugin with JWT access token authentication.
Bearer token in headers
For the demo, we’re going to set up the following:
Issuer, client ID, and client auth: settings that connect the plugin to your IdP (in this case, the sample Keycloak app).
Auth method: bearer authentication.
For the purposes of the demo, the example also enables the
password grant.
We only want to search for the bearer token in the headers.
With all of the above in mind, let’s test out JWT access token auth with Keycloak.
Enable the OpenID Connect plugin on the openid-connect service:
Next, apply the KongPlugin resource to an ingress by annotating the service as follows:
kubectl annotate service SERVICE_NAME konghq.com/plugins=openid-connect-example
Replace SERVICE_NAME with the name of the service that this plugin configuration will target.
You can see your available ingresses by running kubectl get service.
Note:
The KongPlugin resource only needs to be defined once
and can be applied to any service, consumer, or route in the namespace. If you
want the plugin to be available cluster-wide, create the resource as a
KongClusterPlugin instead of KongPlugin.
Add this section to your declarative configuration file:
You can also specify the bearer token as a query string parameter.
All parameters are the same as for the
bearer token in headers configuration,
except the client_credentials_param_type, which must be set to query:
Next, apply the KongPlugin resource to an ingress by annotating the service as follows:
kubectl annotate service SERVICE_NAME konghq.com/plugins=openid-connect-example
Replace SERVICE_NAME with the name of the service that this plugin configuration will target.
You can see your available ingresses by running kubectl get service.
Note:
The KongPlugin resource only needs to be defined once
and can be applied to any service, consumer, or route in the namespace. If you
want the plugin to be available cluster-wide, create the resource as a
KongClusterPlugin instead of KongPlugin.
Add this section to your declarative configuration file:
At this point you have created a service, routed traffic to the service, and
enabled the OpenID Connect plugin on the service. You can now test authentication with a JWT access token.
In this example, the password grant
lets you obtain a JWT access token, enabling you to test how JWT access token authentication works.
One way to get a JWT access token is to issue the following call
(we use jq to filter the response):
When you visit our website, we store cookies on your browser to collect information. The information collected might relate to you, your preferences or your device, and is mostly used to make the site work as you expect it to and to provide a more personalized web experience. However, you can choose not to allow certain types of cookies, which may impact your experience of the site and the services we are able to offer. Click on the different category headings to find out more and change our default settings according to your preference. You cannot opt-out of our First Party Strictly Necessary Cookies as they are deployed in order to ensure the proper functioning of our website (such as prompting the cookie banner and remembering your settings, to log into your account, to redirect you when you log out, etc.). For more information about the First and Third Party Cookies used please follow this link.