OpenID Connect (1.0) plugin allows the integration with a 3rd party identity provider (IdP) 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 and grants:

• Signed JWT access tokens (JWS)
• Opaque access tokens
• Refresh tokens
• Authorization code
• Username and password
• Client credentials
• Session cookies

The plugin has been tested with several OpenID Connect providers:

• Auth0 (Kong Integration Guide)
• Amazon AWS Cognito (Kong Integration Guide)
• Connect2id
• Curity
• Dex
• Gluu
• Google (Kong Integration Guide)
• IdentityServer
• Keycloak
• Microsoft Azure Active Directory (Kong Integration Guide)
• Microsoft Active Directory Federation Services
• Microsoft Live Connect
• Okta (Kong Integration Guide)
• OneLogin
• OpenAM
• Paypal
• PingFederate
• Salesforce
• WSO2
• Yahoo!

As long as your provider supports OpenID Connect standards, the plugin should work, even if it is not specifically tested against it. Let Kong 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.

This plugin can be used for authentication in conjunction with the Application Registration plugin.

Important Configuration Parameters

This plugin contains many configuration parameters that might seem overwhelming at the start. Here is a list of parameters that you should focus on first:

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

   Note: This does not have to match the URL of the iss claim in the access tokens being validated. To set URLs supported in the iss claim, use config.issuers_allowed.

2. Next, you should decide what authentication grants you want to use with this plugin, so configure: config.auth_methods.

   That parameter should contain only the grants that you want to use; otherwise, you inadvertently widen the attack surface.

3. In many cases, you also need to specify config.client_id, and if your identity provider requires authentication, such as on a token endpoint, you will need to specify the client authentication credentials too, for example config.client_secret.

4. If you are using a public identity provider, 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 identity provider uses a non-standard claim (other than aud as specified in JWT standard). This is because, for example Google, shares the public keys with different clients.

5. If you are using Kong in DB-less mode with the declarative configuration, you should set up config.session_secret if you are also using the session cookie authentication. Otherwise, each of your Nginx workers across all your nodes will encrypt and sign the cookies with their own secrets.

In summary, start with the following parameters:

1. config.issuer
2. config.auth_methods
3. config.client_id (and in many cases the client authentication credentials)
4. config.audience_required (if using a public identity provider)
5. config.session_secret (if using the Kong in DB-less mode)

Configuration Reference

This plugin is compatible with DB-less mode.

In DB-less mode, you configure Kong Gateway declaratively. Therefore, the Admin API is mostly read-only. The only tasks it can perform are all related to handling the declarative config, including:

• Setting a target’s health status in the load balancer
• Validating configurations against schemas
• Uploading the declarative configuration using the /config endpoint

Enable the plugin on a service

Admin API

Kubernetes

Declarative (YAML)

Konnect Cloud

Kong Manager

For example, configure this plugin on a service by making the following request:

curl -X POST http://{HOST}:8001/services/{SERVICE}/plugins \
    --data "name=openid-connect"  \
    --data "config.auth_methods=authorization_code" \
    --data "config.auth_methods=session" \
    --data "config.hide_credentials=true" \
    --data "config.issuer=<discovery-uri>" \
    --data "config.client_id=<client-id>" \
    --data "config.client_secret=<client-secret>" \
    --data "config.session_secret=<session-secret>" \
    --data "config.response_mode=form_post"

SERVICE is the id or name of the service that this plugin configuration will target.

First, create a KongPlugin resource:

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <openid-connect-example>
config: 
  auth_methods:
  - authorization_code
  - session
  hide_credentials: true
  issuer: <discovery-uri>
  client_id:
  - <client-id>
  client_secret:
  - <client-secret>
  session_secret: <session-secret>
  response_mode: form_post
plugin: openid-connect

Next, apply the KongPlugin resource to a Service by annotating the Service as follows:

apiVersion: v1
kind: Service
metadata:
  name: {SERVICE}
  labels:
    app: {SERVICE}
  annotations:
    konghq.com/plugins: <openid-connect-example>
spec:
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP
    name: {SERVICE}
  selector:
    app: {SERVICE}

{SERVICE} is the id or name of the service that this plugin configuration will target.

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.

For example, configure this plugin on a service by adding this section to your declarative configuration file:

