Connect an AWS role changedclaude-tag/admins/federated-access/aws
Nearest release: v2.1.290, published under an hour before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 5 Oct 2026 18:54 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 22 Oct 2026 18:07 UTC.
Upstream edited
Recorded here
Lines+15added
Lines−15removed
From line
10
where the diff opens
First seen
10 Sep 2026
this site's first read of the page
Recorded edits12to this page, all time
The whole hunk
from line 10, old and new numbered
/
from line 10
1010>
1111> AWS roles are connected on the [**Federated agent access**](https://claude.ai/admin-settings/claude-tag/federated-cloud-access) page, under **Claude Tag** in the admin settings sidebar. Use its **Cloud roles** section. Connecting a role needs an organization Owner, or an admin with full Claude Tag management permission.
1212
13With an AWS role connection, Claude signs in to an IAM role in your AWS account with a short-lived identity token and calls AWS with the role's permissions. No access key is stored in Claude. The token names your organization and the [agent](/docs/claude-tag/concepts/agent-identity) making the request (Claude's identity in one Slack channel), and your role's trust policy decides which tokens to accept. If someone else manages your AWS account, give them the values from the console and the trust policy below; the console steps need an organization Owner or a [Claude Tag admin](/docs/claude-tag/admins/restrict-access#delegate-claude-tag-administration).
13With an AWS role connection, Claude signs in to an IAM role in your AWS account with a short-lived identity token and calls AWS with the role's permissions. No access key is stored in Claude. The token names your organization and the [agent](/docs/claude-tag/concepts/agent-identity.md) making the request (Claude's identity in one Slack channel), and your role's trust policy decides which tokens to accept. If someone else manages your AWS account, give them the values from the console and the trust policy below; the console steps need an organization Owner or a [Claude Tag admin](/docs/claude-tag/admins/restrict-access.md#delegate-claude-tag-administration).
1414
1515## Before you begin
1616
from line 63
6363}
6464```
6565
66Keep both conditions. Because every organization's tokens come from the same issuer with the same audience, the `sub` condition is the only thing that limits the role to your organization; see [Authorize on the subject](/docs/claude-tag/admins/federated-access/token-reference#authorize-on-the-subject). The wildcard replaces only the agent ID at the end. Never put a wildcard before `/agent/`. `StringEquals` on the prefix never matches, so keep the prefix condition under `StringLike`. Both condition keys start with `identity.anthropic.com/agents:` (the issuer without `https://`).
66Keep both conditions. Because every organization's tokens come from the same issuer with the same audience, the `sub` condition is the only thing that limits the role to your organization; see [Authorize on the subject](/docs/claude-tag/admins/federated-access/token-reference.md#authorize-on-the-subject). The wildcard replaces only the agent ID at the end. Never put a wildcard before `/agent/`. `StringEquals` on the prefix never matches, so keep the prefix condition under `StringLike`. Both condition keys start with `identity.anthropic.com/agents:` (the issuer without `https://`).
6767
6868The prefix condition is the minimum, and it admits every agent in your organization. Where your use case allows, pin the role to specific agents instead, which is the strongest form: use `StringEquals` on `identity.anthropic.com/agents:sub` with one full subject, or a JSON array of full subjects. The console doesn't show agent IDs, so you learn a subject from CloudTrail after a first sign-in under the prefix condition. Agent IDs change when a Slack channel is deleted and recreated, so update the policy when that happens.
6969
from line 83
8383
8484**3. Narrow the allowed AWS hosts**
8585
86The **Allowed AWS hosts** field starts with `*.amazonaws.com`, which lets Claude use the role with any AWS service. Keep that entry for the first verification, then narrow the list to the hosts Claude needs from the connection's [**Edit connection** dialog](/docs/claude-tag/admins/add-connections#set-allowed-websites), which you open from the connection's row on the **Connectors** tab; see [Manage federated connections on the Connectors tab](/docs/claude-tag/admins/federated-access/overview#manage-federated-connections-on-the-connectors-tab). A wildcard covers subdomains only: `*.s3.us-west-2.amazonaws.com` matches `example-reports.s3.us-west-2.amazonaws.com` but not `s3.us-west-2.amazonaws.com`. The AWS CLI and SDKs use both forms for S3, so list both the plain host and the wildcard for each region, and for `us-east-1` also `*.s3.amazonaws.com`, the older global S3 address some tools still use there. Every host must end in `.amazonaws.com`. The sign-in itself goes to the AWS Security Token Service (STS) from Anthropic's side and doesn't need an entry here.
86The **Allowed AWS hosts** field starts with `*.amazonaws.com`, which lets Claude use the role with any AWS service. Keep that entry for the first verification, then narrow the list to the hosts Claude needs from the connection's [**Edit connection** dialog](/docs/claude-tag/admins/add-connections.md#set-allowed-websites), which you open from the connection's row on the **Connectors** tab; see [Manage federated connections on the Connectors tab](/docs/claude-tag/admins/federated-access/overview#manage-federated-connections-on-the-connectors-tab). A wildcard covers subdomains only: `*.s3.us-west-2.amazonaws.com` matches `example-reports.s3.us-west-2.amazonaws.com` but not `s3.us-west-2.amazonaws.com`. The AWS CLI and SDKs use both forms for S3, so list both the plain host and the wildcard for each region, and for `us-east-1` also `*.s3.amazonaws.com`, the older global S3 address some tools still use there. Every host must end in `.amazonaws.com`. The sign-in itself goes to the AWS Security Token Service (STS) from Anthropic's side and doesn't need an entry here.
8787
8888**4. Confirm the trust policy**
8989
from line 91
9191
9292**5. Choose a bundle and connect**
9393
94Choose a bundle from the **Access bundle** list, or create one: click **New bundle** if the dialog shows it, enter a **Bundle name**, and click **Create bundle**. Then click **Connect role**. This creates a [connection](/docs/claude-tag/admins/add-connections) in that bundle, with the hosts you entered under **Allowed hosts**. A role can be connected in one bundle only, and it applies wherever that bundle applies.
94Choose a bundle from the **Access bundle** list, or create one: click **New bundle** if the dialog shows it, enter a **Bundle name**, and click **Create bundle**. Then click **Connect role**. This creates a [connection](/docs/claude-tag/admins/add-connections.md) in that bundle, with the hosts you entered under **Allowed hosts**. A role can be connected in one bundle only, and it applies wherever that bundle applies.
9595
9696The **Cloud roles** table has **Role**, **Access bundle**, **Allowed hosts**, **Added**, and **Actions** columns. Each connection's name appears under **Role** with the role's ARN and an **AWS role** chip beneath it, and **Check trust policy** and **Remove** are under **Actions**.
9797
from line 99
9999
100100Claude uses the role in the channels where its bundle applies. A bundle you created in the connect dialog applies nowhere until you choose places; see [Manage federated connections on the Connectors tab](/docs/claude-tag/admins/federated-access/overview#manage-federated-connections-on-the-connectors-tab).
101101
102Claude also needs to know what the role is for. Add a line like this to the scope's [custom instructions](/docs/claude-tag/admins/attach-to-scope#add-custom-instructions):
102Claude also needs to know what the role is for. Add a line like this to the scope's [custom instructions](/docs/claude-tag/admins/attach-to-scope.md#add-custom-instructions):
103103
104104```text wrap theme={null}
105105Use the AWS CLI to read the S3 bucket example-reports in us-west-2. AWS access is already set up.
106106```
107107
108Claude calls AWS with `curl`, an AWS SDK, or the AWS CLI, as with an [AWS SigV4 credential](/docs/claude-tag/admins/connections/custom#aws-sigv4). [Agent Proxy](/docs/claude-tag/concepts/agent-identity#agent-proxy) signs each request at the network boundary with the role's temporary credentials, so the sandbox never holds them.
108Claude calls AWS with `curl`, an AWS SDK, or the AWS CLI, as with an [AWS SigV4 credential](/docs/claude-tag/admins/connections/custom.md#aws-sigv4). [Agent Proxy](/docs/claude-tag/concepts/agent-identity.md#agent-proxy) signs each request at the network boundary with the role's temporary credentials, so the sandbox never holds them.
109109
110110New threads pick up the connection on their own. In a thread already running, ask Claude to use AWS. If Claude still can't, send [`@Claude !restart`](/docs/claude-tag/users/commands#restart-a-stuck-or-wrong-context-session) in that thread. Claude then continues from a fresh session with your organization's current configuration.
111111
112112## Verify the connection
113113
114[Federated connections](/docs/claude-tag/admins/federated-access/limits#where-federated-connections-work) work only in agent sessions, such as a Slack channel. A test from a personal session, such as a direct message with `@Claude`, won't work.
114[Federated connections](/docs/claude-tag/admins/federated-access/limits.md#where-federated-connections-work) work only in agent sessions, such as a Slack channel. A test from a personal session, such as a direct message with `@Claude`, won't work.
115115
116116In a channel where the role's connection applies, start a new thread and ask Claude to run a connectivity check. The check is Claude's own request to `sts.amazonaws.com`, so keep `*.amazonaws.com` under the connection's **Allowed hosts** for this check, or add `sts.amazonaws.com` if you already narrowed the list. The sign-in itself needs no entry there. After the check passes, remove `sts.amazonaws.com` again if you added it, or narrow the wildcard. While it is listed, Claude can send any STS request signed with the role's credentials. If the role is allowed to assume another role, the credentials AWS returns are readable in Claude's sandbox. The call needs no permissions policy on the role. Send Claude this prompt:
117117
from line 132
132132* `AccessDenied` on the sign-in means the trust policy didn't accept the token. Check the `sub` condition and the condition-key prefix.
133133* A denied action after a successful sign-in means AWS denied the action. Check the role's permissions policy first, then any bucket policy, permissions boundary, or service control policy.
134134
135See [Troubleshoot federated agent access](/docs/claude-tag/admins/federated-access/troubleshooting) for the errors Claude shows.
135See [Troubleshoot federated agent access](/docs/claude-tag/admins/federated-access/troubleshooting.md) for the errors Claude shows.
136136
137137To disconnect a role, click **Remove** in the role's row of the **Cloud roles** table, then **Remove role** in the confirmation. Claude stops using the role within about a minute, in existing threads as well as new ones, and the connection is removed from its bundle. Credentials from an earlier sign-in stay valid in AWS until they expire, within 1 hour; they're held only by Agent Proxy, never by Claude's sandbox.
138138
from line 143
143143* **"This role is already connected in the bundle"**: the role already has its one connection. Apply that bundle where you need the role instead; see [Manage federated connections on the Connectors tab](/docs/claude-tag/admins/federated-access/overview#manage-federated-connections-on-the-connectors-tab).
144144* **"Enter a role ARN like `arn:aws:iam::123456789012:role/ClaudeTag`"**: the **Role ARN** field rejected the value, most often because the ARN is in the AWS GovCloud (US) or AWS China partition, which can't be connected.
145145
146For other dialog messages, see [Troubleshoot federated agent access](/docs/claude-tag/admins/federated-access/troubleshooting).
146For other dialog messages, see [Troubleshoot federated agent access](/docs/claude-tag/admins/federated-access/troubleshooting.md).
147147
148If Claude reports HTTP 403 with a reason that starts with [`request blocked: federated connections work only in agent sessions (such as a Slack channel), not in personal sessions (such as a direct message)`](/docs/claude-tag/admins/federated-access/troubleshooting#request-blocked-federated-connections-work-only-in-agent-sessions-such-as-a-slack-channel--not-in-personal-sessions-such-as-a-direct-message), the request came from a personal session, such as a direct message with `@Claude`. A personal session runs under a person's own account. [Federated connections](/docs/claude-tag/admins/federated-access/limits#where-federated-connections-work) work only in agent sessions, so test again from a new thread in a Slack channel where the connection [applies](/docs/claude-tag/admins/attach-to-scope#how-scopes-inherit).
148If Claude reports HTTP 403 with a reason that starts with [`request blocked: federated connections work only in agent sessions (such as a Slack channel), not in personal sessions (such as a direct message)`](/docs/claude-tag/admins/federated-access/troubleshooting#request-blocked-federated-connections-work-only-in-agent-sessions-such-as-a-slack-channel--not-in-personal-sessions-such-as-a-direct-message), the request came from a personal session, such as a direct message with `@Claude`. A personal session runs under a person's own account. [Federated connections](/docs/claude-tag/admins/federated-access/limits.md#where-federated-connections-work) work only in agent sessions, so test again from a new thread in a Slack channel where the connection [applies](/docs/claude-tag/admins/attach-to-scope.md#how-scopes-inherit).
149149
150150## Related resources
151151
152* [Give Claude access](/docs/claude-tag/admins/add-connections): the bundle and connection model
153* [Attach a bundle to a scope](/docs/claude-tag/admins/attach-to-scope): where a role connection applies
154* [Identity token reference](/docs/claude-tag/admins/federated-access/token-reference): every claim in the token, lifetimes, and key rotation
155* [Troubleshoot federated agent access](/docs/claude-tag/admins/federated-access/troubleshooting): console and runtime errors for every connection type
156* [AWS SigV4 credential](/docs/claude-tag/admins/connections/custom#aws-sigv4): the stored-key alternative, and how Claude signs AWS requests
152* [Give Claude access](/docs/claude-tag/admins/add-connections.md): the bundle and connection model
153* [Attach a bundle to a scope](/docs/claude-tag/admins/attach-to-scope.md): where a role connection applies
154* [Identity token reference](/docs/claude-tag/admins/federated-access/token-reference.md): every claim in the token, lifetimes, and key rotation
155* [Troubleshoot federated agent access](/docs/claude-tag/admins/federated-access/troubleshooting.md): console and runtime errors for every connection type
156* [AWS SigV4 credential](/docs/claude-tag/admins/connections/custom.md#aws-sigv4): the stored-key alternative, and how Claude signs AWS requests
157157
No line in this hunk matches that.