From f641bcae46ace412d288bb187327f2b1237a7d20 Mon Sep 17 00:00:00 2001 From: aa-wong Date: Mon, 19 Oct 2026 12:44:12 -0700 Subject: [PATCH 1/2] docs: document workload identity in the Access Hub and connecting Claude Tag channels --- .../guides/claude-tag-gateway-endpoint.mdx | 4 + .../guides/claude-tag-workload-identity.mdx | 126 ++++++++++++++++++ .../identity/agents/workload-identity.mdx | 111 +++++++++++---- 3 files changed, 213 insertions(+), 28 deletions(-) create mode 100644 docs/ai-control-plane/guides/claude-tag-workload-identity.mdx diff --git a/docs/ai-control-plane/guides/claude-tag-gateway-endpoint.mdx b/docs/ai-control-plane/guides/claude-tag-gateway-endpoint.mdx index 26934def..8a91b843 100644 --- a/docs/ai-control-plane/guides/claude-tag-gateway-endpoint.mdx +++ b/docs/ai-control-plane/guides/claude-tag-gateway-endpoint.mdx @@ -21,6 +21,10 @@ Routing Claude Tag through a single [gateway endpoint](/docs/ai-control-plane/mc - [How user-scoped permissions work](#how-user-scoped-permissions-work) - [Controlling read scope expansion](#control-read-scope-expansion) + + This guide runs every tool call as the person who mentioned Claude. To have channels act as a shared Speakeasy agent with its own policy and no per-person sign-in, follow [Connect Claude Tag channels with workload identity](/docs/ai-control-plane/guides/claude-tag-workload-identity) instead. + + ## Prerequisites - A gateway endpoint with the MCP servers Claude Tag should reach. To create one, follow [Permission a Claude connector with a gateway endpoint](/docs/ai-control-plane/guides/claude-connector-gateway-endpoint). diff --git a/docs/ai-control-plane/guides/claude-tag-workload-identity.mdx b/docs/ai-control-plane/guides/claude-tag-workload-identity.mdx new file mode 100644 index 00000000..89824941 --- /dev/null +++ b/docs/ai-control-plane/guides/claude-tag-workload-identity.mdx @@ -0,0 +1,126 @@ +--- +title: "Connect Claude Tag channels with workload identity" +description: "Let Claude Tag call MCP servers from Slack channels as an agent, with no stored secret, by trusting Anthropic's agent tokens in the Access Hub and connecting Speakeasy as a Claude Tag authorization server." +guideCategory: "Governance" +--- + +import { Callout } from "@/mdx/components"; + +[Claude Tag](https://claude.com/docs/claude-tag/admins/setup-overview) brings Claude into Slack. In a channel, Claude Tag acts as a channel agent rather than as the person who mentioned it. With [federated access](https://claude.com/docs/claude-tag/admins/federated-access/authorization-server), Anthropic gives each channel agent a short-lived identity token, and Claude Tag exchanges it at an authorization server for an access token to call MCP servers. + +Speakeasy can be that authorization server. Each Claude Tag channel then signs in with [workload identity](/docs/ai-control-plane/identity/agents/workload-identity), acts as a Speakeasy agent chosen for it, and needs no stored secret. + + + To have Claude Tag call tools as the person who mentioned it, with their own credentials, follow [Roll out Claude Tag with a gateway endpoint](/docs/ai-control-plane/guides/claude-tag-gateway-endpoint) instead. Use this guide when channels should act as a shared agent with its own policy. + + +This guide covers: + +- [How the connection works](#how-the-connection-works) +- [Prerequisites](#prerequisites) +- [Start the guided setup](#start-the-guided-setup) +- [Enter the Anthropic organization](#enter-the-anthropic-organization) +- [Choose an agent](#choose-an-agent) +- [Connect the authorization server in Claude](#connect-the-authorization-server-in-claude) +- [Add the server to a bundle](#add-the-server-to-a-bundle) +- [Test from a channel](#test-from-a-channel) +- [Manage and revoke access](#manage-and-revoke-access) + +## How the connection works + +When someone mentions Claude in a channel thread and Claude needs an MCP tool: + +- Anthropic issues a token for the channel's agent, signed by `https://identity.anthropic.com/agents`. Its subject has the form `wimse://identity.anthropic.com/org/ORG_ID/agent/AGENT_ID`, with one agent per channel. +- Claude Tag posts the token to the Speakeasy token endpoint. +- Speakeasy checks the signature and matches the subject against the Claude Tag access rule in the Access Hub. The rule covers every agent in one Anthropic organization. +- Speakeasy returns an access token valid for 15 minutes. Claude Tag sends it on MCP requests and exchanges a new token when it expires. + +Each channel signs in under its own subject, so its sessions are listed and revocable separately. Every channel acts as the same Speakeasy agent and can do only what that agent's policy allows. + +## Prerequisites + +- In the Claude organization: Claude Tag with federated access, and an Owner or an admin with full Claude Tag management permission. +- In Speakeasy: `workload:write`, which the Admin role holds by default. +- An agent whose policy allows the MCP servers and tools Claude Tag should use. To create one, see [Authorizing agents](/docs/ai-control-plane/identity/agents/authorizing-agents#create-an-agent). +- MCP servers on a Speakeasy host. A server on a custom domain signs clients in at its own origin, which Claude Tag can't use, because Claude Tag requires the token endpoint to be on a different host from the servers it calls. +- A Speakeasy authorization server in shared mode for the organization or project. If the guided setup reports that no token endpoint is available, contact Speakeasy to enable one. + +## Start the guided setup + +Open the [Access Hub](https://ai.speakeasy.com/@self/access-hub) under **Secure > Access Hub**. On the **Catalog** tab, select **Claude Tag**, then **Set one up**. + +The **Set up Claude Tag** panel opens. Its first step links to the Claude Tag **Federated access** settings. Keep them open in another tab, because later steps switch between the two. + +## Enter the Anthropic organization + +Enter the **Anthropic organization ID**. It's at the bottom of the Claude organization settings, labeled **Organization ID**. The Claude Tag console shows the same value as **Tenant ID**. + +The panel shows the access rule it will create: + +```text +wimse://identity.anthropic.com/org/ORG_ID/agent/* +``` + +The rule admits every Claude Tag channel in that Anthropic organization, including channels created later. That's safe because Anthropic mints the agent ID at the end of the subject, and no caller can choose it. Speakeasy already knows Anthropic's issuer and signing keys, so there's nothing else to enter. + +## Choose an agent + +Choose the agent every Claude Tag channel acts as, optionally add tags, and select **Connect Claude Tag**. Speakeasy trusts Anthropic's issuer and saves the access rule with that agent. + +## Connect the authorization server in Claude + +In the Claude Tag **Federated access** settings, under **Authorization servers**, select **Connect an authorization server**. Copy each value from the Speakeasy panel into the matching field: + +- **Token endpoint**: the Speakeasy token endpoint shown in the panel. +- **Issuer URL**: the Speakeasy issuer URL shown in the panel. Claude marks this field optional, but fill it in. Claude Tag requests its token for this issuer, and Speakeasy refuses tokens issued for anything else. + +If the organization has more than one shared authorization server, choose the one that serves the MCP servers Claude Tag should reach before copying. + +Leave the values under **Set your authorization server to accept these values** as they are. Speakeasy already accepts Anthropic's issuer and the organization's subject prefix. + +Select the checkbox confirming that the authorization server checks each token's subject belongs to the organization. The Speakeasy access rule is that check. Then select **Register server**. + +## Add the server to a bundle + +Claude opens **Add authorization server to a bundle**. Fill in: + +- **Resource**: leave empty. Claude Tag's access token then works at every MCP server of the authorization server that the agent may connect to. +- **Scope**: leave empty. +- **Allowed API hosts**: the MCP host shown in the Speakeasy panel. If Claude also asks for API paths, list the path of each MCP server Claude Tag should use, such as `/mcp/SERVER_SLUG`. +- **Access bundle**: the bundle assigned to the channels Claude Tag should work in, or a new one created with **New bundle**. + +Select **Connect server**. + +## Test from a channel + +In a Slack channel where the bundle applies, start a new thread, mention Claude, and ask it to list the MCP server's tools. + + + Federated connections work only in channel threads. A direct message with Claude fails with `request blocked: federated connections work only in agent sessions`. + + +Each channel that signs in appears on [MCP Sessions](/docs/ai-control-plane/mcp-gateway/access/clients-and-sessions#organization-wide-view) under Anthropic's issuer and the channel's own subject. + +If the exchange fails, check: + +- The Anthropic organization ID matches the **Tenant ID** in the Claude Tag console. +- The **Issuer URL** in Claude matches the Speakeasy issuer URL exactly. +- The MCP server is on a Speakeasy host and attached to the authorization server whose values were copied. +- The agent's policy allows the server, and the agent owner still has access to it. + +Speakeasy returns the same `invalid_grant` error for every refusal, and Claude Tag reads only the error code, so these checks are the quickest way to find the cause. + +## Manage and revoke access + +After setup, the **Claude Tag** catalog entry in the Access Hub reads **Connected** and lists the access rule. From there: + +- To have one channel act as a different agent, select **Allow access** and add a rule for that channel's exact subject. An exact rule takes priority over the wildcard. Agent IDs appear in each channel's sessions on **MCP Sessions**. +- To change the agent for every channel, select **⋮ > Edit** on the wildcard rule. +- To disconnect Claude Tag, select **⋮ > Remove** on the rule, then remove the authorization server in the Claude Tag settings. Removing it there also frees a gateway slot, since a Claude organization can register at most five. + +Removing a rule stops new exchanges but doesn't end sessions already issued. To cut off a channel immediately, also revoke its sessions on **MCP Sessions**. + +## Next steps + +- Read [Workload identity](/docs/ai-control-plane/identity/agents/workload-identity) for how trusted platforms, access rules, and token exchange work for other platforms. +- Read [Authorizing agents](/docs/ai-control-plane/identity/agents/authorizing-agents) to scope the agent Claude Tag acts as. diff --git a/docs/ai-control-plane/identity/agents/workload-identity.mdx b/docs/ai-control-plane/identity/agents/workload-identity.mdx index d813d87f..4225c340 100644 --- a/docs/ai-control-plane/identity/agents/workload-identity.mdx +++ b/docs/ai-control-plane/identity/agents/workload-identity.mdx @@ -1,16 +1,16 @@ --- title: Workload identity -description: "Let CI jobs, Kubernetes pods, and other workloads connect as an agent by exchanging the identity token their own platform issues, with no stored secret. Set up trusted issuers and admitted subjects in the Access Hub." +description: "Let CI jobs, Kubernetes pods, Claude Tag channels, and other workloads connect as an agent by exchanging the identity token their own platform issues, with no stored secret. Set up trusted platforms and access rules in the Access Hub." --- import { Callout } from "@/mdx/components"; -Workload identity lets a CI job, Kubernetes pod, or other workload connect as an agent without a stored secret. The workload presents the identity token its own platform already issues, such as a GitHub Actions OIDC token, and exchanges it for a short-lived access token. The workload acts as its agent and inherits that agent's permissions in full. +Workload identity lets a CI job, Kubernetes pod, Claude Tag channel, or other workload connect to MCP servers without a stored secret. The workload presents the identity token its own platform already issues, such as a GitHub Actions OIDC token, and exchanges it for a short-lived Speakeasy access token. The workload then acts as the agent assigned to it and inherits that agent's policy in full. ## Access requirements - Any member who can [create an agent](/docs/ai-control-plane/identity/agents/authorizing-agents#create-an-agent) can give it a workload credential. Managing trusted platforms in the Access Hub requires `workload:read` and `workload:write`, which only the Admin role holds by default. + Managing the Access Hub requires `workload:read` to view it and `workload:write` to change it. Only the Admin role holds both by default. Choosing an agent for a workload requires no permission on the agent itself, so grant `workload:write` only to people trusted to hand any agent's access to a machine. ## When to use workload identity @@ -19,48 +19,103 @@ Choose the credential that fits where the agent runs: | | API key | Workload identity | | --- | --- | --- | -| Runs in | Any runtime | Runtimes whose platform issues identity tokens, such as GitHub Actions, Kubernetes, SPIFFE, and GCP | +| Runs in | Any runtime | Runtimes whose platform issues identity tokens, such as Claude Tag, GitHub Actions, Kubernetes, and SPIFFE | | Secret to store | Yes, the key | None | -| Token lifetime | Up to one year, revocable | 15 minutes or one hour, with no refresh token | -| Servers with per-user OAuth | Supported | Not supported | +| Token lifetime | Up to one year, revocable | 15 minutes, with no refresh token | +| Servers with per-user OAuth | The key owner's connected account | The agent owner's connected account | -Workload identity removes the risk of a leaked long-lived key. Use an API key for laptops, hosted agents, and any runtime without a platform identity token. +Workload identity removes the risk of a leaked long-lived key. Use an [API key](/docs/ai-control-plane/identity/agents/authorizing-agents#create-an-agent) for laptops, hosted agents, and any runtime without a platform identity token. -## Set up workload identity +## How it works -Start the [**New agent identity**](/docs/ai-control-plane/identity/agents/authorizing-agents#create-an-agent) wizard as for any agent. In the **Credential** step, choose **Workload identity** and fill in the settings that appear. +Three pieces of configuration decide whether a workload gets in and what it can do: -![The Credential step with Workload identity selected for GitHub Actions, showing the issuer and the repository claim matcher](/assets/docs/ai-control-plane/identity/agent-credential-workload.webp) +- **Trusted platform**: an issuer whose tokens Speakeasy verifies, identified by its issuer URL and the URL of its signing keys (JWKS URI). Trusting a platform admits nothing on its own. +- **Access rule**: a token subject, the `sub` claim, that is allowed to sign in, and the agent it acts as. A rule matches one subject exactly, or every subject that starts with a prefix when it ends in `*`. +- **Agent**: supplies the whole policy the workload acts under. The workload holds no permissions of its own, and it can reach only what both the agent's policy and the agent owner's current permissions allow. If the owner loses access to a server, the workload loses it on its next request. -- **Platform**: the platform the workload runs on, or **Custom OIDC** for any other OpenID Connect issuer. -- **Issuer**: the platform's token issuer URL. The wizard fills it in for known platforms and checks that its signing keys can be discovered. -- **Claim matchers**: the claims a token must carry to be admitted, such as `repository` and `ref` for GitHub Actions. A token is accepted only when it matches every claim. These matchers are the security boundary: a platform such as GitHub Actions signs tokens for every customer's jobs, so a valid signature alone proves nothing. Match as narrowly as possible, for example on a specific repository and branch. -- **Session duration**: **15 min** or **1 hour**. Shorter sessions limit how long a stolen token stays useful. +A workload is admitted only when its token is signed by a trusted platform and its subject matches an access rule under that platform. Platforms such as Anthropic, GitHub, and Google sign tokens for all of their customers, so a valid signature alone proves nothing. The access rule is the security boundary. -Select **Create agent**. +The workload sends its platform token to the token endpoint of a Speakeasy authorization server and receives an access token valid for 15 minutes. It sends that access token as a bearer token on MCP requests. There's no refresh token: when the access token expires, the workload exchanges a fresh platform token. + +## Manage the Access Hub + +The [Access Hub](https://ai.speakeasy.com/@self/access-hub) lists the platforms the organization trusts and the access rules under each one. Open it from the organization sidebar under **Secure > Access Hub**. Trust applies to MCP servers in every project. + +The Access Hub has two tabs: + +- **Catalog**: platforms Speakeasy has verified, with their issuer and signing keys already filled in. Selecting one opens a guided setup that asks only for what differs per organization. To connect Claude Tag, follow [Connect Claude Tag channels with workload identity](/docs/ai-control-plane/guides/claude-tag-workload-identity). +- **Custom**: any other platform, registered by hand. + +### Register a custom platform + +On the **Custom** tab, select **Register new access** and fill in: + +- **Name**: how the platform is labeled in the Access Hub. Not used for matching. +- **Issuer**: the value the token's `iss` claim must carry. It must be an HTTPS URL. Speakeasy stores it exactly as entered, so copy it from the platform's documentation or discovery document. +- **JWKS URI**: where the platform publishes its signing keys. It must be an HTTPS URL. +- **Description** and **Tags**: optional, for finding the platform later. + +Select **Register**. The issuer is fixed once registered. To trust a different issuer, register it as a new platform. + +### Allow access + +Open the platform, select **Allow access**, and fill in: + +- **Subject**: the `sub` claim to admit, compared exactly as entered. To admit every subject that starts with the same text, end the subject with `*`. +- **Agent**: the agent the workload acts as. Choose the most narrowly scoped agent that can do the job. +- **Label** and **Tags**: optional. A label helps when a subject is opaque, such as a numeric service account ID. + +Select **Allow access**. + + + A rule ending in `*` admits every subject that starts with the text before it, including subjects created later. That's safe when the platform mints the varying part, as Anthropic does with agent IDs in `wimse://identity.anthropic.com/org/ORG_ID/agent/*`. It isn't safe when the caller influences the subject. For example, `repo:acme/deploy:*` on GitHub Actions admits every branch, so anyone who can push a branch gets in. + + +A rule for an exact subject takes priority over a wildcard rule that also matches it, and a longer wildcard takes priority over a shorter one. This makes it possible to admit a whole fleet under one agent and give a single workload a different one. + +### Change or remove access + +Select the **⋮** menu on a rule to edit its agent, label, or tags, or to remove it. The subject is fixed once allowed. To stop trusting a platform and every rule under it, select **Stop trusting** on the platform. + +Removing access doesn't end sessions already issued. To stop a workload immediately, also revoke its sessions on [MCP Sessions](/docs/ai-control-plane/mcp-gateway/access/clients-and-sessions#organization-wide-view), or [suspend the agent](/docs/ai-control-plane/identity/agents#suspend-revoke-or-delete-an-agent). Every change to platforms and access rules is recorded in [Audit Logs](/docs/ai-control-plane/org-admin/audit-logs). ## Exchange a platform token -The **Provision** step shows a snippet tailored to the agent's platform, with the exact audience and token endpoint filled in. Copy it into the workload's job or startup script. +A workload exchanges its token at the token endpoint of a shared Speakeasy authorization server, which serves every MCP server attached to it. Organization admins find each authorization server's issuer URL and token endpoint under **Speakeasy Authorization Servers** in the organization settings. + + + Workload sign-in needs an authorization server in shared mode. If none is listed, contact Speakeasy to enable one for the organization or a project. + -The snippet requests an identity token from the platform, posts it to the agent's token endpoint using the OAuth JWT bearer grant, and sends the returned access token as a bearer token on MCP requests. For GitHub Actions, the workflow needs the `id-token: write` permission. No client ID or secret is involved. +Request a token from the platform with its audience set to the authorization server's issuer URL. Then post it to the token endpoint using the OAuth JWT bearer grant: -The access token can't be refreshed. When it expires, the workload requests a fresh platform token and exchanges it again. Use a fresh platform token for each exchange, because a token with a `jti` claim is accepted only once. +```bash +curl https://AUTHENTICATION_HOST/oauth/usi/ISSUER_ID/token \ + --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \ + --data-urlencode "assertion=$PLATFORM_TOKEN" \ + --data-urlencode "resource=https://MCP_HOST/mcp/SERVER_SLUG" +``` -## Test an assertion +No client ID or secret is involved. The `resource` parameter is optional: -To check a token before the workload runs, use **Test an assertion** in the **Provision** step. Paste a sample JWT from the workload and select **Test** to see whether it would be accepted and, if not, why. At runtime, every refusal returns the same `invalid_grant` error so callers can't probe the trust policy, which makes this test the quickest way to debug claim matchers. +- With `resource`, the access token works only at that MCP server. +- Without it, the access token works at every MCP server of the authorization server that the agent may connect to. -## Per-user OAuth servers +A successful exchange returns the access token: -Servers that use per-user OAuth reject workload sessions, because a workload has no person to connect an upstream account. When the agent includes such a server, the wizard shows a warning. Use an API key for that agent, or remove those servers. +```json +{ + "access_token": "eyJ...", + "token_type": "Bearer", + "expires_in": 900 +} +``` -## Manage trusted platforms in the Access Hub +Send it as `Authorization: Bearer ACCESS_TOKEN` on MCP requests. When it expires or is revoked, the MCP server answers `401` with `error="invalid_token"`, and the workload exchanges a fresh platform token. Use a new platform token for each exchange, because a token with a `jti` claim is accepted only once. -The [Access Hub](https://ai.speakeasy.com/@self/access-hub), under **Organization settings > Secure**, lists every issuer the organization trusts and the subjects admitted under each one. Trust applies to MCP servers in every project. +Every refusal returns the same `invalid_grant` error, so callers can't probe the trust policy. A `resource` that isn't an MCP server of the authorization server returns `invalid_target`. -- To trust a new issuer, select **Register new access** and enter its issuer URL and signing keys URL. Trusting an issuer admits nothing on its own. -- To admit a workload, open the issuer, select **Allow access**, enter the token subject, and choose the agent it acts as. End the subject with `*` to admit every subject that starts with the text before it. Use a prefix only when the issuer, not the caller, controls the varying part. -- To stop a workload, select **Remove** on its row, or **Stop trusting** to remove an issuer and every workload under it. +## Servers with per-user OAuth -Removing access doesn't end sessions already issued. To stop a workload immediately, also revoke its sessions on [MCP Sessions](/docs/ai-control-plane/mcp-gateway/access/clients-and-sessions#organization-wide-view), or [suspend the agent](/docs/ai-control-plane/identity/agents#suspend-revoke-or-delete-an-agent). Changes to the trust policy are recorded in [Audit Logs](/docs/ai-control-plane/org-admin/audit-logs). +Some MCP servers call an upstream service with each person's own connected account. A workload has no person behind it, so it uses the account connected by the owner of its assigned agent. If the owner hasn't connected an account for that service, calls to the server fail rather than fall back to another credential. From 0b1013a00a0b9b828cc258a11618e02c6ef38b60 Mon Sep 17 00:00:00 2001 From: aa-wong Date: Mon, 19 Oct 2026 12:44:31 -0700 Subject: [PATCH 2/2] docs: point agent credential steps at Access Hub access rules --- docs/ai-control-plane/identity/agents/authorizing-agents.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ai-control-plane/identity/agents/authorizing-agents.mdx b/docs/ai-control-plane/identity/agents/authorizing-agents.mdx index 0ea5a147..0298aef5 100644 --- a/docs/ai-control-plane/identity/agents/authorizing-agents.mdx +++ b/docs/ai-control-plane/identity/agents/authorizing-agents.mdx @@ -43,7 +43,7 @@ Select the MCP servers the agent can connect to. Each selected server grants `mc Choose how the agent proves who it is: - **API key** works in any runtime. The key is long-lived and can be rotated or revoked. API keys expire after 90 days by default and after one year at most. -- **Workload identity** suits CI jobs and Kubernetes pods. The workload exchanges the token its own platform already issues for a short-lived session, so no secret is stored. See [Workload identity](/docs/ai-control-plane/identity/agents/workload-identity). +- **Workload identity** suits CI jobs, Kubernetes pods, and Claude Tag channels. The workload exchanges the token its own platform already issues for a short-lived session, so no secret is stored. An access rule in the Access Hub assigns the workload to this agent. See [Workload identity](/docs/ai-control-plane/identity/agents/workload-identity). Select **Create agent**. The agent is created and the action is recorded in the organization audit log. @@ -87,7 +87,7 @@ When every check passes, a live feed shows the agent's calls as they arrive. If nothing arrives: -- A 401 means the credential was rejected. Run the setup again, or for a workload, check the issuer and claim matchers. +- A 401 means the credential was rejected. Run the setup again, or for a workload, check its platform and access rule in the Access Hub. - A 403 means the tool isn't granted. Check the server and tool selection. - No requests at all means the runtime isn't pointed at the gateway URL.