plugins:
- name: openid-connect
  service: {SERVICE}
  config: 
    auth_methods:
    - authorization_code
    - session
    hide_credentials: true
    issuer: <discovery-uri>
    client_id:
    - <client-id>
    client_secret:
    - <client-secret>
    session_secret: <session-secret>
    response_mode: form_post

SERVICE is the id or name of the service that this plugin configuration will target.

Configure this plugin on a service:

1. In Konnect Cloud, select the service on the ServiceHub page.
2. Scroll down to Versions and select the version.
3. Scroll down to Plugins and click New Plugin.
4. Find and select the OpenID Connect plugin.

5. Enter the following parameters, updating the default or sample values as needed:

   • Config.Hide Credentials: true
   • Config.Issuer: <discovery-uri>
6. Click Create.

Configure this plugin on a service:

1. In Kong Manager, select the workspace.
2. From the Dashboard, scroll down to Services and click View for the service row.
3. Scroll down to plugins and click Add Plugin.

4. Find and select the OpenID Connect plugin.

   Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.

5. If the option is available, select Scoped.

6. Add the service name and ID to the Service field if it is not already prefilled.

7. Enter the following parameters, updating the default or sample values as needed:

   • Config.Hide Credentials: true
   • Config.Issuer: <discovery-uri>
8. Click Create.

Enable the plugin on a route

Admin API

Kubernetes

Declarative (YAML)

Konnect Cloud

Kong Manager

For example, configure this plugin on a route with:

$ curl -X POST http://{HOST}:8001/routes/{ROUTE}/plugins \
    --data "name=openid-connect"  \
    --data "config.auth_methods=authorization_code" \
    --data "config.auth_methods=session" \
    --data "config.hide_credentials=true" \
    --data "config.issuer=<discovery-uri>" \
    --data "config.client_id=<client-id>" \
    --data "config.client_secret=<client-secret>" \
    --data "config.session_secret=<session-secret>" \
    --data "config.response_mode=form_post"

ROUTE is the id or name of the route that this plugin configuration will target.

First, create a KongPlugin resource:

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <openid-connect-example>
config: 
  auth_methods:
  - authorization_code
  - session
  hide_credentials: true
  issuer: <discovery-uri>
  client_id:
  - <client-id>
  client_secret:
  - <client-secret>
  session_secret: <session-secret>
  response_mode: form_post
plugin: openid-connect

Then, apply it to an ingress (Route or Routes) by annotating the ingress as follows:

apiVersion: networking/v1beta1
kind: Ingress
metadata:
  name: {ROUTE}
  annotations:
    kubernetes.io/ingress.class: kong
    konghq.com/plugins: <openid-connect-example>
spec:
  rules:
  - host: examplehostname.com
    http:
      paths:
      - path: /bar
        backend:
          serviceName: echo
          servicePort: 80

ROUTE is the id or name of the route that this plugin configuration will target.

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.

For example, configure this plugin on a route by adding this section to your declarative configuration file:

plugins:
- name: openid-connect
  route: <route>
  config: 
    auth_methods:
    - authorization_code
    - session
    hide_credentials: true
    issuer: <discovery-uri>
    client_id:
    - <client-id>
    client_secret:
    - <client-secret>
    session_secret: <session-secret>
    response_mode: form_post

ROUTE is the id or name of the route that this plugin configuration will target.

Configure this plugin on a route:

1. In Konnect Cloud, select the service from the ServiceHub page.
2. Scroll down to Versions and select the version.
3. Select the route.
4. Scroll down to Plugins and click Add Plugin.
5. Find and select the OpenID Connect plugin.

6. Enter the following parameters, updating the default or sample values as needed:

   • Config.Hide Credentials: true
   • Config.Issuer: <discovery-uri>
7. Click Create.

Configure this plugin on a route:

1. In Kong Manager, select the workspace.
2. From the Dashboard, select Routes in the left navigation.
3. Click View for the route row.
4. Scroll down to plugins and click Add Plugin.

5. Find and select the OpenID Connect plugin.

   Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.

6. If the option is available, select Scoped.

7. Add the Route ID if it is not already prefilled.

8. Enter the following parameters, updating the default or sample values as needed:

   • Config.Hide Credentials: true
   • Config.Issuer: <discovery-uri>
9. Click Create.

Enable the plugin globally

A plugin which is not associated to any service, route, or consumer is considered global, and will be run on every request. Read the Plugin Reference and the Plugin Precedence sections for more information.

