SPB Git

Repository Public

cmek-aws-kms.md 36.6 KB 659 lines markdown

1---2title: Configure AWS KMS for CMEK3url: https://platform.claude.com/docs/en/manage-claude/cmek-aws-kms4description: Use AWS KMS to provide an encryption key for your organization.5---67```bash Configure with the /claude-api skill in Claude Code8claude "/claude-api help me configure a customer-managed encryption key with AWS KMS"9```1011This guide walks through configuring an [AWS KMS](https://aws.amazon.com/kms/) key as a [customer-managed encryption key (CMEK)](https://platform.claude.com/docs/en/manage-claude/cmek) for your Anthropic organization.1213<Warning>14  Enabling CMEK is permanent. If your KMS key is deleted or disabled, Anthropic cannot recover the data encrypted under it. Review the [warnings and limitations](https://platform.claude.com/docs/en/manage-claude/cmek) before you begin.15</Warning>1617<Note>18  **Claude Platform on AWS:** On [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), your key policy grants access to an AWS service principal instead of Anthropic's IAM role, there is no separate validation step, and you register and attach the key in the Claude Console. Follow [Set up CMEK on Claude Platform on AWS](https://platform.claude.com/docs/en/manage-claude/cmek-aws-kms#claude-platform-on-aws) on this page instead of the steps in the next sections.19</Note>2021## Prerequisites2223* An AWS account with permissions to create KMS keys and set key policies (`kms:CreateKey` and `kms:PutKeyPolicy`).24* An Anthropic Admin API key for your organization.25* The [AWS CLI](https://aws.amazon.com/cli/) installed and authenticated.2627## Amazon Resource Name (ARN) for Anthropic2829To have Anthropic use your encryption key, you must give Anthropic's IAM role a KMS key it can use for encrypting data. The ARN for Anthropic CMEK is:3031```text wrap32arn:aws:iam::915198916910:role/anthropic-cmek-client-us33```3435<Warning>36  Use only this published ARN. Never trust an identifier provided over email, chat, or any onboarding channel.37</Warning>3839## Encryption key setup4041<Steps>42  <Step title="Create the KMS key with a cross-account key policy">43    The key policy grants Anthropic's IAM role cross-account access. Three statements are required:4445    1. **Account root admin:** the standard KMS pattern. Your account retains full admin control.46    2. **Anthropic encrypt and decrypt:** the `kms:Encrypt` and `kms:Decrypt` actions, which Anthropic uses to encrypt and decrypt the data keys that protect your workspace data (envelope encryption).47    3. **Anthropic describe:** the metadata read Anthropic performs at startup. It is granted separately because `DescribeKey` has no `EncryptionContext` parameter, so an `EncryptionContext` condition on this action would always deny.4849    ```bash50    export YOUR_ACCOUNT=$(aws sts get-caller-identity --query Account --output text)5152    aws kms create-key \53      --region <region> \54      --description "Anthropic CMEK" \55      --key-usage ENCRYPT_DECRYPT \56      --policy "{57        \"Version\": \"2012-10-17\",58        \"Statement\": [59          {60            \"Sid\": \"AccountRootAdmin\",61            \"Effect\": \"Allow\",62            \"Principal\": {\"AWS\": \"arn:aws:iam::${YOUR_ACCOUNT}:root\"},63            \"Action\": \"kms:*\",64            \"Resource\": \"*\"65          },66          {67            \"Sid\": \"AllowAnthropicCMEKCrypto\",68            \"Effect\": \"Allow\",69            \"Principal\": {\"AWS\": \"arn:aws:iam::915198916910:role/anthropic-cmek-client-us\"},70            \"Action\": [\"kms:Encrypt\", \"kms:Decrypt\"],71            \"Resource\": \"*\",72            \"Condition\": {73              \"StringEquals\": {74                \"kms:EncryptionContext:anthropic:compartment_uuid\": [75                  \"00000000-0000-0000-0000-000000000000\",76                  \"<compartment-uuid>\"77                ]78              }79            }80          },81          {82            \"Sid\": \"AllowAnthropicCMEKDescribe\",83            \"Effect\": \"Allow\",84            \"Principal\": {\"AWS\": \"arn:aws:iam::915198916910:role/anthropic-cmek-client-us\"},85            \"Action\": \"kms:DescribeKey\",86            \"Resource\": \"*\"87          }88        ]89      }"90    ```9192    Capture `KeyMetadata.Arn` from the output. You need it when you register the key in the next step.9394    The `EncryptionContext` condition is recommended but optional. Anthropic always includes your workspace's compartment ID in the encryption context, so ciphertext is cryptographically bound to that compartment regardless. Adding the condition provides defense-in-depth at the IAM layer. To start without it, omit the `Condition` block from the `AllowAnthropicCMEKCrypto` statement and add it later with `kms:PutKeyPolicy`.9596    <Note>97      **Finding your compartment ID:** Where to find your compartment ID differs between Claude Platform and Claude Enterprise. See the **Claude Platform** and **Claude Enterprise** tabs under **Register the key with Anthropic**.98    </Note>99100    You can also create the key from the AWS Console. Choose a symmetric key with the encrypt and decrypt key usage, a single-region key, and KMS key material origin. The Create-key wizard commits a key policy at its **Review** step: If you add Anthropic's account ID `915198916910` under key usage permissions there, the generated policy grants the whole Anthropic account broader actions (such as `kms:ReEncrypt*` and `kms:GenerateDataKey*`) with no `EncryptionContext` condition, and validation would still succeed against it. To avoid leaving an over-permissive key, finish the wizard with administrative permissions only, then open the key's **Key policy** tab and replace the JSON with the role-scoped policy shown earlier (the three statements scoped to the `anthropic-cmek-client-us` role, with the `EncryptionContext` condition).101102    <Frame caption="Configure key: symmetric, encrypt and decrypt, single-region key.">103      ![AWS KMS Create key wizard on the Configure key step, with Symmetric key type, Encrypt and decrypt key usage, and Single-Region key selected.](https://platform.claude.com/docs/images/cmek/aws-configure-key.png)104    </Frame>105106    <Frame caption="Add an alias and description for the key.">107      ![AWS KMS Add labels step with an alias of anthropic-cmek and a description of Anthropic CMEK.](https://platform.claude.com/docs/images/cmek/aws-add-labels.png)108    </Frame>109110    <Frame caption="Define key administrative permissions (optional). Your account retains full admin control.">111      ![AWS KMS Define key administrative permissions step listing IAM roles that can administer the key.](https://platform.claude.com/docs/images/cmek/aws-admin-permissions.png)112    </Frame>113114    <Frame caption="Do not add Anthropic's account ID here. This wizard step produces an over-permissive policy. Leave usage permissions empty and edit the Key policy JSON after creation (see the preceding key policy).">115      ![AWS KMS Define key usage permissions step with Anthropic's account ID entered under Other AWS accounts.](https://platform.claude.com/docs/images/cmek/aws-usage-permissions.png)116    </Frame>117  </Step>118</Steps>119120## Register the key with Anthropic121122How you register the key depends on which product you use.123124<Tabs>125  <Tab title="Claude Platform">126    <Note>127      **Claude Platform on AWS:** The principal, key policy, and registration flow differ, and there is no separate validation step. Follow [Set up CMEK on Claude Platform on AWS](https://platform.claude.com/docs/en/manage-claude/cmek-aws-kms#claude-platform-on-aws) instead of this tab.128    </Note>129130    <Note>131      **Finding your compartment ID:** Each workspace has a compartment ID that scopes its CMEK data. Find it in the Claude Console under **Workspace > Security**, under **Encryption key** (the **Compartment ID** field), or read the `compartment_id` field returned by the [Get Workspace](https://platform.claude.com/docs/en/api/admin-api/workspaces/get-workspace) endpoint. Substitute that value for `<compartment-uuid>` in the preceding key policy.132133      Key validation always sends the all-zeros compartment UUID (`00000000-0000-0000-0000-000000000000`) as the encryption context, because validation runs before the key is attached to any workspace. Live traffic sends the compartment ID of each attached workspace.134135      Any `EncryptionContext` condition must allow the all-zeros value plus the compartment ID of every workspace the key is attached to. Validation also runs again whenever key setup is re-run, so keep the all-zeros entry in place permanently.136137      To attach the key to an additional workspace, add that workspace's compartment ID to the condition with `kms:PutKeyPolicy` before attaching.138    </Note>139140    You can set up the key in the Claude Console or through the Admin API, with the same result.141142    <Tabs>143      <Tab title="Claude Console">144        <Steps>145          <Step title="Register the key with Anthropic">146            In the Claude Console, open **Settings > Encryption keys** and click **Add key**. Enter a display name, choose **AWS KMS**, and click **Continue**. Paste the key ARN into **KMS key ARN**, and click **Add**.147          </Step>148149          <Step title="Validate the key">150            On the **Encryption keys** page, click **Verify** next to the key. **Connected** appears when the check passes. If it fails, a message gives the reason.151          </Step>152153          <Step title="Attach the key to a workspace">154            Open **Settings > Workspaces**, choose the workspace, and open its **Security** tab. Under **Encryption key**, select the key, click **Save**, and confirm. Attaching a key can't be undone. For a workspace that already receives requests, the key can take [up to a day to take effect](https://platform.claude.com/docs/en/manage-claude/cmek#how-it-works).155          </Step>156        </Steps>157      </Tab>158159      <Tab title="API">160        <Steps>161          <Step title="Register the key with Anthropic">162            Create an external key configuration through the Admin API.163164            <CodeGroup>165              ```bash cURL166              curl -sS "https://api.anthropic.com/v1/organizations/external_keys" \167                -H "x-api-key: $ANTHROPIC_API_KEY" \168                -H "anthropic-version: 2023-06-01" \169                -H "content-type: application/json" \170                -d '{171                  "display_name": "<friendly-name>",172                  "geo": "us",173                  "provider_config": {174                    "type": "aws",175                    "kms_arn": "<key-arn-from-create-key-step>"176                  }177                }'178              ```179180              ```bash CLI181              ant beta:organization:external-keys create <<'YAML'182              display_name: "<friendly-name>"183              geo: us184              provider_config:185                type: aws186                kms_arn: "<key-arn-from-create-key-step>"187              YAML188              ```189190              ```python Python191              client = anthropic.Anthropic()192193              external_key = client.beta.organization.external_keys.create(194                  display_name="<friendly-name>",195                  geo="us",196                  provider_config={"type": "aws", "kms_arn": "<key-arn-from-create-key-step>"},197              )198199              print(f"id: {external_key.id}")200              print(f"display_name: {external_key.display_name}")201              ```202203              ```typescript TypeScript204              const client = new Anthropic();205206              const externalKey = await client.beta.organization.externalKeys.create({207                display_name: "<friendly-name>",208                geo: "us",209                provider_config: {210                  type: "aws",211                  kms_arn: "<key-arn-from-create-key-step>"212                }213              });214215              console.log(`id: ${externalKey.id}`);216              console.log(`display_name: ${externalKey.display_name}`);217              ```218219              ```csharp C#220              using Anthropic.Models.Beta.Organization.ExternalKeys;221222              AnthropicClient client = new();223224              var externalKey = await client.Beta.Organization.ExternalKeys.Create(new()225              {226                  DisplayName = "<friendly-name>",227                  Geo = Geo.Us,228                  ProviderConfig = new BetaAwsExternalKeyConfig229                  {230                      KmsArn = "<key-arn-from-create-key-step>"231                  }232              });233234              Console.WriteLine($"id: {externalKey.ID}");235              Console.WriteLine($"display_name: {externalKey.DisplayName}");236              ```237238              ```go Go239              client := anthropic.NewClient()240241              externalKey, err := client.Beta.Organization.ExternalKeys.New(context.Background(), anthropic.BetaOrganizationExternalKeyNewParams{242              	DisplayName: anthropic.String("<friendly-name>"),243              	Geo:         anthropic.BetaOrganizationExternalKeyNewParamsGeoUs,244              	ProviderConfig: anthropic.BetaOrganizationExternalKeyNewParamsProviderConfigUnion{245              		OfAWS: &anthropic.BetaAWSExternalKeyConfigParam{246              			KMSARN: "<key-arn-from-create-key-step>",247              		},248              	},249              })250              if err != nil {251              	log.Fatal(err)252              }253254              fmt.Printf("id: %s\n", externalKey.ID)255              fmt.Printf("display_name: %s\n", externalKey.DisplayName)256              ```257258              ```java Java259              import com.anthropic.models.beta.organization.externalkeys.BetaAwsExternalKeyConfig;260              import com.anthropic.models.beta.organization.externalkeys.ExternalKeyCreateParams;261262              void main() {263                  AnthropicClient client = AnthropicOkHttpClient.fromEnv();264265                  var params = ExternalKeyCreateParams.builder()266                      .displayName("<friendly-name>")267                      .geo(ExternalKeyCreateParams.Geo.US)268                      .providerConfig(BetaAwsExternalKeyConfig.builder()269                          .kmsArn("<key-arn-from-create-key-step>")270                          .build())271                      .build();272                  var externalKey = client.beta().organization().externalKeys().create(params);273274                  IO.println("id: " + externalKey.id());275                  IO.println("display_name: " + externalKey.displayName().orElseThrow());276              }277              ```278279              ```php PHP280              use Anthropic\Beta\Organization\ExternalKeys\ExternalKeyCreateParams\Geo;281              // ...282283              $client = new Client();284285              $externalKey = $client->beta->organization->externalKeys->create(286                  displayName: '<friendly-name>',287                  geo: Geo::US,288                  providerConfig: [289                      'type' => 'aws',290                      'kmsARN' => '<key-arn-from-create-key-step>',291                  ],292              );293294              echo "id: {$externalKey->id}\n";295              echo "display_name: {$externalKey->displayName}\n";296              ```297298              ```ruby Ruby299              client = Anthropic::Client.new300301              external_key = client.beta.organization.external_keys.create(302                display_name: "<friendly-name>",303                geo: :us,304                provider_config: {305                  type: :aws,306                  kms_arn: "<key-arn-from-create-key-step>"307                }308              )309310              puts "id: #{external_key.id}"311              puts "display_name: #{external_key.display_name}"312              ```313            </CodeGroup>314315            The response contains the external key ID:316317            ```json318            {319              "type": "external_key",320              "id": "ekey_<id>",321              "display_name": "<friendly-name>"322            }323            ```324          </Step>325326          <Step title="Validate the key">327            Trigger an encrypt and decrypt round-trip against your key.328329            <CodeGroup>330              ```bash cURL331              curl -sS -X POST "https://api.anthropic.com/v1/organizations/external_keys/ekey_<id>/validate" \332                -H "x-api-key: $ANTHROPIC_API_KEY" \333                -H "anthropic-version: 2023-06-01"334              ```335336              ```bash CLI337              ant beta:organization:external-keys validate --external-key-id "ekey_<id>"338              ```339340              ```python Python341              client = anthropic.Anthropic()342343              validation = client.beta.organization.external_keys.validate("ekey_<id>")344345              print(f"status: {validation.status}")346              print(f"error: {validation.error}")347              ```348349              ```typescript TypeScript350              const client = new Anthropic();351352              const validation = await client.beta.organization.externalKeys.validate("ekey_<id>");353354              console.log(`status: ${validation.status}`);355              console.log(`error: ${validation.error}`);356              ```357358              ```csharp C#359              AnthropicClient client = new();360361              var validation = await client.Beta.Organization.ExternalKeys.Validate("ekey_<id>");362363              Console.WriteLine($"status: {validation.Status.Raw()}");364              Console.WriteLine($"error: {validation.Error}");365              ```366367              ```go Go368              client := anthropic.NewClient()369370              validation, err := client.Beta.Organization.ExternalKeys.Validate(context.Background(), "ekey_<id>")371              if err != nil {372              	log.Fatal(err)373              }374375              fmt.Printf("status: %s\n", validation.Status)376              fmt.Printf("error: %s\n", validation.Error)377              ```378379              ```java Java380              AnthropicClient client = AnthropicOkHttpClient.fromEnv();381382              var validation = client.beta().organization().externalKeys().validate("ekey_<id>");383384              IO.println("status: " + validation.status().asString());385              IO.println("error: " + validation.error().orElse(""));386              ```387388              ```php PHP389              $client = new Client();390391              $validation = $client->beta->organization->externalKeys->validate(392                  externalKeyID: 'ekey_<id>',393              );394395              echo "status: {$validation->status}\n";396              echo "error: {$validation->error}\n";397              ```398399              ```ruby Ruby400              client = Anthropic::Client.new401402              external_key_id = "ekey_<id>"403              validation = client.beta.organization.external_keys.validate(external_key_id)404405              puts "status: #{validation.status}"406              puts "error: #{validation.error}"407              ```408            </CodeGroup>409410            A successful response looks like this:411412            ```json413            { "type": "external_key_validation", "status": "success", "error": null }414            ```415416            If validation fails, common causes are:417418            * **Encryption context mismatch:** Validation fails while data traffic works (or the reverse) with an opaque `AccessDeniedException` when a `kms:EncryptionContext:anthropic:compartment_uuid` condition allows only one of the two values Anthropic sends. Validation sends the all-zeros UUID (`00000000-0000-0000-0000-000000000000`); live traffic sends the attached workspace's compartment ID. Confirm the condition lists both. To rule the condition out entirely, temporarily remove the `Condition` block from the `AllowAnthropicCMEKCrypto` statement and re-validate.419            * **Resource control policies (RCPs):** If your AWS organization has an RCP that denies KMS operations when `aws:PrincipalOrgID` does not match your org, it blocks Anthropic's cross-account role. The RCP needs a carve-out for this key or for Anthropic's role ARN. Service control policies do not apply here, because they do not evaluate for external principals calling through resource-based policies.420            * **Access granted through IAM instead of the key policy:** Cross-account KMS access must be granted in the key policy itself, not through an IAM policy in your account. Check with `aws kms get-key-policy --key-id <id> --policy-name default`.421            * **Region mismatch:** Confirm the key's region is one Anthropic operates in for the geo tier you configured.422          </Step>423424          <Step title="Attach the key to a workspace">425            Once the key is validated, attach it to a new workspace before you send any requests to that workspace. For a workspace that already receives requests, the key can take [up to a day to take effect](https://platform.claude.com/docs/en/manage-claude/cmek#how-it-works).426427            <CodeGroup>428              ```bash cURL429              curl -sS -X POST "https://api.anthropic.com/v1/organizations/workspaces/<workspace-id>" \430                -H "x-api-key: $ANTHROPIC_API_KEY" \431                -H "anthropic-version: 2023-06-01" \432                -H "content-type: application/json" \433                -d '{434                  "external_key_id": "ekey_<id>"435                }'436              ```437438              ```bash CLI439              ant beta:organization:workspaces update \440                --workspace-id "<workspace-id>" \441                --external-key-id "ekey_<id>"442              ```443444              ```python Python445              client = anthropic.Anthropic()446447              workspace = client.beta.organization.workspaces.update(448                  "<workspace-id>", external_key_id="ekey_<id>"449              )450451              print(f"id: {workspace.id}")452              print(f"external_key_id: {workspace.external_key_id}")453              ```454455              ```typescript TypeScript456              const client = new Anthropic();457458              const workspace = await client.beta.organization.workspaces.update("<workspace-id>", {459                external_key_id: "ekey_<id>"460              });461462              console.log(`id: ${workspace.id}`);463              console.log(`external_key_id: ${workspace.external_key_id}`);464              ```465466              ```csharp C#467              AnthropicClient client = new();468469              var workspace = await client.Beta.Organization.Workspaces.Update("<workspace-id>", new()470              {471                  ExternalKeyID = "ekey_<id>"472              });473474              Console.WriteLine($"id: {workspace.ID}");475              Console.WriteLine($"external_key_id: {workspace.ExternalKeyID}");476              ```477478              ```go Go479              client := anthropic.NewClient()480481              workspace, err := client.Beta.Organization.Workspaces.Update(482              	context.Background(),483              	"<workspace-id>",484              	anthropic.BetaOrganizationWorkspaceUpdateParams{485              		ExternalKeyID: anthropic.String("ekey_<id>"),486              	},487              )488              if err != nil {489              	log.Fatal(err)490              }491492              fmt.Printf("id: %s\n", workspace.ID)493              fmt.Printf("external_key_id: %s\n", workspace.ExternalKeyID)494              ```495496              ```java Java497              import com.anthropic.models.beta.organization.workspaces.WorkspaceUpdateParams;498499              void main() {500                  AnthropicClient client = AnthropicOkHttpClient.fromEnv();501502                  var params = WorkspaceUpdateParams.builder()503                      .externalKeyId("ekey_<id>")504                      .build();505                  var workspace = client.beta().organization().workspaces().update("<workspace-id>", params);506507                  IO.println("id: " + workspace.id());508                  IO.println("external_key_id: " + workspace.externalKeyId().orElseThrow());509              }510              ```511512              ```php PHP513              $client = new Client();514515              $workspace = $client->beta->organization->workspaces->update(516                  workspaceID: '<workspace-id>',517                  externalKeyID: 'ekey_<id>',518              );519520              echo "id: {$workspace->id}\n";521              echo "external_key_id: {$workspace->externalKeyID}\n";522              ```523524              ```ruby Ruby525              client = Anthropic::Client.new526527              workspace_id = "<workspace-id>"528              workspace = client.beta.organization.workspaces.update(529                workspace_id,530                external_key_id: "ekey_<id>"531              )532533              puts "id: #{workspace.id}"534              puts "external_key_id: #{workspace.external_key_id}"535              ```536            </CodeGroup>537          </Step>538        </Steps>539      </Tab>540    </Tabs>541  </Tab>542543  <Tab title="Claude Enterprise">544    In [claude.ai > Organization settings > Data and privacy](https://claude.ai/admin-settings/data-privacy-controls), open **Encryption keys**, then click **Add key**. Choose **AWS** and click **Continue**, then paste the Key ARN from the previous step and click **Add**. Anthropic validates the key with an encrypt and decrypt round-trip. Once it shows as verified, your organization is CMEK-protected from that point forward.545546    The key details step of this flow displays your organization's **Compartment ID** with a copy button. Substitute that value for `<compartment-uuid>` in the key policy (see the Create the KMS key step under Encryption key setup); you can open the flow to copy the ID before you create the key. After setup, the ID remains visible on the key under **Encryption keys**.547548    On Claude Enterprise, CMEK applies to the whole organization, so there is no separate workspace attach step, and an organization can have only one key.549  </Tab>550</Tabs>551552## Set up CMEK on Claude Platform on AWS553554On [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), CMEK uses AWS KMS keys only, and setup differs from the preceding sections in these ways:555556* **Principal:** Your key policy grants access to the AWS service principal `aws-external-anthropic.amazonaws.com`. Anthropic's IAM role and account ID are not used, so the [ARN for Anthropic](https://platform.claude.com/docs/en/manage-claude/cmek-aws-kms#amazon-resource-name-arn-for-anthropic) does not apply.557* **Key requirements:** The key must be a symmetric KMS key with encrypt and decrypt usage, single-region, and in the same AWS account and region as the workspace you attach it to. Cross-account keys are not supported: the key must be in the AWS account that hosts your organization. Multi-region keys (key IDs that begin with `mrk-`) and alias ARNs are rejected when you register the key; use the key ARN.558* **No separate validation step:** Apart from those checks on the key ARN at registration, the key is validated when you attach it to a workspace. The attach call performs an encrypt/decrypt round against the key with that workspace's compartment ID as the encryption context, so a key policy problem surfaces at attach time rather than at registration. Unlike the Claude Platform policy earlier on this page, an `EncryptionContext` condition therefore needs no all-zeros entry.559* **Where you manage keys:** Register and attach keys in the Claude Console, signed in through AWS with the Admin role. The external key endpoints are also available on Claude Platform on AWS, authorized through [IAM actions](https://platform.claude.com/docs/en/api/claude-platform-on-aws-iam-actions#encryption-keys); there, a key is identified by its KMS key ARN rather than an `ekey_` ID.560561<Warning>562  Use only this published service principal name. Never trust an identifier provided over email, chat, or any onboarding channel.563</Warning>564565### Prerequisites566567* The AWS account that hosts your Claude Platform on AWS organization, with permissions to create KMS keys and set key policies (`kms:CreateKey` and `kms:PutKeyPolicy`).568* The **Admin** role in the Claude Console for Claude Platform on AWS. See [Using the Claude Console](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#using-the-claude-console).569* For the IAM principal you sign in to the Claude Console with: besides `aws-external-anthropic:AssumeConsole`, the [IAM actions](https://platform.claude.com/docs/en/api/claude-platform-on-aws-iam-actions#encryption-keys) for the operations you perform there, because the Encryption keys page and key attachment go through the AWS gateway. Registering a key is `RegisterKey` (with `ListKeys` and `GetKey` to view registrations), and attaching one is `UpdateWorkspace` or `CreateWorkspace`. The external key actions (and `CreateWorkspace`) are account-scoped, so grant them on `Resource: "*"`; a policy limited to workspace ARNs does not include them.570* For the IAM principal that attaches the key to a workspace (the identity you signed in to the Claude Console with): `kms:DescribeKey`, `kms:Encrypt`, and `kms:Decrypt` on the key. Your principal's access to the key is checked when you attach it, in addition to the service principal's.571* Optional, for the key picker in the Claude Console: `kms:ListKeys` and `kms:DescribeKey` for the principal you sign in with. Without them, paste the key ARN instead.572573### Create the KMS key574575The key policy has three statements: your account's root admin statement; a statement that lets the Claude Platform on AWS service principal encrypt, decrypt, and generate data keys; and a separate statement for `kms:DescribeKey`. Both service-principal statements carry a recommended `aws:SourceArn` condition: the service calls your key on behalf of a specific workspace and passes that [workspace's ARN](https://platform.claude.com/docs/en/api/claude-platform-on-aws-iam-actions#service-details) as the source ARN, so the pattern shown limits the grant to workspaces in your own AWS account. `DescribeKey` is granted separately because it has no `EncryptionContext` parameter, so an `EncryptionContext` condition on that action would always deny.576577If you plan to use the optional `EncryptionContext` condition shown here, create the workspace first (without a key) and copy its compartment ID from the Claude Console under **Workspace > Security**, under **Encryption key** (the **Compartment ID** field), or from the `compartment_id` field returned by the [Get Workspace](https://platform.claude.com/docs/en/api/admin-api/workspaces/get-workspace) endpoint. Substitute it for `<compartment-uuid>`. Otherwise, delete the `StringEquals` entry from that statement's `Condition` block and keep the `ArnLike` entry.578579```bash580export YOUR_ACCOUNT=$(aws sts get-caller-identity --query Account --output text)581582aws kms create-key \583  --region <workspace-region> \584  --description "Anthropic CMEK (Claude Platform on AWS)" \585  --key-usage ENCRYPT_DECRYPT \586  --policy "{587    \"Version\": \"2012-10-17\",588    \"Statement\": [589      {590        \"Sid\": \"AccountRootAdmin\",591        \"Effect\": \"Allow\",592        \"Principal\": {\"AWS\": \"arn:aws:iam::${YOUR_ACCOUNT}:root\"},593        \"Action\": \"kms:*\",594        \"Resource\": \"*\"595      },596      {597        \"Sid\": \"AllowClaudePlatformOnAWSCrypto\",598        \"Effect\": \"Allow\",599        \"Principal\": {\"Service\": \"aws-external-anthropic.amazonaws.com\"},600        \"Action\": [\"kms:Encrypt\", \"kms:Decrypt\", \"kms:GenerateDataKey\"],601        \"Resource\": \"*\",602        \"Condition\": {603          \"ArnLike\": {604            \"aws:SourceArn\": \"arn:aws:aws-external-anthropic:*:${YOUR_ACCOUNT}:workspace/*\"605          },606          \"StringEquals\": {607            \"kms:EncryptionContext:anthropic:compartment_uuid\": [608              \"<compartment-uuid>\"609            ]610          }611        }612      },613      {614        \"Sid\": \"AllowClaudePlatformOnAWSDescribe\",615        \"Effect\": \"Allow\",616        \"Principal\": {\"Service\": \"aws-external-anthropic.amazonaws.com\"},617        \"Action\": \"kms:DescribeKey\",618        \"Resource\": \"*\",619        \"Condition\": {620          \"ArnLike\": {621            \"aws:SourceArn\": \"arn:aws:aws-external-anthropic:*:${YOUR_ACCOUNT}:workspace/*\"622          }623        }624      }625    ]626  }"627```628629Capture `KeyMetadata.Arn` from the output. You need it when you register the key.630631Both conditions are optional hardening, and they compose. The `aws:SourceArn` condition can be written before any workspace exists; to pin the key to particular workspaces instead of your whole account, list their full workspace ARNs in place of the wildcard pattern, and to start without it, delete the `ArnLike` entry from both service-principal statements (removing a `Condition` block that this leaves empty). The `EncryptionContext` condition is also optional. Every encrypt, decrypt, and data-key call made for a workspace, including the attach-time check, carries that workspace's compartment ID as `anthropic:compartment_uuid`, so the condition lists the compartment ID of each workspace you attach the key to and needs no all-zeros entry. Adding it binds the key to the workspaces you list at the IAM layer as well. Because a compartment ID exists only once its workspace exists, the order is: create the workspace, put its compartment ID in the condition (at key creation, or later with `kms:PutKeyPolicy`), then attach the key. Before attaching the key to each additional workspace, add that workspace's compartment ID the same way. To start without it, delete the `StringEquals` entry from the `AllowClaudePlatformOnAWSCrypto` statement's `Condition` block; if you add it later, include the compartment ID of every workspace the key is already attached to.632633You can also create the key from the AWS Console: choose a symmetric key with the encrypt and decrypt key usage, a single-region key, and KMS key material origin, in the workspace's region. Leave key usage permissions empty in the Create-key wizard, then open the key's **Key policy** tab and replace the JSON with the policy shown here.634635### Register and attach the key636637<Steps>638  <Step title="Register the key">639    In the Claude Console, open **Settings > Encryption keys** and click **Add key**. Enter a display name, then choose the key from the key picker or choose **Enter ARN manually** and paste the key ARN, and click **Add**. The key must be in the AWS account that hosts your organization; cross-account keys are not supported. The picker lists the enabled, customer-managed, symmetric, single-region keys in your account in one of your organization's regions; for a key the picker doesn't list, enter the ARN. It lists keys only if the principal you signed in with can call `kms:ListKeys` and `kms:DescribeKey`.640  </Step>641642  <Step title="Attach the key to a workspace">643    Attach the key to a new workspace before you send any requests to that workspace. For a workspace that already receives requests, the key can take [up to a day to take effect](https://platform.claude.com/docs/en/manage-claude/cmek#how-it-works). In the Claude Console, open the workspace and, under **Security**, select the key in **Encryption key**, save, and confirm. You can also select a key when you create a workspace in the Claude Console, but only if your key policy does not yet name specific workspaces (no `EncryptionContext` condition, and the account-wide `aws:SourceArn` pattern rather than individual workspace ARNs), because the workspace's ID and compartment ID are assigned at creation. Once attached, a workspace's key can't be changed.644645    This is when the key is validated: the attach call checks your principal's access to the key and performs an encrypt/decrypt round against it with the workspace's compartment ID as the encryption context, so a problem with either the key policy or your principal's permissions surfaces as an error on that call. If the attach fails with a KMS access error, check the following:646647    * The key policy names the `aws-external-anthropic.amazonaws.com` service principal and grants `kms:Encrypt`, `kms:Decrypt`, and `kms:GenerateDataKey`, plus `kms:DescribeKey` in a separate statement that has no `EncryptionContext` condition.648    * The `aws:SourceArn` condition matches this workspace's ARN (your account ID, and the workspace if you listed specific ARNs), and any `EncryptionContext` condition includes this workspace's compartment ID.649    * The key is enabled, single-region, and in the same AWS account and region as the workspace.650    * The principal you are signed in as has `kms:DescribeKey`, `kms:Encrypt`, and `kms:Decrypt` on the key.651    * No service control policy or resource control policy in your AWS organization prevents the service principal or your principal from using the key.652    * If the policy looks right and the attach still fails, find the denied `kms:` event in CloudTrail in the key's account (it shows the calling principal and, for cryptographic calls, the encryption context), then retry with the `aws:SourceArn` condition temporarily removed to tell a source-ARN mismatch apart from an encryption-context mismatch. Once the key is attached, whether on that retry or after you correct the encryption context, restore the `ArnLike` entry on both service-principal statements with `kms:PutKeyPolicy`, using the account-wide `aws:SourceArn` pattern or the ARN of every workspace the key is attached to.653  </Step>654</Steps>655656## Terraform657658For infrastructure-as-code deployments, the same steps map to the `aws` provider with the `aws_kms_key` and `aws_kms_alias` resources.659
Files main
Menu

Theme