Authentication and authorization

Configure Context Gateway Control Plane credentials, agent-key grants, and identity provider sign-in for agents.

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:

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 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.
  2. Set dataplane.config.auth.oidc.audience to the new API identifier.
  3. 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 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.

RATE THIS PAGE
Back to top ↑