Kong Identity authorization servers, claims, scopes, and clients

Uses: Kong Identity Konnect Platform

Use cases

The following table describes when you’d want to use Kong Identity authorization servers:

Use case	Description
Issue OAuth 2.0 access tokens for machine clients	Use a Konnect-hosted authorization server to issue OAuth 2.0 and OpenID Connect tokens that authenticate machine clients to your Kong Gateway APIs.
Inject custom or dynamic claims into JWTs	Define static or dynamic claims on an auth server so tokens carry the metadata your upstream services and plugins need.
Centralize OAuth client registration	Manage OAuth clients in one place and reuse them across multiple Kong Gateway control planes in the same region.
Integrate with Dev Portal applications	Register Dev Portal applications as Kong Identity clients automatically using Dynamic Client Registration.

Kong Identity client credential authentication flow

The following diagram shows how authentication works with Kong Identity:

 
sequenceDiagram
    autonumber
    participant client as Client Application
    participant idsvc as Kong Identity Service
    participant gateway as Kong Gateway
    participant api as Customer API
    client->>idsvc: request access token
(Client ID, Client Secret, requested scope)
    idsvc->>idsvc: validate credentials
    idsvc-->>client: access token, granted scope, expiry time
    client->>gateway: /get_protected_resource
(access token, granted scope)
    gateway->>idsvc: validate access token
    idsvc-->>gateway: validate access token
    gateway->>api: get_resource
    api-->>gateway: resource
    gateway-->>client: resource

You can configure each claim to be included or not in the JWT token issued by the authorization server, based on the scopes the client requests. Including the claim can be useful to validate the token offline, however, the data in the claim can be viewed by anyone who has the token. You can configure a claim in two ways:

In the Konnect UI.
Using the Konnect API.

When configuring a claim, you can choose from the following options:

UI setting	Description	Example
Always include	The claim is always included in the token, regardless of which scopes the client requests.	A claim named “role” with the value “employee”. It appears in the token whether the client requests specific scopes or not. An API could check this claim to make sure only employees can access internal endpoints.
Only include when specific scopes are requested	The claim is only included in the token when the client explicitly requests one of the associated scopes.	A “read” claim that only shows up when the client asks for a specific “read” scope, but not for other scopes.
Only include when no scopes are requested	The claim is included in the token only when the client does not request any specific scope.	A “default-access” claim that grants minimal baseline permissions when a client authenticates without specifying what it needs.
Never include	The claim exists in the auth server for internal reference but is never embedded in tokens.	A “department” claim used to organize clients internally. It’s saved in the auth server but never sent to APIs.

API parameters

Configure the claim by sending a POST request to the /auth-servers/{authServerId}/claims endpoint.

{
  "name": "",
  "value": "",
  "include_in_token": true,
  "include_in_all_scopes": true,
  "include_in_scopes": [],
  "enabled": true
}

Copied!

{
  "name": "",
  "value": "",
  "include_in_token": true,
  "include_in_all_scopes": false,
  "include_in_scopes": [
    "$SCOPE_UUID"
  ],
  "enabled": true
}

Copied!

{
  "name": "",
  "value": "",
  "include_in_token": true,
  "include_in_all_scopes": false,
  "include_in_scopes": [],
  "enabled": true
}

Copied!

{
  "name": "",
  "value": "",
  "include_in_token": false,
  "include_in_all_scopes": false,
  "include_in_scopes": [],
  "enabled": true
}

Copied!

Dynamic claim templates

Dynamic claim templates allow you to define custom JWT claims, where the claim value is determined at the time the access token is generated. The value is based on contextual data and specified functions. For example, you can use a dynamic claim template so that Konnect populates a random UUID for the client.

You can use dynamic claim templates for both the auth server and client.

These JWT claim values can be rendered as any of the following types:

Strings
Integers
Floats
Booleans
JSON object or arrays

The type is inferred from the value.

JWT claim values can be templated with contextual data and functions. Dynamic values must use ${} as templating boundaries. For example:

