# Authentication and authorization

```json metadata
{
  "schema_version": 2,
  "title": "Authentication and authorization",
  "description": "Configure Context Gateway Control Plane credentials, agent-key grants, and identity provider sign-in for agents.",
  "categories": ["docs","operate","iris"],
  "tableOfContents": {"sections":[{"id":"credentials","title":"Credentials"},{"id":"control-plane-admin-token","title":"Control Plane admin token"},{"id":"gateway-authorization-and-grants","title":"Gateway authorization and grants"},{"children":[{"id":"upgrade-from-the-shared-audience","title":"Upgrade from the shared audience"},{"id":"grant-signed-in-users-access","title":"Grant signed-in users access"}],"id":"identity-provider-sign-in","title":"Identity provider sign-in"},{"id":"rotate-credentials","title":"Rotate credentials"}]}

,
  "codeExamples": []
}
```


## Credentials

| Credential | Who presents it to whom | Secret / key | Auto-generated? | What it unlocks |
| --- | --- | --- | --- | --- |
| Control Plane admin token | Operator → Control Plane (`:9100`) | The Secret in `controlplane.adminToken` / `token` | No | Gateway and Upstream management: `/iris/v1/context-gateway/gateways` |
| Control Plane internal token | Identity Service → Control Plane | The Secret in `controlplane.internalToken` / `token` | No | Checking that the Gateway in a grant exists |
| Data Plane runtime token | Data Plane → Identity Service | The Secret in `dataplane.runtimeToken` / `token` | No | Checking agent keys for `context-gateway` |
| Identity Service control token | Operator → Identity Service (`:9200`) | Set on the Identity Service release. By default the Identity Service chart generates it (`control.autoGenerate: true`), so read it from the Secret the chart generates | Yes, by default | Creating, listing, rotating, and revoking agent keys |
| Agent key | Agent → Data Plane (`:8083`) | None. Returned once when minted or rotated | No | Listing and calling tools on the Gateways its grants name |
| Identity provider access token | Agent → Data Plane (`:8083`) | None. Issued by your identity provider | No | The Gateways its role or subject grants name |

The admin, internal, and runtime tokens must be distinct. An agent key gets `401` from the Control Plane. No credential that an agent presents is sent to an Upstream.

The chart consumes externally created token files. Provision the admin, internal, and runtime Secrets before installing the release.

## Control Plane admin token

The examples use the admin token in `Authorization: Bearer <token>` for Gateway and Upstream operations. Deployments that configure `controlplane.config.auth.oidc` can also authorize administrators with identity provider access tokens. The admin token remains available, and the health routes need no credential.

Load the token from your Secret before you call the Control Plane:

```bash
export IRIS_CONTEXT_GATEWAY_SERVICE_TOKEN="$(kubectl -n <namespace-name> get secret \
  <admin-token-secret> -o jsonpath='{.data.token}' | base64 --decode)"
```

## Gateway authorization and grants

An agent key needs a grant on each Gateway it uses:

| Grant field | Value |
| --- | --- |
| `tenant` | The deployment's `tenantId`. |
| `product` | `context-gateway` |
| `resourceType` | `gateway` |
| `resourceId` | The Gateway ID. |
| `actions` | `["use"]` or `["full"]` |

One grant covers listing and calling every tool on the Gateway, including tools that change data. Model Context Protocol (MCP) tool annotations do not limit it.

The Identity Service mints a key only for a Gateway that exists in the tenant and is not being deleted. A revoked key stops working within the Identity Service cache lifetime, 300 seconds by default.

The [API examples](https://redis.io/docs/latest/operate/iris/context-gateway/self-managed/api-examples#mint-an-agent-key) show the complete request.

## Identity provider sign-in

Turn on sign-in to let MCP clients use access tokens from your identity provider (IdP). The Data Plane validates each token itself and serves protected resource metadata so that clients can find the IdP. IdP tokens are accepted only in `Authorization: Bearer`, never in `X-Api-Key`, and they never reach an Upstream.

Set these keys under `dataplane.config.auth.oidc`:

| Key | Value |
| --- | --- |
| `enabled` | `true` |
| `issuer` | Your IdP's issuer URL. |
| `audience` | Exactly one API identifier that belongs to the Data Plane alone, such as `api://context-gateway-dp`. Not the shared `api://redis-iris`. Tokens audienced at a Gateway's MCP URL are also accepted. |
| `jwks_uri` | Your IdP's JSON Web Key Set (JWKS) URL. |
| `user_id_claim` | The claim that identifies a user. `sub` by default, `oid` for Microsoft Entra ID. |
| `role_mappings` | Maps IdP role or group claim values to Iris roles, such as `gateway_user`. |

`dataplane.config.oauth.public_base_url` defaults to `publicBaseURL`, the Data Plane's public origin. The issuer and key set URLs must use HTTPS.

Register the Data Plane's audience as a separate API at your IdP. On Microsoft Entra ID, that is a second app registration. Don't use the shared `api://redis-iris` audience that the Control Plane and the Iris UI use. MCP clients hold the sign-in token, and the shared audience would also open Agent Memory and Playbook for the user. The Data Plane refuses to start with `api://redis-iris`. It cannot see a renamed shared audience, so if you renamed it, choose a different value here too. Don't give MCP clients the shared audience or its scope either: a token that carries both audiences still opens Agent Memory and Playbook.

### Upgrade from the shared audience

Earlier chart versions documented `api://redis-iris` for the Data Plane, and the Data Plane now fails at startup with that value. Before you upgrade a deployment that has sign-in turned on with the shared audience:

1. Register the separate API at your IdP and assign roles on it.
1. Set `dataplane.config.auth.oidc.audience` to the new API identifier.
1. Upgrade the chart.

MCP clients then need to sign in again to receive tokens for the new audience.

### Grant signed-in users access

Grant signed-in users access in either way:

- Map an IdP group to the `gateway_user` role. The role grants `use` on every Gateway in the tenant.
- Assign Identity Service subject grants to individual users for selected Gateways, with `POST /v1/subject-grants/apply` on the Identity Service. See [subject grants](https://redis.io/docs/latest/operate/iris/identity-service/authentication#subject-grants) for the request. A subject grant names the IdP's issuer, the user's `user_id_claim` value, and the same product, resource type, Gateway ID, and `use` action as an agent-key grant.

A specific subject grant cannot narrow the all-Gateway role, and removing a subject grant does not remove access that a role gives. To restrict a user to selected Gateways, don't map them to `gateway_user`.



## Rotate credentials

See [Operations](https://redis.io/docs/latest/operate/iris/context-gateway/self-managed/operations#rotate-credentials).