Home / Kong Identity
Edit
Report

Authenticate OAuth clients with a Kong Identity authorization server

Uses: Kong Gateway Kong Identity deck
Incompatible with
on-prem
Related Documentation
Gateway Documentation decK Documentation
Tags
#authentication
Related Resources
Authentication
Kong Identity
Kong Identity principals and directories
Minimum Version
Kong Gateway - 3.15
TL;DR

Create a Kong Identity authorization server and OAuth client, create a principal, and link the client to the principal with an auth_server_client identity. Configure the OpenID Connect plugin with principals.enabled set to true to use Kong Identity as your IdP, then send a request with the client credentials in an Authorization: Basic header to a protected Gateway Service.

Prerequisites

Kong Konnect

This is a Konnect tutorial and requires a Konnect personal access token.

  1. Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.

  2. Export your token to an environment variable:

    export KONNECT_TOKEN='YOUR_KONNECT_PAT'

  3. Run the quickstart script to automatically provision a Control Plane and Data Plane, and configure your environment:

    curl -Ls https://get.konghq.com/quickstart | bash -s -- -k $KONNECT_TOKEN \
     --deck-output

    This sets up a Konnect Control Plane named quickstart, provisions a local Data Plane, and prints out the following environment variable exports:

    export DECK_KONNECT_TOKEN=$KONNECT_TOKEN
export DECK_KONNECT_CONTROL_PLANE_NAME=quickstart
export KONNECT_CONTROL_PLANE_URL=https://us.api.konghq.com
export KONNECT_PROXY_URL='http://localhost:8000'

    Copy and paste these into your terminal to configure your session.

decK   v1.64.0+

To complete this tutorial, install decK. We recommend keeping decK up to date with the latest version (1.64.0).

decK is a CLI tool for managing Kong Gateway declaratively with state files. This guide uses deck gateway apply, which directly applies entity configuration to your Gateway instance.

You can check your current decK version with deck version.

Required entities

For this tutorial, you’ll need Kong Gateway entities, like Gateway Services and Routes, pre-configured. These entities are essential for Kong Gateway to function but installing them isn’t the focus of this guide. Follow these steps to pre-configure them:

  1. Run the following command:

    echo '
_format_version: "3.0"
services:
  - name: example-service
    url: http://httpbin.konghq.com/anything
routes:
  - name: example-route
    paths:
    - "/anything"
    service:
      name: example-service
    protocols:
    - http
    - https
' | deck gateway apply -

To learn more about entities, you can read our entities documentation.

Kong Identity directory

A directory is a regional collection of principals. Create a directory for this tutorial:

DIRECTORY_ID=$(curl -X POST "https://us.api.konghq.com/v2/directories" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"\
     -H "Content-Type: application/json" \
     --json '{
       "name": "kong-identity-directory",
       "description": "Directory for this tutorial",
       "allow_all_control_planes": true
     }' | jq -r ".id"
)

Create an authorization server in Kong Identity

An authorization server in Kong Identity issues the OAuth tokens that clients present to authenticate to your service.

Create an authorization server using the /v1/auth-servers endpoint:

_response=$(curl -X POST "https://us.api.konghq.com/v1/auth-servers" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"\
     -H "Content-Type: application/json" \
     --json '{
       "name": "example-auth-server",
       "description": "Example auth server",
       "audience": "orders-api"
     }')

Export the env variables:

export AUTH_SERVER_ID=$(echo "$_response" | jq -r ".id")
export ISSUER_URL=$(echo "$_response" | jq -r ".issuer")

Create a client

The client is the credential that the OpenID Connect plugin uses to authenticate. Kong Identity autogenerates the client ID and secret.

Create a client using the /v1/auth-servers/$AUTH_SERVER_ID/clients endpoint:

_response=$(curl -X POST "https://us.api.konghq.com/v1/auth-servers/$AUTH_SERVER_ID/clients" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"\
     -H "Content-Type: application/json" \
     --json '{
       "name": "example-client",
       "allow_all_scopes": true,
       "allow_scopes": [],
       "access_token_duration": 300,
       "grant_types": [
         "client_credentials"
       ],
       "response_types": [
         "token"
       ],
       "redirect_uris": [],
       "login_uri": ""
     }')

Export the env variables:

export CLIENT_ID=$(echo "$_response" | jq -r ".id")
export CLIENT_SECRET=$(echo "$_response" | jq -r ".client_secret")

Create a principal

Create the Principal by sending a POST request to the /v2/directories/{directoryId}/principals endpoint:

PRINCIPAL_ID=$(curl -X POST "https://us.api.konghq.com/v2/directories/$DIRECTORY_ID/principals" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "display_name": "example-principal",
       "description": "Example principal"
     }' | jq -r ".id"
)

This script:

  • Creates a Principal named example-principal
  • Saves the returned ID as $PRINCIPAL_ID

Link the client to the principal

Link the Kong Identity authorization server client to the principal (used to unify authentication across Kong products) so that Kong Identity can map the OAuth tokens it issues to this principal. Because Kong Identity issues the tokens, you reference the authorization server and client you created earlier instead of an external issuer and claim.

Add the identity using the /v2/directories/$DIRECTORY_ID/principals/$PRINCIPAL_ID/identities endpoint:

curl -X POST "https://us.api.konghq.com/v2/directories/$DIRECTORY_ID/principals/$PRINCIPAL_ID/identities" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"\
     -H "Content-Type: application/json" \
     --json '{
       "type": "auth_server_client",
       "auth_server_id": "'$AUTH_SERVER_ID'",
       "client_id": "'$CLIENT_ID'"
     }'

Get the directory name

To configure the OpenID Connect plugin, you need the name of the directory you created. Store it as DECK_DIRECTORY_NAME so decK can read it during sync:

DECK_DIRECTORY_NAME=$(curl -X GET "https://us.api.konghq.com/v2/directories" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" | jq -r ".data[0].name"
)

Export the directory name so decK can read it during sync:

export DECK_DIRECTORY_NAME

Generate a salt token

Starting with decK v1.59+, you need to set cache_tokens_salt to avoid regenerating session credentials during sync. Generate a salt token:

export DECK_TOKEN_SALT="$(openssl rand -base64 16)"

Configure the OpenID Connect plugin

Export the variables to decK:

export DECK_ISSUER_URL=$ISSUER_URL
export DECK_CLIENT_ID=$CLIENT_ID
export DECK_CLIENT_SECRET=$CLIENT_SECRET

Configure the OpenID Connect plugin to use Kong Identity as the identity provider and map the client credentials. Setting principals.enabled to true maps the authenticated token to a directory. This example applies the plugin to the example-service you created in the prerequisites.

echo '
_format_version: "3.0"
plugins:
  - name: openid-connect
    service: example-service
    config:
      issuer: "${{ env "DECK_ISSUER_URL" }}"
      client_id:
      - "${{ env "DECK_CLIENT_ID" }}"
      client_secret:
      - "${{ env "DECK_CLIENT_SECRET" }}"
      client_auth:
      - client_secret_post
      auth_methods:
      - client_credentials
      client_credentials_param_type:
      - header
      principals:
        enabled: true
        directory: "${{ env "DECK_DIRECTORY_NAME" }}"
      cache_tokens_salt: "${{ env "DECK_TOKEN_SALT" }}"
' | deck gateway apply -

Validate

Base64-encode the client ID and secret for the Authorization header:

export CLIENT_CREDENTIALS=$(printf '%s' "$CLIENT_ID:$CLIENT_SECRET" | base64)

Send a request to the protected Gateway Service with the client credentials. The OpenID Connect plugin exchanges them for a token with Kong Identity, validates it, and maps it to your principal. The request should succeed with a 200 status code:

curl -i "$KONNECT_PROXY_URL/anything" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Basic $CLIENT_CREDENTIALS"

Send a request without credentials. Kong Identity rejects it because the request can’t be mapped to a principal:

curl -i $KONNECT_PROXY_URL/anything

This request returns a 401 error with the message Unauthorized.

Cleanup

Clean up Konnect environment

If you created a new control plane and want to conserve your free trial credits or avoid unnecessary charges, delete the new control plane used in this tutorial.

Destroy the Kong Gateway container

 
curl -Ls https://get.konghq.com/quickstart | bash -s -- -d
Something wrong?
Report an Issue | Edit this Page
View all Kong documentation

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!
Contribute

Still need help?

Ask in our Slack Community
Contact Support