Kong Identity

Uses: Konnect Platform

How Kong Identity works

Kong Identity allows you to create auth servers, claims, scopes, and clients in Konnect using the Konnect API. Each of these components plays a specific role in how access is managed:

Auth server: Issue OAuth 2.0 and OpenID Connect tokens that you can use to authenticate a client (machine) with your Gateway Services. Each auth server is unique to your organization and Konnect region. We recommend creating different auth servers for different environments or subsidiaries.
Clients: Represent machines that request tokens, such as microservices, mobile apps, or automation scripts.
Scopes: Define what those clients are allowed to access.
Claims: Optional pieces of metadata, like user roles or environment tags, that can be included in tokens and forwarded to upstream services.

To use Kong Identity for authentication, you must configure one of the supported plugins (OpenID Connect, OAuth2.0 Introspection, or Upstream OAuth). These plugins determine how tokens are validated, introspected, or passed along to upstream services.

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

Kong Identity authorization code flow

In the authorization code flow:

(Optional) The client application displays the user consent page and authenticates the user (this part is handled outside Kong Gateway). When the user clicks Authorize, the client app calls the /authorize endpoint created by attaching the OAuth2 plugin to a service.

If an app requires user authentication, the authorization step must happen outside of Konnect.
The client makes a request that includes the client ID, secret, and scopes the user consented to.
The authorization server (Kong Gateway with OAuth2 plugin) validates the client credentials and returns an authorization code.
The client exchanges this code at the /oauth/token endpoint for access tokens.
The client uses the access token to call protected APIs.

Kong Consumer Group claim authorization flow

When using plugins scoped to Consumer Groups:

In Konnect > API Gateway > Consumers, the client creates the Consumer. Each user that needs access is represented as a Consumer.

If using OIDC, you don’t need to manually map credentials. The OIDC plugin automatically maps clients to Consumers based on token claims.
The client defines the required Consumer Groups in Konnect, and then applies the desired plugin at the Consumer Group scope.
The client assigns each Consumer to the appropriate Consumer Group. Once assigned, the plugin configuration at the group level automatically applies to the Consumer.

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`

Configure Kong Identity

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

How Kong Identity works

Kong Identity client credential authentication flow

Kong Identity authorization code flow

Kong Consumer Group claim authorization flow

Dynamic claim templates

Supported contexts

Supported functions

Configure Kong Identity

Help us make these docs great!

Still need help