What this read moved
1–5 of 5claude-tag/admins/connections/custom Changed · +3 / -2 lines
from line 58
5858
5959* `service.region.amazonaws.com`
6060* S3 virtual-hosted-style endpoints, for example `my-bucket.s3.us-east-1.amazonaws.com`
61* The regionless hosts of global AWS services such as IAM, STS, and CloudFront
61* Service hostnames with extra parts before the service name, as long as the region is the last part before `amazonaws.com`, for example the Amazon ECR API host `api.ecr.us-east-1.amazonaws.com` or the host of an API Gateway invoke URL, `abc123.execute-api.us-east-1.amazonaws.com`
62* The regionless hosts of IAM, STS, S3, Route 53, CloudFront, Organizations, and Global Accelerator, for example `iam.amazonaws.com`, which Agent Proxy signs for `us-east-1`
6263
63Apart from S3 virtual-hosted-style endpoints, Agent Proxy can't read the service from a hostname that has extra parts before the service name, so requests to those hosts fail before reaching AWS. Examples include the host of an API Gateway invoke URL, such as `abc123.execute-api.us-east-1.amazonaws.com`, and the host of an Amazon Managed Workflows for Apache Airflow (MWAA) environment. The proxy also can't sign requests to an API Gateway custom domain or to a non-AWS API that uses Signature Version 4.
64Requests to other hostnames fail before reaching AWS. Agent Proxy can't sign a request to a hostname with no region for any other service, such as `ec2.amazonaws.com`, or to a hostname with the region before the service name, such as an OpenSearch domain endpoint (`my-domain.us-east-1.es.amazonaws.com`). It also can't sign requests to an API Gateway custom domain or to a non-AWS API that uses Signature Version 4.
6465
6566| Field | Value |
6667| :---------------- | :---------------------------------------------------------------------------------------------------------- |
claude-tag/admins/federated-access/aws Changed · +8 / -4 lines
from line 67
6767 </Step>
6868
6969 <Step title="Attach permissions">
70 Attach a least-privilege permissions policy to the role. For the check under [Verify the connection](#verify-the-connection), the role needs `s3:ListBucket` on the example bucket. Each sign-in gives Claude temporary credentials that last 1 hour, the AWS default. Claude doesn't ask for a different length, and the role's maximum session duration setting doesn't change this. To cut off access before they expire, use the role's **Revoke active sessions** option in IAM or change its permissions.
70 Attach a least-privilege permissions policy to the role for the work Claude will do. The check under [Verify the connection](#verify-the-connection) needs no permissions. Each sign-in gives Claude temporary credentials that last 1 hour, the AWS default. Claude doesn't ask for a different length, and the role's maximum session duration setting doesn't change this. To cut off access before they expire, use the role's **Revoke active sessions** option in IAM or change its permissions.
7171 </Step>
7272</Steps>
7373
from line 113
113113
114114## Verify the connection
115115
116In a channel whose workspace or channel has the bundle attached, start a new thread and ask Claude to make a small read (replace `example-reports` with a bucket the role can read):
116In a channel whose workspace or channel has the bundle attached, 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
118118```text wrap theme={null}
119@Claude list the objects in the S3 bucket example-reports and tell me how many there are.
119@Claude Connectivity check for this channel's AWS connection. Please run exactly:
120
121curl -sS -o /tmp/resp.txt -w '%{http_code}' 'https://sts.amazonaws.com/?Action=GetCallerIdentity&Version=2011-06-15'
122
123and tell me the HTTP status code it prints and, only if it is not 200, the first 200 characters of /tmp/resp.txt.
120124```
121125
122Then check CloudTrail in the AWS account for an `AssumeRoleWithWebIdentity` event on your role whose identity provider names `identity.anthropic.com/agents`. Claude signs in at the global STS endpoint, `sts.amazonaws.com`, so the event is recorded in the US East (N. Virginia) region; look there or in a multi-region trail, and allow a few minutes for it to appear. The role session name is an opaque ID for the Claude session that signed in. Claude may reuse one sign-in's credentials for most of the hour across threads in the same channel, so not every request produces a sign-in event. After AWS denies a request, Claude signs in again on the next one.
126A status of 200 means the sign-in worked. Then check CloudTrail in the AWS account for an `AssumeRoleWithWebIdentity` event on your role whose identity provider names `identity.anthropic.com/agents`. Claude signs in at the global STS endpoint, `sts.amazonaws.com`, so the event is recorded in the US East (N. Virginia) region; look there or in a multi-region trail, and allow a few minutes for it to appear. The role session name is an opaque ID for the Claude session that signed in. Claude may reuse one sign-in's credentials for most of the hour across threads in the same channel, so not every request produces a sign-in event. After AWS denies a request, Claude signs in again on the next one.
123127
124128If Claude reports that the request was refused, CloudTrail usually shows why.
125129
claude-tag/admins/federated-access/gcp Changed · +7 / -3 lines
from line 123
123123
124124## Verify the connection
125125
126In a channel whose workspace or channel has the bundle attached, start a new thread and ask Claude to make a small read (replace `example-reports` with a bucket the identity can read):
126In a channel whose workspace or channel has the bundle attached, start a new thread and ask Claude to run a connectivity check. The check reads a bucket's metadata, so the identity needs the `storage.buckets.get` permission on the bucket, and `storage.googleapis.com` must be under the connection's **Allowed hosts**. Send Claude this prompt, replacing `example-reports` with a bucket the identity can read:
127127
128128```text wrap theme={null}
129@Claude list the objects in the Cloud Storage bucket example-reports and tell me how many there are.
129@Claude Connectivity check for this channel's Google Cloud connection. Please run exactly:
130
131curl -sS -o /tmp/resp.txt -w '%{http_code}' https://storage.googleapis.com/storage/v1/b/example-reports
132
133and tell me the HTTP status code it prints, then paste the contents of /tmp/resp.txt.
130134```
131135
132Claude's reply tells you whether the read worked. For log evidence, enable Data Access audit logs beforehand for the Security Token Service API, for Cloud Storage, and, with a service account, for the IAM Service Account Credentials API, because Google keeps them off by default. The Security Token Service entry records each token exchange, with Google's reason when it refuses one, which Claude's own error doesn't show. The Cloud Storage entry shows the caller as the service account, or as the federated identity with the agent's full subject.
136A status of 200 with a JSON body whose `kind` is `storage#bucket` means the token exchange and the API call both worked. For log evidence, enable Data Access audit logs beforehand for the Security Token Service API, for Cloud Storage, and, with a service account, for the IAM Service Account Credentials API, because Google keeps them off by default. The Security Token Service entry records each token exchange, with Google's reason when it refuses one, which Claude's own error doesn't show. The Cloud Storage entry shows the caller as the service account, or as the federated identity with the agent's full subject.
133137
134138If Claude reports that the request was refused, the two most common causes are these:
135139
claude-tag/admins/federated-access/troubleshooting Changed · +59 / -37 lines
### Claude says Google credentials are not enabled for this organization ### Claude says a Google credential-minting endpoint was refused ### An AWS request fails after a successful sign-in ### request blocked: Google (gcp) credentials aren't enabled for this organization ### request blocked: this credential has restrict\_credential\_minting set, so Google's credential-minting endpoints are refused
from line 107
107107
108108To keep the gateway, register the same address again; see [Removing and reconnecting a gateway](#removing-and-reconnecting-a-gateway). To drop it, in **Access bundles**, open the bundle's **Credentials** tab, open the **⋮** menu on the connection's row, and choose **Delete**.
109109
110### request blocked: Google (gcp) credentials aren't enabled for this organization
110### Claude says Google credentials are not enabled for this organization
111111
112112**What you see**
113113
114Claude's request got HTTP 403 with this reason.
114Claude's request got HTTP 403 with the reason "request blocked: Google (gcp) credentials aren't enabled for this organization".
115115
116116**What it means**
117117
from line 121
121121
122122Contact your Anthropic account team with the details under [Contact Anthropic](#contact-anthropic).
123123
124### request blocked: this credential has restrict\_credential\_minting set, so Google's credential-minting endpoints are refused
124### Claude says a Google credential-minting endpoint was refused
125125
126126**What you see**
127127
128Claude's request got HTTP 403 with this reason.
128Claude's request got HTTP 403 with the reason "request blocked: this credential has restrict\_credential\_minting set, so Google's credential-minting endpoints are refused".
129129
130130**What it means**
131131
from line 185
185185
186186**What it means**
187187
188Most often, the system Claude's identity token was presented to refused the exchange. AWS refused `AssumeRoleWithWebIdentity`, Google Cloud's token exchange refused the token, or your authorization server answered the grant with an error. Claude's reply doesn't say why; your own logs do.
188Most often, the system Claude's identity token was presented to refused the exchange. AWS refused `AssumeRoleWithWebIdentity`, Google Cloud's token exchange refused the token, or your authorization server answered the grant with an error. Claude's reply doesn't say why; for a refused exchange, your own logs do.
189189
190190**How to resolve**
191191
192192Look up the refusal where it happened and fix the configuration it names.
193193
194| Connection | Where to look | Entry |
195| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------ |
196| AWS role | CloudTrail, the `AssumeRoleWithWebIdentity` event for the role | [AWS refuses AssumeRoleWithWebIdentity](#aws-refuses-assumerolewithwebidentity) |
197| Google Cloud identity | Cloud Audit Logs, the Security Token Service API entry for the token exchange and, if you named a service account, the IAM Service Account Credentials API entry | [Google Cloud refuses the token exchange](#google-cloud-refuses-the-token-exchange) |
198| Authorization server | Your server's log for the `POST` to the token endpoint | [Your authorization server rejects the grant](#your-authorization-server-rejects-the-grant) |
194| Connection | Where to look | Entry |
195| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
196| AWS role | CloudTrail, the `AssumeRoleWithWebIdentity` event for the role | [AWS refuses AssumeRoleWithWebIdentity](#aws-refuses-assumerolewithwebidentity) if the event failed. [An AWS request fails after a successful sign-in](#an-aws-request-fails-after-a-successful-sign-in) if the event succeeded, or there is no new event. |
197| Google Cloud identity | Cloud Audit Logs, the Security Token Service API entry for the token exchange and, if you named a service account, the IAM Service Account Credentials API entry | [Google Cloud refuses the token exchange](#google-cloud-refuses-the-token-exchange) |
198| Authorization server | Your server's log for the `POST` to the token endpoint | [Your authorization server rejects the grant](#your-authorization-server-rejects-the-grant) |
199199
200Allow for log delivery delay before concluding there was no attempt. If your logs show none at the time of the request, the token wasn't issued, and you should [contact Anthropic](#contact-anthropic) with the details listed there. A gateway connection doesn't produce this error. Your gateway's own response reaches Claude, so Claude reports the status your gateway returned, usually 401 or 403; see [Your gateway rejects every token](#your-gateway-rejects-every-token).
200Allow for log delivery delay before concluding there was no attempt. For an AWS role, no new event can also mean Claude reused credentials from an earlier sign-in. See [An AWS request fails after a successful sign-in](#an-aws-request-fails-after-a-successful-sign-in). Otherwise, if your logs show no attempt at the time of the request, the token wasn't issued. [Contact Anthropic](#contact-anthropic) with the details listed there. A gateway connection doesn't produce this error. Your gateway's own response reaches Claude, so Claude reports the status your gateway returned, usually 401 or 403; see [Your gateway rejects every token](#your-gateway-rejects-every-token).
201
202### An AWS request fails after a successful sign-in
203
204**What you see**
205
206Claude's request to an AWS service got HTTP 502 with the reason `injection failed ("<connection name>")`. CloudTrail shows that the role's `AssumeRoleWithWebIdentity` event succeeded, or shows no new event because Claude was reusing credentials from an earlier sign-in. Other kinds of request with the same connection may still work. The failure repeats for one kind of request, for example every call to one host or every upload to S3.
207
208**What it means**
209
210The sign-in worked, but [Agent Proxy](/docs/claude-tag/concepts/agent-identity#agent-proxy) couldn't sign the request with the role's credentials, so it never left for AWS. Claude's reply doesn't say which of these applies:
211
212* **A hostname with no usable region.** Agent Proxy reads the AWS service and signing region from the hostname, so the region must be the last label before `amazonaws.com`, as in `service.region.amazonaws.com`, `my-bucket.s3.us-east-1.amazonaws.com`, or `api.ecr.us-east-1.amazonaws.com`. Agent Proxy refuses a hostname with no region, such as `ec2.amazonaws.com`, unless the service is IAM, STS, S3, Route 53, CloudFront, Organizations, or Global Accelerator, which it signs for `us-east-1`. It also refuses a hostname that puts the region before the service name, such as an OpenSearch domain endpoint (`my-domain.us-east-1.es.amazonaws.com`).
213* **A large request to a service other than S3 with no content hash.** When a request has no `x-amz-content-sha256` header, Agent Proxy hashes the body before signing and refuses a body over 1 MB (1,048,576 bytes). The AWS CLI and SDKs add that header for S3 but usually not for other services.
214* **An S3 upload sent in chunks.** The AWS CLI (2.23.0 and later) and the AWS SDKs that compute upload checksums by default can send S3 uploads in chunks with a checksum trailer. Agent Proxy can't sign a request in that format. The fix is to have the AWS CLI or SDK send the body in one piece.
215
216**How to resolve**
217
218| Cause | Do this |
219| :--------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
220| Hostname with no usable region | Use the service's regional endpoint, `service.region.amazonaws.com` (for S3, also `bucket.s3.region.amazonaws.com`), and make sure that host is in the connection's **Allowed hosts**. A host that exists only with the region before the service name, such as an OpenSearch domain endpoint, can't be reached through a federated connection. [Contact Anthropic](#contact-anthropic) with the hostname. |
221| Large request to a service other than S3 | Keep the body under 1 MB, or have Claude send the request with an `x-amz-content-sha256` header set to the hex SHA-256 of the body, for example with `curl`. For large data, upload to S3 and pass a reference instead. |
222| S3 upload sent in chunks | Have Claude set the environment variable `AWS_REQUEST_CHECKSUM_CALCULATION=WHEN_REQUIRED` before running the AWS CLI or a script that uses an AWS SDK, or add `request_checksum_calculation = WHEN_REQUIRED` to the profile in `~/.aws/config`, then retry. To apply it in every thread, add a line to the scope's [custom instructions](/docs/claude-tag/admins/attach-to-scope#add-custom-instructions), for example "Before using the AWS CLI or an AWS SDK, add `request_checksum_calculation = WHEN_REQUIRED` to the default profile in `~/.aws/config`." S3 still computes and stores a checksum for the object. If the upload still fails, [contact Anthropic](#contact-anthropic). |
201223
202224### The cloud API answers 403 after a successful exchange
203225
claude-tag/admins/federated-access/token-reference Changed · +3 / -1 lines
from line 95
9595
9696Tokens may carry additional claims Anthropic uses internally for audit; ignore any claim not listed here and never base an authorization decision on it.
9797
98Three claim names are reserved and absent from every token: `platform_user_id`, `actor_sub`, and `account_id`. Don't write a rule that depends on them. An absent claim is omitted from the token, never sent empty.
99
98100Anthropic sends the token only to the destinations you connect in **Federated cloud access**. When the request comes from Slack, the `slack_workspace_id` and `slack_channel_id` claims carry your Slack workspace and channel IDs to that destination along with your organization and agent IDs.
99101
100Authorize on `sub`, as described under [Authorize on the subject](#authorize-on-the-subject). A gateway or authorization server, which can read every claim, can use `tenant` and `agent_id` instead, because they repeat the subject's two parts. An AWS trust policy matches on `sub` and `aud` only; a Google Cloud attribute condition can read `sub` or `tenant`. The token carries no claims about the person behind the request, and no `groups`, `roles`, or `scope` claims. A rule that needs `slack_workspace_id` or `slack_channel_id` should refuse a token that lacks them.
102Authorize on `sub`, as described under [Authorize on the subject](#authorize-on-the-subject). A gateway or authorization server, which can read every claim, can use `tenant` and `agent_id` instead, because they repeat the subject's two parts. An AWS trust policy matches on `sub` and `aud` only; a Google Cloud attribute condition can read `sub` or `tenant`. The token carries no claim that names the person behind the request, and no `groups`, `roles`, or `scope` claims. A rule that needs `slack_workspace_id` or `slack_channel_id` should refuse a token that lacks them.
101103
102104<Note>Anthropic may add claims to the token. A verifier must ignore claims it doesn't recognize and must never depend on a claim not listed here being present.</Note>
103105