Skip to content

feat(identity): access management concepts #7637

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
juliamrch wants to merge 3 commits into
base: release/ai-gateway-2.3
Choose a base branch
from
+201 −0
Open

feat(identity): access management concepts #7637

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1a942c5
draft
juliamrch Oct 19, 2026
7142ccb
draft users
juliamrch Oct 22, 2026
5516b22
access management features
juliamrch Oct 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions app/_indices/ai-gateway.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,7 @@ sections:
- title: Reference
items:
- path: /ai-gateway/ai-gateway-v2-concepts/
- path: /ai-gateway/access-management/concepts/
- path: /ai-gateway/configuration/
- path: /ai-gateway/configure-on-prem/
- path: /ai-gateway/v2-migration-guide/
Expand Down
200 changes: 200 additions & 0 deletions app/ai-gateway/access-management.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,200 @@
---
title: "Access management concepts"
content_type: reference
layout: reference
permalink: /ai-gateway/access-management/concepts/
works_on:
- konnect

products:
- ai-gateway
breadcrumbs:
- /ai-gateway/
tags:
- ai
- access-control
- authentication

# TODO: confirm min_version with the Access Management team
min_version:
ai-gateway: '2.2'
Comment on lines +18 to +20

@kong-ksai kong-ksai Bot Oct 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Low delete

min_version ships with a TODO that asks a team to confirm the version. The comment records an authoring step only, and a reader cannot act on it. Delete the comment and keep the version.

Suggested change
# TODO: confirm min_version with the Access Management team
min_version:
ai-gateway: '2.2'
min_version:
ai-gateway: '2.2'

React 👍 if this finding helped, 👎 if it did not.

@Guaris Guaris Oct 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is probably 2.3


description: "Learn what users, agents, groups, identity providers, Token Vault, and virtual keys are in {{site.ai_gateway}} access management, and how they relate to each other."

related_resources:
- text: "{{site.ai_gateway}}"
url: /ai-gateway/
- text: "Principals"
url: /identity/principals/
- text: "AI Agents"
url: /ai-gateway/entities/ai-agent/
- text: "AI Vaults"
url: /ai-gateway/entities/ai-vault/
- text: "AI Consumers"
url: /ai-gateway/entities/ai-consumer/
- text: "Token Vault"
url: /identity/token-vault/
---

Access management allows you to define who can use your organization's resources, like [models](/ai-gateway/entities/ai-model/) or [MCP servers](/ai-gateway/entities/ai-mcp-server/), in {{site.ai_gateway}}.

## How access management works

Access management uses Kong Identity features, such as [principals](/identity/principals/) and [auth servers](/identity/auth-servers/), to answer two questions:

@Guaris Guaris Oct 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Principals dont' show up in the M1 of Curly bassoon. I think principals may refer to users in this context but I'm not sure.

@Guaris Guaris Oct 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Confirmed, Users are principals.


* Who is making the request?
* What are they allowed to do?

You can give permissions to users individually, or in bulk using groups.

## Users

A user is a person who an admin adds to the system in one of two ways:

* An admin creates them manually, one at a time.
* An admin uploads a CSV file containing the org structure.

To create a user, you must provide the following:

* A name

@Guaris Guaris Oct 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* A name
* A name for the user

* An email

Once a user exists, an admin can:

Check warning on line 62 in app/ai-gateway/access-management.md

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[base.AvoidTemporalWords] Avoid time-relative wording ('Once a'). Docs go stale. Use 'after' or 'when' for sequence, and state the version or condition instead of what is current.

Raw Output:
{"message": "[base.AvoidTemporalWords] Avoid time-relative wording ('Once a'). Docs go stale. Use 'after' or 'when' for sequence, and state the version or condition instead of what is current.", "location": {"path": "app/ai-gateway/access-management.md", "range": {"start": {"line": 62, "column": 1}}}, "severity": "INFO"}

Check warning on line 62 in app/ai-gateway/access-management.md

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[base.AvoidTemporalWords] Avoid time-relative wording ('Once a'). Docs go stale. Use 'after' or 'when' for sequence, and state the version or condition instead of what is current.

