JWT access token authentication

JWT access token auth flow

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:

 
sequenceDiagram
    autonumber
    participant client as Client 
(e.g. mobile app)
    participant kong as API Gateway 
(Kong)
    participant httpbin as Upstream 
(backend service,
 e.g. httpbin)
    activate client
    activate kong
    client->>kong: service with
access token
    deactivate client
    kong->>kong: load access token
    kong->>kong: verify signature
    kong->>kong: verify claims
    activate httpbin
    kong->>httpbin: request with
access token
    httpbin->>kong: response
    deactivate httpbin
    activate client
    kong->>client: response
    deactivate kong
    deactivate client
  

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.

<socket-binding name="https" port="${jboss.https.port:8443}"/>

<socket-binding name="https" port="${jboss.https.port:8440}"/>

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:

curl -X POST http://localhost:8001/services/{serviceName|Id}/plugins \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
  "name": "openid-connect",
  "config": {
    "issuer": "http://keycloak.test:8080/auth/realms/master",
    "client_id": "kong",
    "client_auth": "private_key_jwt",
    "auth_methods": [
      "bearer",
      "password"
    ],
    "client_credentials_param_type": [
      "header"
    ]
  }
}
    '

curl -X POST \
https://{us|eu}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/services/{serviceId}/plugins \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer TOKEN" \
    --data '{"name":"openid-connect","config":{"issuer":"http://keycloak.test:8080/auth/realms/master","client_id":"kong","client_auth":"private_key_jwt","auth_methods":["bearer","password"],"client_credentials_param_type":["header"]}}'

echo "
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: openid-connect-example
plugin: openid-connect
config:
  issuer: http://keycloak.test:8080/auth/realms/master
  client_id: kong
  client_auth: private_key_jwt
  auth_methods:
  - bearer
  - password
  client_credentials_param_type:
  - header
" | kubectl apply -f -

kubectl annotate service SERVICE_NAME konghq.com/plugins=openid-connect-example

plugins:
- name: openid-connect
  service: SERVICE_NAME|ID
  config:
    issuer: http://keycloak.test:8080/auth/realms/master
    client_id: kong
    client_auth: private_key_jwt
    auth_methods:
    - bearer
    - password
    client_credentials_param_type:
    - header

terraform {
  required_providers {
    konnect = {
      source  = "kong/konnect"
    }
  }
}

provider "konnect" {
  personal_access_token = "kpat_YOUR_TOKEN"
  server_url            = "https://us.api.konghq.com/"
}

resource "konnect_gateway_plugin_openid_connect" "my_openid_connect" {
  enabled = true

  config = {
    issuer = "http://keycloak.test:8080/auth/realms/master"
    client_id = "kong"
    client_auth = "private_key_jwt"
    auth_methods = ["bearer", "password"]
    client_credentials_param_type = ["header"]
  }

  control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
  service = {
    id = konnect_gateway_service.my_service.id
  }
}

Bearer token in query string

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:

curl -X POST http://localhost:8001/services/{serviceName|Id}/plugins \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
  "name": "openid-connect",
  "config": {
    "issuer": "http://keycloak.test:8080/auth/realms/master",
    "client_id": "kong",
    "client_auth": "private_key_jwt",
    "auth_methods": [
      "bearer",
      "password"
    ],
    "client_credentials_param_type": [
      "query"
    ]
  }
}
    '

curl -X POST \
https://{us|eu}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/services/{serviceId}/plugins \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer TOKEN" \
    --data '{"name":"openid-connect","config":{"issuer":"http://keycloak.test:8080/auth/realms/master","client_id":"kong","client_auth":"private_key_jwt","auth_methods":["bearer","password"],"client_credentials_param_type":["query"]}}'

echo "
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: openid-connect-example
plugin: openid-connect
config:
  issuer: http://keycloak.test:8080/auth/realms/master
  client_id: kong
  client_auth: private_key_jwt
  auth_methods:
  - bearer
  - password
  client_credentials_param_type:
  - query
" | kubectl apply -f -

kubectl annotate service SERVICE_NAME konghq.com/plugins=openid-connect-example

plugins:
- name: openid-connect
  service: SERVICE_NAME|ID
  config:
    issuer: http://keycloak.test:8080/auth/realms/master
    client_id: kong
    client_auth: private_key_jwt
    auth_methods:
    - bearer
    - password
    client_credentials_param_type:
    - query

terraform {
  required_providers {
    konnect = {
      source  = "kong/konnect"
    }
  }
}

provider "konnect" {
  personal_access_token = "kpat_YOUR_TOKEN"
  server_url            = "https://us.api.konghq.com/"
}

resource "konnect_gateway_plugin_openid_connect" "my_openid_connect" {
  enabled = true

  config = {
    issuer = "http://keycloak.test:8080/auth/realms/master"
    client_id = "kong"
    client_auth = "private_key_jwt"
    auth_methods = ["bearer", "password"]
    client_credentials_param_type = ["query"]
  }

  control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
  service = {
    id = konnect_gateway_service.my_service.id
  }
}

Test the JWT access token authentication

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

curl --user john:doe http://localhost:8000/openid-connect \
    | jq -r .headers.Authorization

Output:

Bearer <access-token>

You can now use the token in the Authorization header or in a query.

Bearer token in header

Request the service with a bearer token:

curl -I http://localhost:8000/openid-connect \
    -H "Authorization: \
    \"$(curl --user john:doe http://localhost:8000/openid-connect \
    | jq -r .headers.Authorization)\""

or:

curl -I http://localhost:8000/openid-connect -H "Authorization: Bearer <access-token>"

Bearer token in query

Test out the token by accessing the Kong proxy:

curl http://localhost:8000?access_token=<token>

More information

JWT access token authentication is also compatible with certificate-bound access tokens.