Certificate-Bound Access Tokens

You are browsing unreleased documentation.

Overview

One of the main vulnerabilities of OAuth are bearer tokens. With OAuth, presenting a valid bearer token is enough proof to access a resource. This can create problems since the client presenting the token isn’t validated as the legitimate user that the token was issued to.

For an alternative solution, please refer to: Demonstrating Proof-of-Possession.

Certificate-bound access tokens can solve this problem by binding tokens to clients. This ensures the legitimacy of the token because the it requires proof that the sender is authorized to use a particular token to access protected resources.

To enable certificate-bound access for OpenID Connect, you must ensure that the auth server is set up to generate OAuth 2.0 Mutual TLS certificate-bound access tokens.

If you are configuring this in Keycloak, see the Keycloak configuration section in the prerequisites. For alternative auth servers, consult their documentation to configure this functionality.

Some of the instructions in the other how-to guides for OpenID Connect support validation of access tokens using mTLS proof of possession. Enabling the proof_of_possession_mtls configuration option in the plugin helps to ensure that the supplied access token belongs to the client by verifying its binding with the client certificate provided in the request.

The certificate-bound access tokens are supported by the following auth methods:

• JWT Access Token Authentication
• Introspection Authentication

• Session Authentication

  Session Authentication is only compatible with certificate-bound access tokens when used along with one of the other supported authentication methods:

  • When the configuration option proof_of_possession_auth_methods_validation is set to false and other non-compatible methods are enabled, if a valid session is found, the proof of possession validation will only be performed if the session was originally created using one of the compatible methods.
  • If multiple openid-connect plugins are configured with the session auth method, we strongly recommend configuring different values of session_secret across plugin instances for additional security. This avoids sessions being shared across plugins and possibly bypassing the proof of possession validation.

The following example shows how to enable this feature for the JWT Access Token Authentication method. Similar steps can be followed for the other methods.

Demo

Prerequisites

Follow these prerequisites to set up a demo Keycloak app and a Kong service and route for testing mTLS client auth.

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}"/>

Configure certificate-bound access tokens

1. Configure Kong Gateway to use mTLS client certificate authentication. You can do this by configuring the TLS Handshake Modifier plugin or the Mutual TLS Authentication plugin:

    curl -X POST http://localhost:8001/plugins \
      --data "name=tls-handshake-modifier" \
      --data "service.name=openid-connect"
   

   If this is configured correctly, it returns a 200 response with the following data:

    {
        "id": "a7f676e6-580d-4841-80de-de46e1f79eb2",
        "name": "tls-handshake-modifier",
        "service": {
            "id": "5fa9e468-0007-4d7e-9aeb-49ca9edd6ccd"
        }
    }
   

2. To enable certificate-bound access tokens, use the proof_of_possession_mtls configuration option:

    curl -X PUT http://localhost:8001/plugins/5f35b796-ced6-4c00-9b2a-90eef745f4f9 \
      --data "name=openid-connect" \
      --data "service.name=openid-connect" \
      --data "config.issuer=https://keycloak.test:8440/auth/realms/master" \
      --data "config.client_id=cert-bound" \
      --data "config.client_secret=cf4c655a-0622-4ce6-a0de-d3353ef0b714" \
      --data "config.auth_methods=bearer" \
      --data "config.proof_of_possession_mtls=strict" 
   

   If this is configured correctly, it returns a 200 response with the following data:

    {
        "id": "5f35b796-ced6-4c00-9b2a-90eef745f4f9",
        "name": "openid-connect",
        "service": {
            "id": "5fa9e468-0007-4d7e-9aeb-49ca9edd6ccd"
        },
        "config": {
            "issuer": "https://keycloak.test:8440/auth/realms/master",
            "client_id": [ "cert-bound" ],
            "client_secret": [ "cf4c655a-0622-4ce6-a0de-d3353ef0b714" ],
            "auth_methods": [ "bearer" ],
            "proof_of_possession_mtls": "strict",
        }
    }
   

3. Obtain the token from the IdP, making sure to modify the following command for your environment:

     curl -f -X POST https://keycloak.test:8440/auth/realms/master/protocol/openid-connect/token \
       --cert client-cert.pem \
       --cert-key client-key.pem \
       --data "client_id=cert-bound" \
       --data "client_secret=cf4c655a-0622-4ce6-a0de-d3353ef0b714" \
       --data "grant_type=client_credentials" \
   

   If this is configured correctly, it returns a 200 response with the following data:

    {
        "access_token": "eyJhbG...",
    }
   

   The token you obtain should include a claim that consists of the hash of the client certificate:

    {
        "exp": 1622556713,
        "typ": "Bearer",
        "cnf": {
            "x5t#S256": "hh_XBS..."
        }
    }
   

4. Access the service using the same client certificate and key used to obtain the token:

    curl -f -X POST https://kong.test:8443 \
      -H "Authorization: Bearer eyJhbGc..." \
      --cert client-cert.pem \
      --cert-key client-key.pem \
   

   If this is configured correctly, it returns a 200 response:

    HTTP/1.1 200 OK