${ uuidv4 } creates a UUID every time a new token is created.
${ .Client.Name } includes the client’s name in the token.
${ now | date "2006-01-02T15:04:05Z07:00" } generates the current timestamp in ISO 8601 format.
${ .AuthServer.Audience }-${ .Client.ID } concatenates the auth server’s audience with the client ID.
${ .Client.Labels.environment | default "production" } uses the client’s environment label, defaulting to “production” if it isn’t set.
${ upper .Client.Name } converts the client name to uppercase.
${ randAlphaNum 16 } generates a random 16-character alphanumeric string for each token.

You can use uuidParse and uuidValidate in your dynamic claim templates to parse a string as a UUID and check for a valid UUID, respectively.

To test the templating, you can use the /v1/auth-servers/$authServerId/clients/$clientId/test-claim endpoint.

Supported contexts

Dynamic claims can use the context passed to the client during authentication in the following format:

Variable Name	Description	Format
AuthServer.ID	A regionally unique UUID of the auth server	uuid.UUID
AuthServer.CreatedAt	The timestamp when the auth server was created	DateTime
AuthServer.UpdatedAt	The timestamp when the auth server was last updated	DateTime
AuthServer.Name	The name of the auth server	string
AuthServer.Description	A description of the auth server	string
AuthServer.Audience	The intended audience for tokens issued by this auth server	string
AuthServer.SigningAlgorithm	The algorithm used to sign the JWT (for example, RS256, HS256)	string
AuthServer.Labels.key	A key/value label for metadata tagging	string
Client.ID	The ID of the client	string
Client.CreatedAt	The timestamp when the client was created	DateTime
Client.UpdatedAt	The timestamp when the client was last updated	DateTime
Client.Name	The name of the client	string
Client.Labels.key	A key/value label for metadata tagging	string
Client.GrantTypes[]	The grant types supported by the client (for example, `client_credentials`)	string
Client.RedirectURIs[]	Allowed redirect URIs for the client	string
Client.LoginURI	Login URI for interactive flows	string
Client.ResponseTypes[]	Supported OAuth response types (for example, code, token)	string
Client.AllowAllScopes	Indicates if all scopes are allowed by default	boolean

Supported functions

Dynamic claim templates support all the following functions from sprig in the claim templating engine:

Type	Supported functions
Date functions	`ago` `date` `dateInZone` `dateModify` `duration` `durationRound` `htmlDate` `htmlDateInZone` `mustDateModify` `mustToDate` `now` `toDate` `unixEpoch`
Strings	`abbrev` `abbrevboth` `trunc` `trim` `upper` `lower` `title` `untitle` `substr` `repeat` `trimAll` `trimSuffix` `trimPrefix` `nospace` `initials` `randAlphaNum` `randAlpha` `randAscii` `randNumeric` `swapcase` `shuffle` `snakecase` `camelcase` `kebabcase` `wrap` `wrapWith` `contains` `hasPrefix` `hasSuffix` `quote` `squote` `cat` `indent` `nindent` `replace` `plural` `sha1sum` `sha256sum` `adler32sum` `toString` `atoi` `int64` `int` `float64` `seq` `toDecimal` `split` `splitList` `splitn` `toStrings` `until` `untilStep` `join` `sortAlpha`
Math	`add1` `add` `sub` `div` `mod` `mul` `randInt` `add1f` `addf` `subf` `divf` `mulf` `biggest` `max` `min` `maxf` `minf` `ceil` `floor` `round`
Defaults	`default` `empty` `coalesce` `all` `any` `compact` `mustCompact` `fromJson` `toJson` `toPrettyJson` `toRawJson` `mustFromJson` `mustToJson` `mustToPrettyJson` `mustToRawJson` `ternary` `deepCopy` `mustDeepCopy`
Paths	`base` `dir` `clean` `ext` `isAbs`
Encoding	`b64enc` `b64dec` `b32enc` `b32dec`
Data Structures	`tuple` `list` `dict` `get` `set` `unset` `hasKey` `pluck` `keys` `pick` `omit` `merge` `mergeOverwrite` `mustMerge` `mustMergeOverwrite` `values` `append` `mustAppend` `prepend` `mustPrepend` `first` `mustFirst` `rest` `mustRest` `last` `mustLast` `initial` `mustInitial` `reverse` `mustReverse` `uniq` `mustUniq` `without` `mustWithout` `has` `mustHas` `slice` `mustSlice` `concat` `dig` `chunk` `mustChunk`
UUIDs	`uuidv4`
URLs	`urlParse` `urlJoin`