Admin API

Kubernetes

Declarative (YAML)

Kong Manager

For example, configure this plugin globally with:

$ curl -X POST http://{HOST}:8001/plugins/ \
    --data "name=openid-connect"  \
    --data "config.auth_methods=authorization_code" \
    --data "config.auth_methods=session" \
    --data "config.hide_credentials=true" \
    --data "config.issuer=<discovery-uri>" \
    --data "config.client_id=<client-id>" \
    --data "config.client_secret=<client-secret>" \
    --data "config.session_secret=<session-secret>" \
    --data "config.response_mode=form_post"

Create a KongClusterPlugin resource and label it as global:

apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
  name: <global-openid-connect>
  annotations:
    kubernetes.io/ingress.class: kong
  labels:
    global: \"true\"
config: 
  auth_methods:
  - authorization_code
  - session
  hide_credentials: true
  issuer: <discovery-uri>
  client_id:
  - <client-id>
  client_secret:
  - <client-secret>
  session_secret: <session-secret>
  response_mode: form_post
plugin: openid-connect

For example, configure this plugin using the plugins: entry in the declarative configuration file:

plugins:
- name: openid-connect
  config: 
    auth_methods:
    - authorization_code
    - session
    hide_credentials: true
    issuer: <discovery-uri>
    client_id:
    - <client-id>
    client_secret:
    - <client-secret>
    session_secret: <session-secret>
    response_mode: form_post

Configure this plugin globally:

1. In Kong Manager, select the workspace.
2. From the Dashboard, select Plugins in the left navigation.
3. Click New Plugin.

4. Find and select the OpenID Connect plugin.

   Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.

5. If the option is available, set the plugin scope to Global.

6. Enter the following parameters, updating the default/sample values as needed:

   • Config.Hide Credentials: true
   • Config.Issuer: <discovery-uri>
7. Click Create.

Parameters

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

Records

In the above parameter list, two configuration settings used an array of records as a data type:

• config.client_jwk: array of JWK records (one for each client)
• config.session_redis_cluster_nodes: array of host records, either as IP addresses or hostnames, and their ports.

Below are descriptions of the record types.

JWK Record

The JSON Web Key (JWK) record is specified in RFC7571. This record is used with the config.client_jwk when using private_key_jwk client authentication.

