Demonstrating Proof-of-Possession

このページは、まだ日本語ではご利用いただけません。翻訳中です。

古いプラグインバージョンのドキュメントを閲覧しています。

Overview

Demonstrating Proof-of-Possession (DPoP) is an alternative technique to the Mutual TLS certificate-bound access tokens. Unlike its alternative, which binds the token to the mTLS client certificate, it binds the token to a JSON Web Key (JWK) provided by the client.

 
sequenceDiagram
    autonumber
    participant client as Client 
(e.g. mobile app)
    participant kong as API Gateway 
(Kong)
    participant upstream as Upstream 
(backend service,
 e.g. httpbin)
    participant idp as Authentication Server 
(e.g. Keycloak)
    activate client
    client->>client: generate key pair
    client->>idp: POST /oauth2/token
DPoP:$PROOF
    deactivate client
    activate idp
    idp-->>client: DPoP bound access token ($AT)
    activate client
    deactivate idp
    client->>kong: GET https://example.com/resource
Authorization: DPoP $AT
DPoP: $PROOF
    activate kong
    deactivate client
    kong->>kong: validate $AT and $PROOF
    kong->>upstream: proxied request 
 GET https://example.com/resource
Authorization: Berear $AT
    deactivate kong
    activate upstream
    upstream-->>kong: upstream response
    deactivate upstream
    activate kong
    kong-->>client: response
    deactivate kong
  

You can use the Demonstrating Proof-of-Possession option without Mutual TLS, and even with plain HTTP, although HTTPS is recommended for enhanced security.

When verification of the DPoP proof is enabled, Kong removes the DPoP header and changes the token type from dpop to bearer. This effectively downgrades the request to use a conventional bearer token. This allows an OAuth2 upstream without DPoP support to work with the DPoP token without losing the protection of the key-binding mechanism.

It’s a prerequisite that the auth server is configured to enable the DPoP for you to enable it with Kong.

If you are setting up Demonstrating Proof-of-Possession in Keycloak, refer to the Keycloak configuration section in the prerequisites. For other authentication servers, please consult their specific documentation to configure this functionality.

Many instructions in the other how-to guides for OpenID Connect support validation of access tokens using Demonstrating Proof-of-Possession. Enabling the proof_of_possession_dpop configuration option in the plugin helps to ensure that the supplied access token is bound to the client by verifying its association with the JWT provided in the request.

DPoP is compatible with the following authentication methods:

• JWT Access Token Authentication
• Introspection Authentication

• Session Authentication

  Session Authentication is only compatible with DPoP when used along with one of the other supported authentication methods:

  • If multiple openid-connect plugins are configured with the session authentication 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}"/>

Set up Demonstrating Proof-of-Possession with the OIDC plugin

To enable Demonstrating Proof-of-Possession, use the proof_of_possession_dpop configuration option, and set the service name to openid-connect to follow the demo:

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:8440/auth/realms/master",
    "client_id": "cert_bound",
    "client_secret": "cf4c655a-0622-4ce6-a0de-d3353ef0b714",
    "auth_methods": [
      "bearer"
    ],
    "proof_of_possession_dpop": "strict"
  }
}
    '

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:8440/auth/realms/master","client_id":"cert_bound","client_secret":"cf4c655a-0622-4ce6-a0de-d3353ef0b714","auth_methods":["bearer"],"proof_of_possession_dpop":"strict"}}'

echo "
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: openid-connect-example
plugin: openid-connect
config:
  issuer: http://keycloak.test:8440/auth/realms/master
  client_id: cert_bound
  client_secret: cf4c655a-0622-4ce6-a0de-d3353ef0b714
  auth_methods:
  - bearer
  proof_of_possession_dpop: strict
" | 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:8440/auth/realms/master
    client_id: cert_bound
    client_secret: cf4c655a-0622-4ce6-a0de-d3353ef0b714
    auth_methods:
    - bearer
    proof_of_possession_dpop: strict

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:8440/auth/realms/master"
    client_id = "cert_bound"
    client_secret = "cf4c655a-0622-4ce6-a0de-d3353ef0b714"
    auth_methods = ["bearer"]
    proof_of_possession_dpop = "strict"
  }

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

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

{
    "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_dpop": "strict",
    }
}

Test Demonstrating Proof-of-Possession

Obtain the token from the IdP. A DPoP supporting client is required. For this demo, here is an example using oauth2c:

oauth2c https://keycloak.test:8440/realms/master/.well-known/openid-configuration \
--client-id cert-bound --client-secret cf4c655a-0622-4ce6-a0de-d3353ef0b714       \
--grant-type client_credentials --scopes openid --dpop                            \
--signing-key https://path/to/the_jwks.json

If this is configured correctly, it returns a 200 response and something like the following:

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

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

{
    "exp": 1622556713,
    "typ": "Bearer",
    "cnf": {
        "jkt": "hh_XBS..."
    }
}

Use the same client key to obtain both the token and sign the request to access the resource. The client should generate proper proof for possession of the key and send it via the DPoP header, which will be verified by Kong together with the token.