Refresh token grant

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

Refresh token grant workflow

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 the password grant and the client credentials grant:

 
sequenceDiagram
    autonumber
    participant client as Client 
(e.g. mobile app)
    participant kong as API Gateway 
(Kong)
    participant idp as IDP 
(e.g. Keycloak)
    participant httpbin as Upstream 
(backend service,
 e.g. httpbin)
    activate client
    activate kong
    client->>kong: service with
refresh token
    deactivate client
    kong->>kong: load refresh token
    activate idp
    kong->>idp: keycloak/token with
client credentials and
refresh token
    deactivate kong
    idp->>idp: authenticate client and
verify refresh token
    activate kong
    idp->>kong: return tokens
    deactivate idp
    kong->>kong: verify tokens
    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 the refresh token grant

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 a refresh token grant.

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: you only need the refresh token grant for this flow. For the purposes of the demo, the example also enables the password grant.
• We want to only search headers for the refresh token.

With all of the above in mind, let’s test out the refresh token grant 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": [
      "refresh_token",
      "password"
    ],
    "refresh_token_param_type": [
      "header"
    ],
    "refresh_token_param_name": "refresh_token",
    "upstream_refresh_token_header": "refresh_token"
  }
}
    '

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":["refresh_token","password"],"refresh_token_param_type":["header"],"refresh_token_param_name":"refresh_token","upstream_refresh_token_header":"refresh_token"}}'

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:
  - refresh_token
  - password
  refresh_token_param_type:
  - header
  refresh_token_param_name: refresh_token
  upstream_refresh_token_header: refresh_token
" | 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:
    - refresh_token
    - password
    refresh_token_param_type:
    - header
    refresh_token_param_name: refresh_token
    upstream_refresh_token_header: refresh_token

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 = ["refresh_token", "password"]
    refresh_token_param_type = ["header"]
    refresh_token_param_name = "refresh_token"
    upstream_refresh_token_header = "refresh_token"
  }

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

Test the refresh token grant

Get a refresh token

In this example, the password grant and the upstream_refresh_token_header are enabled for demoing purposes. One way to get a refresh token is to issue the following call (we use jq to filter the response):

curl --user john:doe http://localhost:8000 | jq -r '.headers."Refresh-Token"'

You can use the output from the Refresh-Token header:

<refresh-token>

Access a service with the token

Request the service with a refresh token:

curl http://localhost:8000 \
 --header "Refresh-Token:$(curl --user john:doe http://localhost:8000 | \
 jq -r '.headers."Refresh-Token"')"

or

curl http://localhost:8000 \
 --header "Refresh-Token: <refresh-token>"

You should get an HTTP 200 response with a refresh token header:

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