Principals and directories

Kong Identity uses principals and directories to unify how Kong products represent the entities they authenticate.

Principal: Represents an external client, workload, or human authenticating to a Kong Gateway (not a Konnect user or Dev Portal developer).
Directory: Regional collection of principals. Each Konnect organization can provision up to one directory per region by default.

Principals work with:

Kong Gateway in Konnect: Principals can authenticate an entity for API traffic (using API keys or basic auth usernames and passwords), or can provide metadata about an entity already authenticated through another mechanism (such as OAuth).
Event Gateway: Principals can provide metadata about an entity already authenticated through another mechanism (such as SASL/SCRAM or SASL/OAUTHBEARER).
Dev Portal: Principals can adjust API gateway behavior based on the authenticating Dev Portal.

For more information, see the Principals reference.

Create an auth server, claim, and client in Kong Identity

You are limited to 50 auth servers per Konnect region.

To configure Kong Identity, do the following:

In the Konnect sidebar, click Identity.
Click New authorization server.
In the Name field, enter a name.
In the Audience field, enter the audience.

Note: The value in the Audience field is the audience that the token is intended for, like a client ID or the upstream URL of the Gateway Service for the API resource. For example, https://api.example.com/payments and http://myhttpbin.dev. If you don’t have an intended audience, you can put a placeholder value, like orders-api, in this field.
Click Create.
Click New scope.
In the Name field, enter a name for your scope.
Click Create.
Navigate back to your authorization server.
Click New claim.
In the Name field, enter a name for your claim.
In the Value field, enter the value for your claim. These can also be dynamic.
From the When to include this claim in tokens dropdown menu, select an option.
Click Create.
Navigate back to your authorization server.
Click New client.
In the Name field, enter a name for your client.
From the Allowed scopes dropdown menu, select an option.
Click Create.
Copy and save your client ID and secret.

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

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": "Appointments Dev",
       "audience": "http://myhttpbin.dev",
       "description": "Auth server for the Appointment dev environment"
     }'

Copied!

Export the auth server ID and issuer URL:

export AUTH_SERVER_ID='YOUR-AUTH-SERVER-ID'
export ISSUER_URL='YOUR-ISSUER-URL'

Copied!

Configure a scope in your auth server using the /v1/auth-servers/$AUTH_SERVER_ID/scopes endpoint:

curl -X POST "https://us.api.konghq.com/v1/auth-servers/$AUTH_SERVER_ID/scopes" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"\
     -H "Content-Type: application/json" \
     --json '{
       "name": "my-scope",
       "description": "Scope to test Kong Identity",
       "default": false,
       "include_in_metadata": false,
       "enabled": true
     }'

Copied!

Export your scope ID:
```
export SCOPE_ID='YOUR-SCOPE-ID'
```
Copied!

Configure a custom claim using the /v1/auth-servers/$AUTH_SERVER_ID/claims endpoint:

curl -X POST "https://us.api.konghq.com/v1/auth-servers/$AUTH_SERVER_ID/claims" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"\
     -H "Content-Type: application/json" \
     --json '{
       "name": "test-claim",
       "value": "test",
       "include_in_token": true,
       "include_in_all_scopes": false,
       "include_in_scopes": [
         "'$SCOPE_ID'"
       ],
       "enabled": true
     }'

Copied!

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

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": "Client",
       "grant_types": [
         "client_credentials"
       ],
       "allow_all_scopes": false,
       "allow_scopes": [
         "'$SCOPE_ID'"
       ],
       "access_token_duration": 3600,
       "id_token_duration": 3600,
       "response_types": [
         "id_token",
         "token"
       ]
     }'

Copied!

Export your client secret and client ID:

export CLIENT_SECRET='YOUR-CLIENT-SECRET'
export CLIENT_ID='YOUR-CLIENT-ID'

Copied!

Kong Identity authorization servers, claims, scopes, and clients

Use cases

Kong Identity client credential authentication flow

Claim configuration

API parameters

Dynamic claim templates

Supported contexts

Supported functions

Principals and directories

Create an auth server, claim, and client in Kong Identity

Help us make these docs great!

Still need help?