Kong OAuth token authentication

You are browsing unreleased documentation.

Kong OAuth token auth flow

The OpenID Connect plugin can also verify the tokens issued by Kong OAuth 2.0 Plugin. This is very similar to third party identity provider issued JWT access token authentication or introspection authentication:

 
sequenceDiagram
    autonumber
    participant client as Client 
(e.g. mobile app)
    participant kong as API Gateway 
(Kong)
    participant httpbin as Upstream 
(backend service,
 e.g. httpbin)
    activate client
    activate kong
    client->>kong: service with
access token
    deactivate client
    kong->>kong: load access token
    kong->>kong: verify kong
oauth token
    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}"/>

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.

Prepare Kong OAuth application

1. Create a consumer:

   curl -i -X PUT http://localhost:8001/consumers/jane
   

2. Create a Kong Gateway OAuth application for the consumer:

   curl -i -X PUT http://localhost:8001/consumers/jane/oauth2/client \
     --data "name=demo" \
     --data "client_secret=secret" \
     --data "hash_secret=true"
   

3. Create a route:

   curl -i -X PUT http://localhost:8001/routes/mock \
     --data "paths=/mock"
   

4. Apply the OAuth plugin to the route:

   curl -i -X POST http://localhost:8001/routes/mock/plugins \
     --data "name=oauth2" \
     --data "config.global_credentials=true" \
     --data "config.enable_client_credentials=true"
   

5. Test the token endpoint:

   curl -i -X POST --insecure https://localhost:8443/mock/oauth2/token \
    --data "client_id=client" \
    --data "client_secret=secret" \
    --data "grant_type=client_credentials"
   

   You should get an HTTP 200 response with the token in the access_token field:

   {
       "access_token": "<access-token>",
       "expires_in": 7200,
       "token_type": "bearer"
   }
   

Set up Kong OAuth token authentication

Using the Keycloak and Kong Gateway configuration from the prerequisites, set up an instance of the OpenID Connect plugin.

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: Kong OAuth2.
• We only want to search for the bearer token in the headers.

With all of the above in mind, let’s test out Kong OAuth2 authentication 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": [
      "kong_oauth2"
    ],
    "bearer_token_param_type": [
      "header"
    ]
  }
}
    '

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":["kong_oauth2"],"bearer_token_param_type":["header"]}}'

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:
  - kong_oauth2
  bearer_token_param_type:
  - header
" | 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:
    - kong_oauth2
    bearer_token_param_type:
    - header

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 = ["kong_oauth2"]
    bearer_token_param_type = ["header"]
  }

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

Test the Kong OAuth token authentication

Request the service with a Kong OAuth token:

curl -I http:localhost:8000 \
  -H "Authorization: \
  \"Bearer $(curl -i -X POST --insecure https://localhost:8443/mock/oauth2/token \
  --data \"client_id=client\" \
  --data \"client_secret=secret\" \
  --data \"grant_type=client_credentials\" | \
    jq -r .access_token)\""

or

curl -I http:localhost:8000 \
  -H "Authorization: Bearer <access-token>"

You should get an HTTP 200 response.