Kong Identity authorization servers, claims, scopes, and clients

Get started:

• Configure the OIDC plugin with Kong Identity
• Configure the Upstream OAuth plugin with Kong Identity
• Configure the OAuth 2.0 Introspection plugin with Kong Identity
• Automatically create Dev Portal applications in Kong Identity with Dynamic Client Registration

Kong Identity authentication servers enable you to use Konnect to generate, authenticate, and authorize API access. Specifically, Kong Identity auth servers can be used for machine-to-machine authentication and to do the following:

• Create authorization servers per region
• Issue and validate access tokens
• Integrate secure authentication into your Kong Gateway APIs

An Kong Identity authorization server is made up of clients, scopes, and claims:

• Auth server: Issues 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. They also configure the strategies by which those entities can authenticate to Kong Identity to retrieve access tokens (also called OAuth 2.0 grant types).
• 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.

Kong Identity implements the OAuth2.0 standard with OpenID Connect for authentication and authorization. Kong Identity can be used with the following Kong plugins:

• OpenID Connect plugin
• OAuth2.0 Introspection plugin
• Upstream OAuth plugin

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.

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

The client credentials flow is a standard OAuth flow where a client authenticates to Kong Identity using credentials (such as a client_id and client_secret) that you’ve issued beforehand. This can be useful when only the client needs to authenticate, such as:

• Machine-to-Machine (M2M) use cases
• A microservice authenticating to Kong Gateway

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
  

Client IDs and secrets

Kong Identity generates both the client_id and the client_secret values when you create a client on the authorization server from the UI or send a POST request to the API endpoint.

Note: Konnect doesn’t store the client’s secrets. Make sure to copy and securely store their values when they’re generated.

You can have a maximum of two secrets active at a time. This allows you to rotate secrets without incurring downtime using the API by sending a POST request to the /auth-servers/{authServerId}/clients/{clientId}/secrets endpoint.

Secret rotation is useful in cases such as:

• Scheduled rotation: When compliance policies require rotating credentials on a fixed schedule.
• Leaked secret: If a secret is exposed, you need to replace it without breaking any service that uses it.
• Shared client: When multiple services share one client, keeping both secrets active during rollout avoids breaking the ones that haven’t switched yet.

When creating a new secret, you can either:

• Provide your own secret value in the "secret" field.
• Let Kong Identity generate the secret automatically and save the value returned in the API response.

API request examples

The following query examples show how to request the Kong Identity Auth Servers API to create a new client secret with the following path parameters:

• Auth server ID
• Client ID

curl -X POST "https://us.api.konghq.com/v1/auth-servers/{authServerId}/clients/{clientId}/secrets" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"\
     -H "Content-Type: application/json" \
     --json '{
       "secret": "new-secret",
       "enabled": true
     }'

curl -X POST "https://us.api.konghq.com/v1/auth-servers/{authServerId}/clients/{clientId}/secrets" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"\
     -H "Content-Type: application/json" \
     --json '{
       "enabled": true
     }'

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:

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
}

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

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

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

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:

Supported functions

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

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.

You are limited to 50 auth servers per Konnect region.

To configure Kong Identity, do the following: