Claims-based authorization

The following options can be configured to manage claims verification during authorization:

1. config.scopes_claim and config.scopes_required
2. config.audience_claim and config.audience_required
3. config.groups_claim and config.groups_required
4. config.roles_claim and config.roles_required

For example, the first configuration option, config.scopes_claim, points to a source, from which the value is retrieved and checked against the value of the second configuration option: config.scopes_required.

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

Claims-based authorization

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.

First, configure the OpenID Connect plugin. For the purposes of the demo, you can use the password 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: password grant (enabled for demo purposes).

• We require the values openid and email to be present in the scope claim of the access token.

  A claim payload may contain arbitrary claims, such as user roles and groups, but as you didn’t configure them in Keycloak, let’s just use the claims that are configured. In this case, we want to authorize against the values in scope claim.

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": [
      "password"
    ],
    "scopes_claim": [
      "scope"
    ],
    "scopes_required": [
      "openid",
      "email"
    ]
  }
}
    '

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":["password"],"scopes_claim":["scope"],"scopes_required":["openid","email"]}}'

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:
  - password
  scopes_claim:
  - scope
  scopes_required:
  - openid
  - email
" | 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:
    - password
    scopes_claim:
    - scope
    scopes_required:
    - openid
    - email

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 = ["password"]
    scopes_claim = ["scope"]
    scopes_required = ["openid", "email"]
  }

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

Test the claims-based authorization

Retrieve access token

In this example, the password grant lets you obtain a JWT access token, enabling you to test how JWT access token authentication works. One way to get a JWT access token is to issue the following call (we use jq to filter the response):

curl --user john:doe http://localhost:8000/openid-connect \
    | jq -r .headers.Authorization

Output:

Bearer <access-token>

The signed JWT <access-token> (JWS) composed of three parts, each separated with a dot character .: <header>.<payload>.<signature> (a JWS compact serialization format). We are interested with the <payload>, and you should have something similar to:

eyJleHAiOjE2MjI1NTY3MTMsImF1ZCI6ImFjY291bnQiLCJ0eXAiOiJCZWFyZXIiLC
JzY29wZSI6Im9wZW5pZCBlbWFpbCBwcm9maWxlIiwicHJlZmVycmVkX3VzZXJuYW1l
Ijoiam9obiIsImdpdmVuX25hbWUiOiJKb2huIiwiZmFtaWx5X25hbWUiOiJEb2UifQ

That can be base64 url decoded to the following JSON:

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

Access the service

Try accessing the service:

curl --user john:doe http://localhost:8000

You should get an HTTP 200 response.

If you set a claim that isn’t enabled in your IdP, you will get a 403 Forbidden response instead.

For example, if you also add audience_claim = aud to the plugin’s configuration and try to access it with your Keycloak credentials from the prerequisites, the response will be a 403, as the access token has "aud": "account", and that does not match "httpbin".

Arrays in claims-based configuration

A few words about config.scopes_claim and config.scopes_required (and the similar configuration options). You may have noticed that config.scopes_claim is an array of string elements. Why? It is used to traverse the JSON when looking up a claim, take for example this imaginary payload:

{
    "user": {
        "name": "john",
        "groups": [
            "employee",
            "marketing"
        ]
    }
}

In this case you would probably want to use config.groups_claim to point to groups claim, but that claim is not a top-level claim, so you need to traverse there:

1. Find the user claim.
2. Inside the user claim, find the groups claim, and read its value:

{
    "config": {
        "groups_claim": [
            "user",
            "groups"
        ]
    }
}

or

curl -i -X PATCH http://localhost:8001/plugins/5f35b796-ced6-4c00-9b2a-90eef745f4f9 \
  --data "config.groups_claim=user" \
  --data "config.groups_claim=groups"

The value of a claim can be the following:

• a space separated string (such as scope claim usually is)
• an JSON array of strings (such as the imaginary groups claim above)
• a simple value, such as a string

What about the config.groups_required then? That is also an array?

That is correct, the required checks are arrays to allow logical and/or type of checks:

1. and: use a space separated values
2. or: specify value(s) in separate array indices

For example:

{
    "config": {
        "groups_required": [
            "employee marketing",
            "super-admins"
        ]
    }
}

or

curl -i -X PATCH http://localhost:8001/plugins/5f35b796-ced6-4c00-9b2a-90eef745f4f9 \
  --data "config.groups_required=employee marketing" \
  --data "config.groups_required=super-admins"

The above means that a claim has to have:

1. employee and marketing values in it, OR
2. super-admins value in it