Skip to content
|
Plugin Hub
github-edit-pageEdit this page
report-issueReport an issue
header icon

Headers

By Kong Inc.
You are browsing unreleased documentation.

The OpenID Connect plugin can pass claim values, tokens, JWKs, and the session identifier to the upstream service in request headers, and to the downstream client in response headers. By default, the plugin passes an access token in Authorization: Bearer <access-token> header to the upstream service (this can be controlled with config.upstream_access_token_header).

The claim values can be taken from:

  • An access token
  • An ID token
  • An introspection response
  • A user info response

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.

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



  2. 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:



  3. (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.

  4. (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.

  5. (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.

  6. Create a verified user with the name: john and the non-temporary password: doe that can be used 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 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

  1. Create a service:

     curl -i -X POST http://localhost:8001/services \
   --data "name=openid-connect" \
   --data "url=https://httpbin.konghq.com/anything"

  2. Create a route:

     curl -i -X POST http://localhost:8001/services/openid-connect/routes \
   --data "name=openid-connect" \
   --data "paths[]=/"

Pass metadata in headers

Let’s take a look for an access token payload:

{
   "exp": 1622556713,
   "aud": "account",
   "typ": "Bearer",
   "scope": "openid email profile",
   "preferred_username": "john",
   "given_name": "John",
   "family_name": "Doe"
}

To pass the preferred_username claim’s value john to the upstream with an Authenticated-User header, we need to patch our plugin:

http -f patch :8001/plugins/5f35b796-ced6-4c00-9b2a-90eef745f4f9 \
  config.auth_methods=password                                   \
  config.upstream_headers_claims=preferred_username              \
  config.upstream_headers_names=authenticated_user

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" ],
        "upstream_headers_claims": [ "preferred_username" ],
        "upstream_headers_names": [ "authenticated_user" ]
    }
}

Let’s see if it had any effect:

http -a john:doe :8000

HTTP/1.1 200 OK

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

See the configuration parameters for other options.