Raw Output:
{"message": "[base.AvoidTemporalWords] Avoid time-relative wording ('Once a'). Docs go stale. Use 'after' or 'when' for sequence, and state the version or condition instead of what is current.", "location": {"path": "app/ai-gateway/access-management.md", "range": {"start": {"line": 62, "column": 1}}}, "severity": "INFO"}

Check warning on line 62 in app/ai-gateway/access-management.md

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[base.AvoidTemporalWords] Avoid time-relative wording ('Once a'). Docs go stale. Use 'after' or 'when' for sequence, and state the version or condition instead of what is current.

Raw Output:
{"message": "[base.AvoidTemporalWords] Avoid time-relative wording ('Once a'). Docs go stale. Use 'after' or 'when' for sequence, and state the version or condition instead of what is current.", "location": {"path": "app/ai-gateway/access-management.md", "range": {"start": {"line": 62, "column": 1}}}, "severity": "INFO"}

* Edit the user's details.
* Add the user to a group, or remove them from one.
* Create or delete [virtual keys](#virtual-keys) for the user. A user can also set their own virtual key.
* Link the user to a cost center.
* Delete or deactivate the user.
Comment on lines +62 to +68

@Guaris Guaris Oct 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does it makes sense to just have a section for admins, and everything that they can do in one place instead of adding it to the User H2


To stop a user from signing in while keeping their history, deactivate the user instead of deleting them.

{:.warning}
> You can't deactivate a user imported from a CSV file. To update the users, import an updated org chart.

An admin can view all users in one searchable table. Search matches on name only. You can filter the table by team, source, and status, and show or hide columns such as metadata and labels.

### Teams

You can assign users to a team. Teams can't be created manually. They are created when you import an org chart that groups users into teams. Teams can be nested under a parent team.

## Agents

An agent is the identity record for a piece of software that calls [models](/ai-gateway/entities/ai-model/) or [MCP servers](/ai-gateway/entities/ai-mcp-server/). It might act for itself, or on behalf of users.

The agent acts as the caller. Like users, it can:

* Hold [virtual keys](#virtual-keys) and remote credentials.
* Be linked to a cost center.

Agents in **Access Management** aren't the same thing as an [AI Agent](/ai-gateway/entities/ai-agent/):

* **AI Agents** are the resource you call through {{site.ai_gateway}}.
* **Agents** in **Access Management** are the identity that calls {{site.ai_gateway}} resources.

{:.warning}
> Agents can't belong to teams or sign in through an identity provider.

## Users versus agents

Users and agents share the following capabilities:

* Virtual keys
* Cost center
* Spend limits
* Group membership

@kong-ksai kong-ksai Bot Oct 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Low q

This list gives agents group membership, but the Groups section calls a group a list of users (line 146) and adds users only (line 155). Can an agent belong to a group? Make the two statements agree.

React 👍 if this finding helped, 👎 if it did not.


The following table lists their differences:

{% table %}
columns:
- title: Aspects
key: aspect
- title: Users
key: users
- title: Agents
key: agents
rows:
- aspect: What it represents
users: A person.
agents: Software that calls [models](/ai-gateway/entities/ai-model/), [MCP servers](/ai-gateway/entities/ai-mcp-server/), or other agents, including service accounts such as CI jobs.
- aspect: How it's created
users: Manually, or through an org structure import.
agents: From the **Agents** section. Agents aren't included in org structure imports.
- aspect: Required fields
users: Name and email.
agents: Name.
- aspect: How it authenticates
users: Signs in through an [identity provider](#identity-providers), and calls the gateway with a [virtual key](#virtual-keys).
agents: Uses only the credentials it holds, such as virtual keys and remote credentials.
- aspect: Org structure
users: Can belong to teams, appear on the org chart, and own a team.
agents: Not part of teams or the org chart.
- aspect: Link to a gateway resource
users: Can't be linked to a gateway resource.
agents: Can be linked to the [AI Agent](/ai-gateway/entities/ai-agent/) it represents.
- aspect: Lifecycle
users: Deactivate to stop sign-in and keep history. Imported users can't be deleted, and their name and email are read-only.
agents: Deactivate or delete.
- aspect: Kong Identity API type
users: "`user`"
agents: "`agent`"
{% endtable %}

## Groups

A group is a list of users that share the same rules. Instead of setting rules on each member, you set them once on the group.

@Guaris Guaris Oct 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A group is a list of users that share the same rules. Instead of setting rules on each member, you set them once on the group.
A group is a list of users and agents that share the same rules. Instead of setting rules on each member, you set them once on the group.

@Guaris Guaris Oct 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The prototype includes agents.


Admins create groups manually. A group can't contain another group.

@Guaris Guaris Oct 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Admins create groups manually. A group can't contain another group.

Feels better as a FAQ


In the {{site.konnect_short_name}} UI, you can:

* View groups in a list.
* Create a group with a name and description.
* Add labels and metadata to a group.
* Add users to a group, either from the groups screen or from a user.
* Edit a group and view its details.
* Delete a group.

@Guaris Guaris Oct 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* Export groups as a CSV

Groups don't have a cost center.

## Identity providers

An identity provider is an external service, such as Okta or Auth0, that signs the tokens people and agents present. Kong trusts the providers you list and uses them to verify that those tokens are genuine.

@kong-ksai kong-ksai Bot Oct 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Low q

This sentence says identity providers sign the tokens people and agents present, but the Agents warning (line 96) says agents can't sign in through an identity provider, and the table (line 129) says agents use only credentials they hold. Which holds for agents? Make the statements agree.

React 👍 if this finding helped, 👎 if it did not.


[Token Vault](#token-vault) needs at least one trusted identity provider to verify callers. You can add a provider, remove one you no longer want Token Vault to rely on, and review the table of trusted providers with their display names, issuer URLs, and linked identities.

To learn more, see [Token Vault's providers](/identity/token-vault/#providers).

## Token Vault

Token Vault stores credentials so that {{site.ai_gateway}} can call external services on behalf of a caller. To set it up:

1. Add at least one trusted [identity provider](#identity-providers).
1. Generate a public encryption key for the vault and set the private key reference on a gateway.

@Guaris Guaris Oct 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
1. Generate a public encryption key for the vault and set the private key reference on a gateway.
1. Configure how Token Vault authenticates with this provider

This feels safe considering there are many providers

1. Create credential providers. A credential provider uses either OAuth or a static API key.

When you set up an [MCP server](/ai-gateway/entities/ai-mcp-server/), you can choose a credential provider for outbound authentication as an alternative to pass-through. You can view the credentials stored in the vault from the provider and identity provider detail pages.

To learn more, see [Token Vault](/identity/token-vault/).

## Virtual keys

A virtual key is an API key that lets a caller use {{site.ai_gateway}}. For example, instead of adding an Anthropic API key to an agent, you generate a virtual key for the agent. The agent uses the virtual key, while the provider API keys stay in [Token Vault](#token-vault) instead of in your apps.

Use virtual keys to:

* **Reinforce API key security:** Virtual keys can be generated and revoked cleanly.

@Guaris Guaris Oct 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* **Reinforce API key security:** Virtual keys can be generated and revoked cleanly.
* **Reinforce API key security:** Virtual keys can be generated and deleted.

It's just called delete note revoke, I think there is a semantic difference.

* **Enforce and monitor costs:** You can link each virtual key to a cost center and set a spend limit.

@Guaris Guaris Oct 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't see how I actually do this. When I create a key I can't associate it with a cost center. I think a spend limit may be more associated to a group.

* **Gain visibility:** The key list shows when each key was last used, so you can delete stale ones.

The gateway treats whoever holds the key as the caller.

@Guaris Guaris Oct 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think virtual keys are associated to users or groups.


You can create a key in two ways:

* Have {{site.ai_gateway}} generate the key.
* Set your own key value.

In both cases, you set an expiry. When you create a key for someone else, you pick the holder. You can filter the holder list by users or agents, and add a new user or agent inline.

The key list shows each key's holder, status, expiry, and creation date. You can revoke or delete a key. Rotating a key isn't supported. To rotate a key, create a new one and revoke the old one.
Loading