Here is an example of JWK record generated by the plugin itself (see: JSON Web Key Set:

{
    "kid": "B2FxBJ8G_e61tnZEfaYpaMLjswjNO3dbVEQhR7-i_9s",
    "kty": "RSA",
    "alg": "RS256",
    "use": "sig"
    "e": "AQAB",
    "n": "…",
    "d": "…",
    "p": "…",
    "q": "…",
    "dp": "…",
    "dq": "…",
    "qi": "…"
}

Host Record

The Host record used with the config.session_redis_cluster_nodes is simple. It contains ip or host, and the port where the port defaults to 6379.

Here is an example of Host the record:

{
    "ip": "127.0.0.1"
    "port": 6379
}

Admin API

The OpenID Connect plugin extends the Kong Admin API with a few endpoints.

Discovery Cache

When configuring the plugin using config.issuer, the plugin will store the fetched discovery information to the Kong database, or in the worker memory with Db-less.

Discovery Cache Object

{
    "id": "<uuid>",
    "issuer": "<config.issuer>"
    "created_at": <timestamp>,
    "configuration": {
        <discovery>
    },
    "keys": [
        <keys>
    ]
}

List All Discovery Cache Objects

/openid-connect/issuers

Response

HTTP 200 OK

{
    "data": [{
        "id": "<uuid>",
        "issuer": "<config.issuer>"
        "created_at": <timestamp>,
        "configuration": {
            <discovery>
        },
        "keys": [
            <keys>
        ]
    }],
    "next": null
}

Retrieve Discovery Cache Object

/openid-connect/issuers/{issuer or id}

Response

HTTP 200 OK

{
    "id": "<uuid>",
    "issuer": "<config.issuer>"
    "created_at": <timestamp>,
    "configuration": {
        <discovery>
    },
    "keys": [
        <keys>
    ]
}

Delete All Discovery Cache Objects

/openid-connect/issuers

Response

HTTP 204 No Content

Note: The automatically generated session secret (that can be overridden with the config.session_secret) is stored with the discovery cache objects. Deleting discovery cache objects will invalidate all the sessions created with the associated secret.

Delete Discovery Cache Object

/openid-connect/issuers/{issuer or id}

Response

HTTP 204 No Content

JSON Web Key Set

When the OpenID Connect client (the plugin) is set to communicate with the identity provider endpoints using private_key_jwt, the plugin needs to use public key cryptography. Thus, the plugin needs to generate the needed keys. Identity provider on the other hand has to verify that the assertions used for the client authentication.

The plugin will automatically generate the key pairs for the different algorithms. It will also publish the public keys with the admin api where the identity provider could fetch them.

{
    "keys": [{
        <keys>
    }]
}

Retrieve JWKS

/openid-connect/jwks

This endpoint will return a standard JWK Set document with the private keys stripped out.

Response

HTTP 200 OK

{
    "keys": [{
        <keys>
    }]
}

Rotate JWKS

/openid-connect/jwks

Deleting JWKS will also cause auto-generation of a new JWK set, so DELETE will actually cause a key rotation.

Response

HTTP 204 No Content

Preparations

The OpenID Connect plugin relies in most cases on a 3rd party identity provider. In this section, we explain configuration of Keycloak and Kong.

All the *.test domains in the following examples point to the localhost (127.0.0.1 and/or ::1).

Keycloak Configuration

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, please refer to the Keycloak documentation.

1. Create a confidential client kong with private_key_jwt authentication and point the Keycloak to download the public keys from the OpenID Connect Plugin JWKS endpoint:

   
   

2. Create another confidential client service with client_secret_basic authentication, and the secret of cf4c655a-0622-4ce6-a0de-d3353ef0b714 (Keycloak auto-generates one), and enable the client credentials grant for the client:

   
   

3. Create verified user john with the non-temporary password doe that we can use with the password grant:

   

Alternatively you can download the exported Keycloak configuration, and use it to configure the Keycloak. Please refer to Keycloak import documentation for more information.

You need to modify Keycloak standalone.xml configuration file, and change the socket binding from:

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

to

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

The Keycloak default https port conflicts with the default Kong TLS proxy port, and that can be a problem if both are started on a single host.

Kong Configuration

Create a Service

http -f put :8001/services/openid-connect url=http://httpbin.org/anything

HTTP/1.1 200 OK

{
    "id": "5fa9e468-0007-4d7e-9aeb-49ca9edd6ccd",
    "name": "openid-connect",
    "protocol": "http",
    "host": "httpbin.org",
    "port": 80,
    "path": "/anything"
}

Create a Route

http -f put :8001/services/openid-connect/routes/openid-connect paths=/

HTTP/1.1 200 OK

{
    "id": "ac1e86bd-4bce-4544-9b30-746667aaa74a",
    "name": "openid-connect",
    "paths": [ "/" ]
}

Create a Plugin

You may execute this before patching the plugin (as seen on following examples) to reset the plugin configuration.

http -f put :8001/plugins/5f35b796-ced6-4c00-9b2a-90eef745f4f9 \
  name=openid-connect                                          \
  service.name=openid-connect                                  \
  config.issuer=http://keycloak.test:8080/auth/realms/master   \
  config.client_id=kong                                        \
  config.client_auth=private_key_jwt

HTTP/1.1 200 OK

{
    "id": "5f35b796-ced6-4c00-9b2a-90eef745f4f9",
    "name": "openid-connect",
    "service": {
        "id": "5fa9e468-0007-4d7e-9aeb-49ca9edd6ccd"
    },
    "config": {
        "issuer": "http://keycloak.test:8080/auth/realms/master",
        "client_id": [ "kong" ],
        "client_auth": [ "private_key_jwt" ]
    }
}

Also, check the discovery cache: http :8001/openid-connect/issuers. It should contain Keycloak OpenID Connect discovery document, and the keys.

Summary

At this point we have:

1. Created a Service
2. Routed traffic to the service
3. Enabled OpenID Connect plugin on the service

Follow up on next sections to enable OpenID Connect plugin for specific grants or flows.

Authentication

Before you proceed, check that you have done the preparations.

We use HTTPie to execute the examples. The output is stripped for a better readability. httpbin.org is used as an upstream service.

Using Admin API is convenient when testing the plugin, but similar configs can be done in declarative format as well.

When plugin is configured with multiple grants / flows there is a hard-coded search order for the credentials:

1. Session Authentication
2. JWT Access Token Authentication
3. Kong OAuth Token Authentication
4. Introspection Authentication
5. User Info Authentication
6. Refresh Token Grant
7. Password Grant
8. Client Credentials Grant
9. Authorization Code Flow

In case plugin finds credentials, it will stop searching other credentials. Some grants may use the same credentials, in other words, both password and client credentials grants can use credentials from basic authentication header.

Because the httpbin.org is used as an upstream service, it is highly recommend that you do not run these usage examples with a production identity provider as there is great a chance of leaking information. Also the examples below use the plain HTTP protocol that you should never use in production. The choices here are for simplicity.

Authorization Code Flow

The authorization code flow is the three-legged OAuth/OpenID Connect flow. The sequence diagram below, describes the participants, and their interactions for this usage scenario, including the use of session cookies:

Patch the Plugin

Let’s patch the plugin that we created in the Kong configuration step:

1. We want to only use the authorization code flow and the session authentication.
2. We want to set the response mode to form_post so that authorization codes won’t get logged to the access logs.
3. We want to preserve the original request query arguments over the authorization code flow redirections.
4. We want to redirect the client to original request url after the authorization code flow so that the POST request (because of form_post) is turned to the GET request, and the browser address bar is updated with the original request query arguments.
5. We don’t want to include any tokens in the browser address bar.

Reset the plugin configuration before patching.

http -f patch :8001/plugins/5f35b796-ced6-4c00-9b2a-90eef745f4f9 \
  config.auth_methods=authorization_code                         \
  config.auth_methods=session                                    \
  config.response_mode=form_post                                 \
  config.preserve_query_args=true                                \
  config.login_action=redirect                                   \
  config.login_tokens=

HTTP/1.1 200 OK

{
    "id": "5f35b796-ced6-4c00-9b2a-90eef745f4f9",
    "name": "openid-connect",
    "service": {
        "id": "5fa9e468-0007-4d7e-9aeb-49ca9edd6ccd"
    },
    "config": {
        "auth_methods": [
            "authorization_code",
            "session"
        ],
        "login_action": "redirect",
        "preserve_query_args": true,
        "login_tokens": null
    }
}

Test the Authorization Code Flow

1. Open the Service Page with some query arguments:

   open http://service.test:8000/?hello=world

   

2. See that the browser is redirected to the Keycloak login page:

   

   You may examine the query arguments passed to Keycloak with the browser developer tools.

3. And finally you will be presented a response from httpbin.org:

   

4. Done.

It looks rather simple from the user point of view, but what really happened is described in the diagram above.

Password Grant

Password grant is a legacy authentication grant. The password grant is a less secure way to authenticate the end users than the authorization code flow. For example, the passwords get shared with 3rd parties. The grant is rather simple though:

Patch the Plugin

Let’s patch the plugin that we created in the Kong configuration step:

1. We want to only use the password grant.
2. We want to search credentials for password grant from the headers only.

Reset the plugin configuration before patching.

http -f patch :8001/plugins/5f35b796-ced6-4c00-9b2a-90eef745f4f9 \
  config.auth_methods=password                                   \
  config.password_param_type=header

HTTP/1.1 200 OK

{
    "id": "5f35b796-ced6-4c00-9b2a-90eef745f4f9",
    "name": "openid-connect",
    "service": {
        "id": "5fa9e468-0007-4d7e-9aeb-49ca9edd6ccd"
    },
    "config": {
        "auth_methods": [ "password" ],
        "password_param_type": [ "header" ]
    }
}

Test the Password Grant

1. Request the service with basic authentication credentials created in the Keycloak configuration step:

   http -v -a john:doe :8000

   GET / HTTP/1.1
   Authorization: Basic BEkg3bHT0ERXFmKr1qelBQYrLBeHb5Hr

   HTTP/1.1 200 OK

   {
       "headers": {
           "Authorization": "Bearer <access-token>"
       },
       "method": "GET"
   }

2. Done.

If you make another request using the same credentials, you should see that Kong adds less latency to the request as it has cached the token endpoint call to Keycloak.

Client Credentials Grant

Client credentials grant is almost the same as the password grant, but the biggest difference with the Kong OpenID Connect plugin is that the plugin itself does not try to authenticate. It just forwards the credentials passed by the client to the identity server’s token endpoint. The client credentials grant is visualized below:

Patch the Plugin

Let’s patch the plugin that we created in the Kong configuration step:

1. We want to only use the client credentials grant.
2. We want to search credentials for client credentials from the headers only.

Reset the plugin configuration before patching.

http -f patch :8001/plugins/5f35b796-ced6-4c00-9b2a-90eef745f4f9 \
  config.auth_methods=client_credentials                         \
  config.client_credentials_param_type=header

HTTP/1.1 200 OK

{
    "id": "5f35b796-ced6-4c00-9b2a-90eef745f4f9",
    "name": "openid-connect",
    "service": {
        "id": "5fa9e468-0007-4d7e-9aeb-49ca9edd6ccd"
    },
    "config": {
        "auth_methods": [ "client_credentials" ],
        "client_credentials_param_type": [ "header" ]
    }
}

Test the Client Credentials Grant

1. Request the service with client credentials created in the Keycloak configuration step:

   http -v -a service:cf4c655a-0622-4ce6-a0de-d3353ef0b714 :8000

   GET / HTTP/1.1
   Authorization: Basic c2VydmljZTpjZjRjNjU1YS0wNjIyLTRjZTYtYTBkZS1kMzM1M2VmMGI3MTQ=

   HTTP/1.1 200 OK

   {
       "headers": {
           "Authorization": "Bearer <access-token>"
       },
       "method": "GET"
   }

2. Done.

If you make another request using the same credentials, you should see that Kong adds less latency to the request as it has cached the token endpoint call to Keycloak.

Refresh Token Grant

The refresh token grant can be used when the client has a refresh token available. There is a caveat with this: identity providers in general only allow refresh token grant to be executed with the same client that originally got the refresh token, and if there is a mismatch, it may not work. The mismatch is likely when Kong OpenID Connect is configured to use one client, and the refresh token is retrieved with another. The grant itself is very similar to password grant and client credentials grant:

Patch the Plugin

Let’s patch the plugin that we created in the Kong configuration step:

1. We want to only use the refresh token grant, but we also enable the password grant for demoing purposes
2. We want to search the refresh token for the refresh token grant from the headers only.
3. We want to pass refresh token from the client in Refresh-Token header.
4. We want to pass refresh token to upstream in Refresh-Token header.

Reset the plugin configuration before patching.

http -f patch :8001/plugins/5f35b796-ced6-4c00-9b2a-90eef745f4f9 \
  config.refresh_token_param_name=refresh_token                  \
  config.refresh_token_param_type=header                         \
  config.auth_methods=refresh_token                              \
  config.auth_methods=password                                   \
  config.upstream_refresh_token_header=refresh_token

HTTP/1.1 200 OK

{
    "id": "5f35b796-ced6-4c00-9b2a-90eef745f4f9",
    "name": "openid-connect",
    "service": {
        "id": "5fa9e468-0007-4d7e-9aeb-49ca9edd6ccd"
    },
    "config": {
        "auth_methods": [
            "refresh_token",
            "password"
        ],
        "refresh_token_param_name": "refresh_token",
        "refresh_token_param_type": [ "header" ],
        "upstream_refresh_token_header": "refresh_token"
    }
}

The config.auth_methods and config.upstream_refresh_token_header are only enabled for demoing purposes so that we can get a refresh token with:

http -a john:doe :8000 | jq -r '.headers."Refresh-Token"'

Output:

<refresh-token>

We can use the output in Refresh-Token header.

Test the Refresh Token Grant

1. Request the service with a bearer token:

   http -v :8000 Refresh-Token:$(http -a john:doe :8000 | \
     jq -r '.headers."Refresh-Token"')

   or

   http -v :8000 Refresh-Token:"<refresh-token>"

   GET / HTTP/1.1
   Refresh-Token: <refresh-token>

   HTTP/1.1 200 OK

   {
       "headers": {
           "Authorization": "Bearer <access-token>",
           "Refresh-Token": "<refresh-token>"
       },
       "method": "GET"
   }

2. Done.

JWT Access Token Authentication

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:

Patch the Plugin

Let’s patch the plugin that we created in the Kong configuration step:

1. We want to only use the bearer authentication, but we also enable the password grant for demoing purposes
2. We want to search the bearer token for the bearer authentication from the headers only.

Reset the plugin configuration before patching.

http -f patch :8001/plugins/5f35b796-ced6-4c00-9b2a-90eef745f4f9 \
  config.bearer_token_param_type=header                          \
  config.auth_methods=bearer                                     \
  config.auth_methods=password # only enabled for demoing purposes

HTTP/1.1 200 OK

{
    "id": "5f35b796-ced6-4c00-9b2a-90eef745f4f9",
    "name": "openid-connect",
    "service": {
        "id": "5fa9e468-0007-4d7e-9aeb-49ca9edd6ccd"
    },
    "config": {
        "auth_methods": [
            "bearer",
            "password"
        ],
        "bearer_token_param_type": [ "header" ]
    }
}

The password grant is enabled so that we can get a JWT access token that we can use to show how the JWT access token authentication works. That is: we need a token. One way to get a JWT access token is to issue the following call (we use jq to filter the response):

http -a john:doe :8000 | jq -r .headers.Authorization

Output:

Bearer <access-token>

We can use the output in Authorization header.

Test the JWT Access Token Authentication

1. Request the service with a bearer token:

   http -v :8000 Authorization:"$(http -a john:doe :8000 | \
     jq -r .headers.Authorization)"

   or

   http -v :8000 Authorization:"Bearer <access-token>"

   GET / HTTP/1.1
   Authorization: Bearer <access-token>

   HTTP/1.1 200 OK

   {
       "headers": {
           "Authorization": "Bearer <access-token>"
       },
       "method": "GET"
   }

2. Done.

Introspection Authentication

As with JWT Access Token Authentication), the introspection authentication relies on a bearer token that the client has already gotten from somewhere. The difference to stateless JWT authentication is that the plugin needs to call the introspection endpoint of the identity provider to find out whether the token is valid and active. This makes it possible to issue opaque tokens to the clients.

Patch the Plugin

Let’s patch the plugin that we created in the Kong configuration step:

1. We want to only use the introspection authentication, but we also enable the password grant for demoing purposes
2. We want to search the bearer token for the introspection from the headers only.

Reset the plugin configuration before patching.

http -f patch :8001/plugins/5f35b796-ced6-4c00-9b2a-90eef745f4f9 \
  config.bearer_token_param_type=header                          \
  config.auth_methods=introspection                              \
  config.auth_methods=password # only enabled for demoing purposes

HTTP/1.1 200 OK

{
    "id": "5f35b796-ced6-4c00-9b2a-90eef745f4f9",
    "name": "openid-connect",
    "service": {
        "id": "5fa9e468-0007-4d7e-9aeb-49ca9edd6ccd"
    },
    "config": {
        "auth_methods": [
            "introspection",
            "password"
        ],
        "bearer_token_param_type": [ "header" ]
    }
}

Test the Introspection Authentication

1. Request the service with a bearer token:

   http -v :8000 Authorization:"$(http -a john:doe :8000 | \
     jq -r .headers.Authorization)"

   or

   http -v :8000 Authorization:"Bearer <access-token>"

   GET / HTTP/1.1
   Authorization: Bearer <access-token>

   HTTP/1.1 200 OK

   {
       "headers": {
           "Authorization": "Bearer <access-token>"
       },
       "method": "GET"
   }

2. Done.

User Info Authentication

The user info authentication uses OpenID Connect standard user info endpoint to verify the access token. In most cases it is preferable to use Introspection Authentication as that is meant for retrieving information from the token itself, whereas the user info endpoint is meant for retrieving information about the user for whom the token was given. The sequence diagram below looks almost identical to introspection authentication:

Patch the Plugin

Let’s patch the plugin that we created in the Kong configuration step:

1. We want to only use the user info authentication, but we also enable the password grant for demoing purposes
2. We want to search the bearer token for the user info from the headers only.

Reset the plugin configuration before patching.

http -f patch :8001/plugins/5f35b796-ced6-4c00-9b2a-90eef745f4f9 \
  config.bearer_token_param_type=header                          \
  config.auth_methods=userinfo                                   \
  config.auth_methods=password # only enabled for demoing purposes

HTTP/1.1 200 OK

{
    "id": "5f35b796-ced6-4c00-9b2a-90eef745f4f9",
    "name": "openid-connect",
    "service": {
        "id": "5fa9e468-0007-4d7e-9aeb-49ca9edd6ccd"
    },
    "config": {
        "auth_methods": [
            "userinfo",
            "password"
        ],
        "bearer_token_param_type": [ "header" ]
    }
}