Kong Identity

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

Kong Identity enables you to use Konnect to generate, authenticate, and authorize API access. Specifically, Kong Identity can be used for machine-to-machine authentication.

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

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.

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
  

In the authorization code flow:

1. (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.

2. The client makes a request that includes the client ID, secret, and scopes the user consented to.
3. The authorization server (Kong Gateway with OAuth2 plugin) validates the client credentials and returns an authorization code.
4. The client exchanges this code at the /oauth/token endpoint for access tokens.
5. The client uses the access token to call protected APIs.

You can configure dynamic claim templates to generate custom claims during runtime. 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 also be templated with contextual data and functions. Dynamic values must use ${} as templating boundaries.

Claims support templating via the context passed to the client during the authentication, in the following format:

{
  "AuthServer": {
    "ID": "uuid.UUID",
    "CreatedAt": "DateTime",
    "UpdatedAt": "DateTime",
    "Name": "string",
    "Description": "string",
    "Audience": "string",
    "SigningAlgorithm": "string",
    "Labels": {
      "key": "value"
    }
  },
  "Client": {
    "ID": "string",
    "CreatedAt": "DateTime",
    "UpdatedAt": "DateTime",
    "Name": "string",
    "Labels": {
      "key": "value"
    },
    "GrantTypes": [
      "string"
    ],
    "RedirectURIs": [
      "string"
    ],
    "LoginURI": "string",
    "ResponseTypes": [
      "string"
    ],
    "AllowAllScopes": true
  }
}

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