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.

The following table describes when you’d want to use principals:

Every principal carries some combination of credentials, identities, and metadata.

Credentials

Credentials are secrets a principal presents at authentication time. You need an API Gateway configured in Konnect to use credentials because the gateway checks them directly against the directory and authenticates the principal.

Kong Identity supports the following credential types:

• Username and password: A principal can have up to two passwords per username to support rotation. Principals in the same directory can’t share a username.
• API key: Each API key must be unique within a directory. API keys can be system-generated by Kong Identity or imported with a custom secret value.

A single principal can have multiple credentials, including multiple credentials of the same type. To authenticate using a credential, a principal must exist in the target directory with a matching credential set.

Identities

Identities are how other systems recognize the principal. Kong Identity uses them either:

• For lookup after authentication has already happened somewhere else (like a third-party IdP).
• To link a principal to an entity in another Kong product.

You can add identities to the principal as a separate resource after you’ve created a principal.

Kong Identity supports the following identity types:

A single principal can have multiple identities, including multiple of the same type.

Lookup caching and time-to-live (TTL): Kong Identity caches principal lookups, so additional lookups don’t require a connection to Kong Identity until it evicts the cache. For Kong Gateway, the eviction rate depends on the smallest of the following:

• The TTL set on the directory (10 minutes by default)
• The TTL set on a credential
• The caching configuration on Kong Gateway. Cached principals are in the general cache pool which can be configured by setting db_cache_ttl.

Principal entity mapping

Principals centralize the concept of an authenticating entity across Kong products. Each product has its own representation of who is authenticating. For example, Kong Gateway has Consumers and Consumer Groups:

• Consumers: Attach a control_plane_consumer identity to map a principal to a Consumer in a specific Kong Gateway control plane. When a Kong Identity-compatible authentication plugin authenticates the principal, the mapped Consumer loads into the request context just as if the Consumer had been authenticated directly. This allows existing Consumer-scoped plugins to function while you migrate to principals.
• Consumer Groups: Map a principal to one or more Consumer Groups by setting the reserved consumer_groups key in the principal’s metadata to a list of Consumer Group UUIDs. Consumer Groups have a many-to-many relationship with principals:
  • The same group can map to many principals
  • One principal can map to many groups.

  If the principal is also mapped to a Consumer and that Consumer belongs to its own Consumer Groups, the gateway loads the union of both sets into the request context. Only Consumer Groups that are defined in the same Kong Gateway as the control plane will be loaded into the request context.

When to use principals instead of Consumers

Kong Gateway Consumers have limitations that principals can address:

• Scale beyond Consumer limits: Users with large populations of authenticating entities can exceed the Consumer control plane limits. Consumers are loaded into data plane memory while principals are loaded on demand when they authenticate.
• Share identity across gateways without manual sync: When the same entity needs to authenticate to multiple gateways, Consumers must be replicated. A principal lives in one directory and can be referenced from any gateway in the same region.
• Unify identity across Kong products: Consumers and applications each represent the same logical entity in different ways, which makes it hard to reason about authentication, policy, and observability together. Principals replace that with one model.
• Attach metadata to identity: Consumers don’t support metadata, which forces custom plugins or header-injection workarounds when you want per-entity rate limits, conditional plugin behavior, or richer logs. Principals support metadata natively.

Metadata

Metadata is a set of key-value pairs associated with a principal. Kong Identity authenticates or looks up a principal, then makes the metadata available in the request context of a Kong Gateway or Event Gateway.

You can use metadata to configure how a gateway behaves when that principal is authenticated to it. For example, a Request Termination plugin can block access only when principal.metadata.business_unit == "payments".

Plugins can read principal attributes from the request context after authentication. The only way to scope plugins to a principal is by using conditional plugin execution on the principal metadata.

For example, a plugin scoped to gold-tier principals would use a condition like this:

condition: principal.metadata.tier == "gold"

The following request context fields are available to plugins:

• principal.id: The UUID of the principal
• principal.metadata.*: Any metadata key on the principal
• principal.display_name: The name of the principal

Event Gateway doesn’t authenticate clients with Kong Identity directly. Authentication happens at the broker (for example, SASL/PLAIN, SASL/SCRAM, SASL/OAUTHBEARER, or mTLS). After authentication, Event Gateway can look up the matching principal in a Kong Identity directory and attach its metadata to the connection context so that policies can use it.

