From 320208c9c4e53416bf704a619ce97ba895b3a1b2 Mon Sep 17 00:00:00 2001 From: Nitin Kanukolanu Date: Mon, 2 Nov 2026 12:10:07 -0500 Subject: [PATCH 1/3] docs(MOD-20266): give the Gateway data plane its own sign-in audience --- .../context-gateway/self-managed/authentication.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/content/operate/iris/context-gateway/self-managed/authentication.md b/content/operate/iris/context-gateway/self-managed/authentication.md index 408e618675..c19a985217 100644 --- a/content/operate/iris/context-gateway/self-managed/authentication.md +++ b/content/operate/iris/context-gateway/self-managed/authentication.md @@ -65,13 +65,25 @@ Set these keys under `dataplane.config.auth.oidc`: | --- | --- | | `enabled` | `true` | | `issuer` | Your IdP's issuer URL. | -| `audience` | Exactly one API identifier for the Data Plane, such as `api://redis-iris`. Tokens audienced at a Gateway's MCP URL are also accepted. | +| `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: From ff1333be054e1f0911e603acbb3618e13ab7d2d0 Mon Sep 17 00:00:00 2001 From: Nitin Kanukolanu Date: Mon, 2 Nov 2026 12:10:24 -0500 Subject: [PATCH 2/3] docs(MOD-20266): tell MCP clients the Gateway takes its own sign-in audience --- content/develop/ai/context-engine/context-gateway/mcp.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/develop/ai/context-engine/context-gateway/mcp.md b/content/develop/ai/context-engine/context-gateway/mcp.md index 3903e78904..fb2065e700 100644 --- a/content/develop/ai/context-engine/context-gateway/mcp.md +++ b/content/develop/ai/context-engine/context-gateway/mcp.md @@ -99,6 +99,8 @@ When the deployment turns on sign-in, an MCP client can use an access token from A request without a credential receives `401` and a `WWW-Authenticate` header that points to the Gateway's protected resource metadata. Clients that support MCP authorization read that document, find the IdP, and sign the user in. The IdP's token never reaches an Upstream. +The token must be issued for the Gateway's own API, not for the shared Iris audience that the Iris console uses. A token for the shared audience alone doesn't open a Gateway. + The signed-in user still needs a grant on the Gateway. See [Identity provider sign-in](/content/operate/iris/context-gateway/self-managed/authentication.md#identity-provider-sign-in). ## Troubleshoot the connection From 506122daeda14ed35749626ee33d603c359394f8 Mon Sep 17 00:00:00 2001 From: Nitin Kanukolanu Date: Mon, 2 Nov 2026 12:10:25 -0500 Subject: [PATCH 3/3] docs(MOD-20266): point the chart upgrade steps at the audience move --- content/operate/iris/context-gateway/self-managed/operations.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/operate/iris/context-gateway/self-managed/operations.md b/content/operate/iris/context-gateway/self-managed/operations.md index 23e2645ac1..1f08de5361 100644 --- a/content/operate/iris/context-gateway/self-managed/operations.md +++ b/content/operate/iris/context-gateway/self-managed/operations.md @@ -98,6 +98,8 @@ Update API clients to the unified `/iris/v1/context-gateway` routes and uppercas Update dashboards and alerts to the `iris_context_gateway_*` metrics. The previous metric names have no aliases. Review database updates and tool policies in [Turn the cache and compression on or off](/content/develop/ai/context-engine/context-gateway/manage-gateways.md#turn-the-cache-and-compression-on-or-off). +If MCP sign-in uses the shared `api://redis-iris` audience, the upgraded Data Plane refuses to start. Move it to an API of its own first, as [Upgrade from the shared audience](/content/operate/iris/context-gateway/self-managed/authentication.md#upgrade-from-the-shared-audience) describes. + ```bash helm upgrade gateway redis-ai/redis-context-gateway \ --version \