This pattern is useful when you want consistent metadata-driven policy decisions for clients that are authenticated by an external mechanism, like Kafka clients connecting with SASL credentials. The metadata lives on the principal, not on the credential, so you can change it without editing the broker.

To fetch principal metadata on a virtual cluster, add a fetch_kong_identity_principal block to the cluster’s authentication configuration. The block references the directory to look up and the identity key to match the authenticated value against. For example, a custom identity on sasl_username matches the SASL username sent by the Kafka client. When a match is found, the principal’s metadata is attached to context.auth.principal.metadata.* for the lifetime of the connection.

A Modify Headers policy that only runs for principals on the operators team would use a condition like this:

condition: context.auth.principal.metadata.team == "operators"

Configuring a principal is a multi-step process. You always create the principal first, then attach identities. Metadata is optional.

The following examples show how to configure identities, credentials, and metadata on a principal. Before using them, you need an existing principal in a directory.

Basic auth

Add a username and password credential to a principal so clients can authenticate at Kong Gateway with basic auth.

curl -X POST "https://us.api.konghq.com/v2/directories/$DIRECTORY_ID/principals/$PRINCIPAL_ID/basic-auths" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "username": "example-user"
     }'

curl -X POST "https://us.api.konghq.com/v2/directories/$DIRECTORY_ID/principals/$PRINCIPAL_ID/basic-auths/$BASIC_AUTH_ID/passwords" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "secret": "example-password"
     }'

Key auth

Add an API key credential to a principal so clients can authenticate at Kong Gateway with key auth.

curl -X POST "https://us.api.konghq.com/v2/directories/$DIRECTORY_ID/principals/$PRINCIPAL_ID/api-keys" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "type": "v1"
     }'

OpenID Connect

Reference a principal authenticated by an external IdP such as Okta or Cognito.

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" \
     --json '{
       "type": "oidc",
       "issuer": "https://idp.example.com",
       "claim": {
         "name": "sub",
         "value": "example-subject"
       }
     }'

Auth server client

Reference a client on a Kong Identity auth server in the same region.

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" \
     --json '{
       "type": "auth_server_client",
       "auth_server_id": "'$AUTH_SERVER_ID'",
       "client_id": "'$CLIENT_ID'"
     }'

Link a principal to a Consumer

Map a principal to a Consumer in a specific Kong Gateway control plane. At most, you can map one Consumer per control plane to a principal. You can map multiple Consumers if they are in different control planes.

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" \
     --json '{
       "type": "control_plane_consumer",
       "control_plane_id": "'$CONTROL_PLANE_ID'",
       "consumer_id": "'$CONSUMER_ID'"
     }'

Link a principal to Consumer Groups

Map a principal to one or more Consumer Groups in a Kong Gateway control plane.

Consumer Groups are mapped through the principal’s metadata using the reserved consumer_groups key, not through the identities resource.

Send a PATCH request to the /v2/directories/{directoryId}/principals/{principalId} endpoint:

curl -X PATCH "https://us.api.konghq.com/v2/directories/$DIRECTORY_ID/principals/$PRINCIPAL_ID" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "metadata": {
         "consumer_groups": [
           "'$CONSUMER_GROUP_ID'"
         ]
       }
     }'

Keep the following in mind when mapping Consumer Groups:

• If the principal is also mapped to a Consumer (for example, Consumer X) and that Consumer belongs to its own Consumer Groups (for example, Group C and Group D), and the principal’s consumer_groups metadata also lists Group A and Group B, then all four groups (A, B, C, and D) load into the request context.
• Consumer Groups must be defined in the same control plane and workspace as the plugin.
• Consumer Groups have a many-to-many relationship with principals.

Custom

Look up a principal by an identifier from an external system.

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" \
     --json '{
       "type": "custom",
       "key": "sasl_username",
       "value": "john"
     }'

The following are default limits for principals and directories:

• 1 directory per region. Contact Kong Support if you need more than one directory.
• 100,000 principals per directory. Contact Kong Support if you need higher limits.
• 10 identities per principal
• 5 of each credential type per principal
• 50 metadata keys per principal
• 2 passwords per username (for rotation)
• Usernames and API keys must be unique within a directory
• Custom identity name and value combinations must be unique within a directory
• OIDC identity issuer and claim combinations must be unique within a directory
• Limit of 100 authentication or principal lookup requests per second per directory, not counting cached requests
• At most, you can map one Consumer per control plane to a principal. You can map multiple Consumers if they are in different control planes.