Claude Platform Docs
AdministraciónClaves de cifrado

Configurar AWS KMS para CMEK

Usa AWS KMS para proporcionar una clave de cifrado para tu organización.

Configure with the /claude-api skill in Claude Code
claude "/claude-api help me configure a customer-managed encryption key with AWS KMS"

Esta guía explica cómo configurar una clave de AWS KMS como una "customer-managed encryption key" (clave de cifrado administrada por el cliente), o CMEK para tu organización de Anthropic.

Requisitos previos

  • Una cuenta de AWS con permisos para crear claves de KMS y establecer políticas de clave (kms:CreateKey y kms:PutKeyPolicy).
  • Una clave de API de administrador (Admin API key) de Anthropic para tu organización.
  • La AWS CLI instalada y autenticada.

Amazon Resource Name (ARN) para Anthropic

Para que Anthropic use tu clave de cifrado, debes darle al rol de IAM de Anthropic una clave de KMS que pueda usar para cifrar datos. El ARN para CMEK de Anthropic es:

arn:aws:iam::915198916910:role/anthropic-cmek-client-us

Configuración de la clave de cifrado

  1. Crea la clave de KMS con una política de clave entre cuentas

    La política de clave otorga al rol de IAM de Anthropic acceso entre cuentas (cross-account). Se requieren tres declaraciones:

    1. Administrador raíz de la cuenta: el patrón estándar de KMS. Tu cuenta conserva el control administrativo total.
    2. Cifrado y descifrado de Anthropic: las acciones kms:Encrypt y kms:Decrypt, que Anthropic usa para cifrar y descifrar las claves de datos que protegen los datos de tu espacio de trabajo ("envelope encryption", o cifrado de sobre).
    3. Descripción de Anthropic: la lectura de metadatos que Anthropic realiza al iniciar. Se otorga por separado porque DescribeKey no tiene un parámetro EncryptionContext, por lo que una condición EncryptionContext sobre esta acción siempre denegaría.
    export YOUR_ACCOUNT=$(aws sts get-caller-identity --query Account --output text)

aws kms create-key \
  --region <region> \
  --description "Anthropic CMEK" \
  --key-usage ENCRYPT_DECRYPT \
  --policy "{
    \"Version\": \"2012-10-17\",
    \"Statement\": [
      {
        \"Sid\": \"AccountRootAdmin\",
        \"Effect\": \"Allow\",
        \"Principal\": {\"AWS\": \"arn:aws:iam::${YOUR_ACCOUNT}:root\"},
        \"Action\": \"kms:*\",
        \"Resource\": \"*\"
      },
      {
        \"Sid\": \"AllowAnthropicCMEKCrypto\",
        \"Effect\": \"Allow\",
        \"Principal\": {\"AWS\": \"arn:aws:iam::915198916910:role/anthropic-cmek-client-us\"},
        \"Action\": [\"kms:Encrypt\", \"kms:Decrypt\"],
        \"Resource\": \"*\",
        \"Condition\": {
          \"StringEquals\": {
            \"kms:EncryptionContext:anthropic:compartment_uuid\": [
              \"00000000-0000-0000-0000-000000000000\",
              \"<compartment-uuid>\"
            ]
          }
        }
      },
      {
        \"Sid\": \"AllowAnthropicCMEKDescribe\",
        \"Effect\": \"Allow\",
        \"Principal\": {\"AWS\": \"arn:aws:iam::915198916910:role/anthropic-cmek-client-us\"},
        \"Action\": \"kms:DescribeKey\",
        \"Resource\": \"*\"
      }
    ]
  }"

    Captura KeyMetadata.Arn de la salida. Lo necesitas cuando registres la clave en el siguiente paso.

    La condición EncryptionContext es recomendada pero opcional. Anthropic siempre incluye el ID de compartimento de tu espacio de trabajo en el contexto de cifrado, por lo que el texto cifrado queda vinculado criptográficamente a ese compartimento de todos modos. Agregar la condición proporciona defensa en profundidad en la capa de IAM. Para comenzar sin ella, omite el bloque Condition de la declaración AllowAnthropicCMEKCrypto y agrégalo más tarde con kms:PutKeyPolicy.

    También puedes crear la clave desde la consola de AWS. Elige una clave simétrica con el uso de clave de cifrado y descifrado, una clave de una sola región y origen de material de clave KMS. El asistente Create-key confirma una política de clave en su paso Review: si agregas el ID de cuenta de Anthropic 915198916910 en los permisos de uso de clave allí, la política generada otorga a toda la cuenta de Anthropic acciones más amplias (como kms:ReEncrypt* y kms:GenerateDataKey*) sin condición EncryptionContext, y la validación aún tendría éxito con ella. Para evitar dejar una clave con permisos excesivos, finaliza el asistente solo con permisos administrativos, luego abre la pestaña Key policy de la clave y reemplaza el JSON con la política limitada al rol que se muestra arriba (las tres declaraciones limitadas al rol anthropic-cmek-client-us, con la condición EncryptionContext).

    Asistente Create key de AWS KMS en el paso Configure key, con el tipo de clave Symmetric, el uso de clave Encrypt and decrypt y Single-Region key seleccionados.
    Configure key (configurar clave): symmetric (simétrica), encrypt and decrypt (cifrar y descifrar), single-region key (clave de una sola región).
    Paso Add labels de AWS KMS con un alias de anthropic-cmek y una descripción de Anthropic CMEK.
    Add labels (agregar etiquetas): agrega un alias y una descripción para la clave.
    Paso Define key administrative permissions de AWS KMS que enumera los roles de IAM que pueden administrar la clave.
    Define key administrative permissions (definir permisos administrativos de la clave), opcional. Tu cuenta conserva el control administrativo total.
    Paso Define key usage permissions de AWS KMS con el ID de cuenta de Anthropic ingresado en Other AWS accounts.
    No agregues el ID de cuenta de Anthropic aquí. Este paso del asistente, Define key usage permissions (definir permisos de uso de la clave), produce una política con permisos excesivos. Deja los permisos de uso vacíos y edita el JSON de Key policy después de la creación (consulta la política de clave anterior).

Registrar la clave con Anthropic

La forma de registrar la clave depende del producto que uses.

  1. Registra la clave con Anthropic

    Crea una configuración de clave externa a través de la Admin API.

    client = anthropic.Anthropic()

external_key = client.beta.organization.external_keys.create(
    display_name="<friendly-name>",
    geo="us",
    provider_config={"type": "aws", "kms_arn": "<key-arn-from-create-key-step>"},
)

print(f"id: {external_key.id}")
print(f"display_name: {external_key.display_name}")

    La respuesta contiene el ID de la clave externa:

    {
  "type": "external_key",
  "id": "ekey_<id>",
  "display_name": "<friendly-name>"
}

  2. Valida la clave

    Activa un ciclo de cifrado y descifrado de ida y vuelta contra tu clave.

    client = anthropic.Anthropic()

validation = client.beta.organization.external_keys.validate("ekey_<id>")

print(f"status: {validation.status}")
print(f"error: {validation.error}")

    Una respuesta exitosa se ve así:

    { "type": "external_key_validation", "status": "success", "error": null }

    Si la validación falla, las causas comunes son:

    • Discrepancia en el contexto de cifrado: La validación falla mientras el tráfico de datos funciona (o al revés) con una AccessDeniedException opaca cuando una condición kms:EncryptionContext:anthropic:compartment_uuid permite solo uno de los dos valores que Anthropic envía. La validación envía el UUID de todos ceros (00000000-0000-0000-0000-000000000000); el tráfico en vivo envía el ID de compartimento del espacio de trabajo adjunto. Confirma que la condición incluya ambos. Para descartar la condición por completo, elimina temporalmente el bloque Condition de la declaración AllowAnthropicCMEKCrypto y vuelve a validar.
    • Políticas de control de recursos (RCP): Si tu organización de AWS tiene una RCP que deniega operaciones de KMS cuando aws:PrincipalOrgID no coincide con tu organización, esta bloquea el rol entre cuentas de Anthropic. La RCP necesita una excepción para esta clave o para el ARN del rol de Anthropic. Las políticas de control de servicios no aplican aquí, porque no se evalúan para principales externos que llaman a través de políticas basadas en recursos.
    • Acceso otorgado a través de IAM en lugar de la política de clave: El acceso entre cuentas a KMS debe otorgarse en la propia política de clave, no a través de una política de IAM en tu cuenta. Verifícalo con aws kms get-key-policy --key-id <id> --policy-name default.
    • Discrepancia de región: Confirma que la región de la clave sea una en la que Anthropic opera para el nivel geográfico que configuraste.

  3. Adjunta la clave a un espacio de trabajo

    Una vez validada la clave, adjúntala a un espacio de trabajo nuevo antes de enviar cualquier solicitud a ese espacio de trabajo. Para un espacio de trabajo que ya recibe solicitudes, la clave puede tardar hasta un día en entrar en vigor.

    client = anthropic.Anthropic()

workspace = client.beta.organization.workspaces.update(
    "<workspace-id>", external_key_id="ekey_<id>"
)

print(f"id: {workspace.id}")
print(f"external_key_id: {workspace.external_key_id}")

Configurar CMEK en Claude Platform on AWS

En Claude Platform on AWS, CMEK usa únicamente claves de AWS KMS, y la configuración difiere de las secciones anteriores en estos aspectos:

  • Principal: Tu política de clave otorga acceso al principal de servicio de AWS aws-external-anthropic.amazonaws.com. El rol de IAM y el ID de cuenta de Anthropic no se usan, por lo que el ARN para Anthropic no aplica.
  • Requisitos de la clave: La clave debe ser una clave de KMS simétrica con uso de cifrado y descifrado, de una sola región, y en la misma cuenta y región de AWS que el espacio de trabajo al que la adjuntas. Las claves entre cuentas no son compatibles: la clave debe estar en la cuenta de AWS que aloja tu organización. Las claves multirregión (ID de clave que comienzan con mrk-) y los ARN de alias se rechazan cuando registras la clave; usa el ARN de la clave.
  • Sin paso de validación separado: Aparte de esas verificaciones sobre el ARN de la clave en el registro, la clave se valida cuando la adjuntas a un espacio de trabajo. La llamada de adjuntar realiza un ciclo de cifrado/descifrado contra la clave con el ID de compartimento de ese espacio de trabajo como contexto de cifrado, por lo que un problema en la política de clave aparece al momento de adjuntar en lugar de en el registro. A diferencia de la política de Claude Platform anterior en esta página, una condición EncryptionContext por lo tanto no necesita una entrada de todos ceros.
  • Dónde administras las claves: Registra y adjunta claves en la Claude Console, con sesión iniciada a través de AWS con el rol Admin. Los endpoints de claves externas también están disponibles en Claude Platform on AWS, autorizados a través de acciones de IAM; allí, una clave se identifica por su ARN de clave de KMS en lugar de un ID ekey_.

Requisitos previos

  • La cuenta de AWS que aloja tu organización de Claude Platform on AWS, con permisos para crear claves de KMS y establecer políticas de clave (kms:CreateKey y kms:PutKeyPolicy).
  • El rol Admin en la Claude Console para Claude Platform on AWS. Consulta Uso de la Claude Console.
  • Para el principal de IAM con el que inicias sesión en la Claude Console: además de aws-external-anthropic:AssumeConsole, las acciones de IAM para las operaciones que realizas allí, porque la página Encryption keys y la acción de adjuntar claves pasan por el gateway de AWS. Registrar una clave es RegisterKey (con ListKeys y GetKey para ver los registros), y adjuntar una es UpdateWorkspace o CreateWorkspace. Las acciones de claves externas (y CreateWorkspace) tienen alcance de cuenta, así que otórgalas sobre Resource: "*"; una política limitada a ARN de espacios de trabajo no las incluye.
  • Para el principal de IAM que adjunta la clave a un espacio de trabajo (la identidad con la que iniciaste sesión en la Claude Console): kms:DescribeKey, kms:Encrypt y kms:Decrypt sobre la clave. El acceso de tu principal a la clave se verifica cuando la adjuntas, además del acceso del principal de servicio.
  • Opcional, para el selector de claves en la Claude Console: kms:ListKeys y kms:DescribeKey para el principal con el que inicias sesión. Sin ellos, pega el ARN de la clave en su lugar.

Crear la clave de KMS

La política de clave tiene tres declaraciones: la declaración de administrador raíz de tu cuenta; una declaración que permite al principal de servicio de Claude Platform on AWS cifrar, descifrar y generar claves de datos; y una declaración separada para kms:DescribeKey. Ambas declaraciones del principal de servicio llevan una condición aws:SourceArn recomendada: el servicio llama a tu clave en nombre de un espacio de trabajo específico y pasa el ARN de ese espacio de trabajo como ARN de origen, por lo que el patrón mostrado limita la concesión a los espacios de trabajo de tu propia cuenta de AWS. DescribeKey se otorga por separado porque no tiene un parámetro EncryptionContext, por lo que una condición EncryptionContext sobre esa acción siempre denegaría.

Si planeas usar la condición EncryptionContext opcional que se muestra aquí, crea primero el espacio de trabajo (sin clave) y copia su ID de compartimento desde la Claude Console en Workspace > Security, en Encryption key (el campo Compartment ID), o desde el campo compartment_id que devuelve el endpoint Get Workspace. Sustitúyelo por <compartment-uuid>. De lo contrario, elimina la entrada StringEquals del bloque Condition de esa declaración y conserva la entrada ArnLike.

export YOUR_ACCOUNT=$(aws sts get-caller-identity --query Account --output text)

aws kms create-key \
  --region <workspace-region> \
  --description "Anthropic CMEK (Claude Platform on AWS)" \
  --key-usage ENCRYPT_DECRYPT \
  --policy "{
    \"Version\": \"2012-10-17\",
    \"Statement\": [
      {
        \"Sid\": \"AccountRootAdmin\",
        \"Effect\": \"Allow\",
        \"Principal\": {\"AWS\": \"arn:aws:iam::${YOUR_ACCOUNT}:root\"},
        \"Action\": \"kms:*\",
        \"Resource\": \"*\"
      },
      {
        \"Sid\": \"AllowClaudePlatformOnAWSCrypto\",
        \"Effect\": \"Allow\",
        \"Principal\": {\"Service\": \"aws-external-anthropic.amazonaws.com\"},
        \"Action\": [\"kms:Encrypt\", \"kms:Decrypt\", \"kms:GenerateDataKey\"],
        \"Resource\": \"*\",
        \"Condition\": {
          \"ArnLike\": {
            \"aws:SourceArn\": \"arn:aws:aws-external-anthropic:*:${YOUR_ACCOUNT}:workspace/*\"
          },
          \"StringEquals\": {
            \"kms:EncryptionContext:anthropic:compartment_uuid\": [
              \"<compartment-uuid>\"
            ]
          }
        }
      },
      {
        \"Sid\": \"AllowClaudePlatformOnAWSDescribe\",
        \"Effect\": \"Allow\",
        \"Principal\": {\"Service\": \"aws-external-anthropic.amazonaws.com\"},
        \"Action\": \"kms:DescribeKey\",
        \"Resource\": \"*\",
        \"Condition\": {
          \"ArnLike\": {
            \"aws:SourceArn\": \"arn:aws:aws-external-anthropic:*:${YOUR_ACCOUNT}:workspace/*\"
          }
        }
      }
    ]
  }"

Captura KeyMetadata.Arn de la salida. Lo necesitas cuando registres la clave.

Ambas condiciones son un endurecimiento opcional, y se combinan. La condición aws:SourceArn puede escribirse antes de que exista cualquier espacio de trabajo; para fijar la clave a espacios de trabajo particulares en lugar de a toda tu cuenta, enumera sus ARN de espacio de trabajo completos en lugar del patrón con comodín, y para comenzar sin ella, elimina la entrada ArnLike de ambas declaraciones del principal de servicio (eliminando un bloque Condition que esto deje vacío). La condición EncryptionContext también es opcional. Cada llamada de cifrado, descifrado y clave de datos realizada para un espacio de trabajo, incluida la verificación al momento de adjuntar, lleva el ID de compartimento de ese espacio de trabajo como anthropic:compartment_uuid, por lo que la condición enumera el ID de compartimento de cada espacio de trabajo al que adjuntas la clave y no necesita una entrada de todos ceros. Agregarla vincula la clave a los espacios de trabajo que enumeras también en la capa de IAM. Dado que un ID de compartimento existe solo una vez que existe su espacio de trabajo, el orden es: crea el espacio de trabajo, coloca su ID de compartimento en la condición (al crear la clave, o más tarde con kms:PutKeyPolicy), luego adjunta la clave. Antes de adjuntar la clave a cada espacio de trabajo adicional, agrega el ID de compartimento de ese espacio de trabajo de la misma manera. Para comenzar sin ella, elimina la entrada StringEquals del bloque Condition de la declaración AllowClaudePlatformOnAWSCrypto; si la agregas más tarde, incluye el ID de compartimento de cada espacio de trabajo al que la clave ya esté adjunta.

También puedes crear la clave desde la consola de AWS: elige una clave simétrica con el uso de clave de cifrado y descifrado, una clave de una sola región y origen de material de clave KMS, en la región del espacio de trabajo. Deja los permisos de uso de clave vacíos en el asistente Create-key, luego abre la pestaña Key policy de la clave y reemplaza el JSON con la política que se muestra aquí.

Registrar y adjuntar la clave

  1. Registra la clave

    En la Claude Console, abre Settings > Encryption keys y haz clic en Add key. Ingresa un nombre para mostrar, luego elige la clave en el selector de claves o elige Enter ARN manually y pega el ARN de la clave, y haz clic en Add. La clave debe estar en la cuenta de AWS que aloja tu organización; las claves entre cuentas no son compatibles. El selector enumera las claves habilitadas, administradas por el cliente, simétricas y de una sola región de tu cuenta en una de las regiones de tu organización; para una clave que el selector no enumere, ingresa el ARN. Enumera claves solo si el principal con el que iniciaste sesión puede llamar a kms:ListKeys y kms:DescribeKey.

  2. Adjunta la clave a un espacio de trabajo

    Adjunta la clave a un espacio de trabajo nuevo antes de enviar cualquier solicitud a ese espacio de trabajo. Para un espacio de trabajo que ya recibe solicitudes, la clave puede tardar hasta un día en entrar en vigor. En la Claude Console, abre el espacio de trabajo y, en Security, selecciona la clave en Encryption key, guarda y confirma. También puedes seleccionar una clave cuando creas un espacio de trabajo en la Claude Console, pero solo si tu política de clave aún no nombra espacios de trabajo específicos (sin condición EncryptionContext, y con el patrón aws:SourceArn de toda la cuenta en lugar de ARN de espacios de trabajo individuales), porque el ID del espacio de trabajo y el ID de compartimento se asignan en la creación. Una vez adjunta, la clave de un espacio de trabajo no se puede cambiar.

    Este es el momento en que se valida la clave: la llamada de adjuntar verifica el acceso de tu principal a la clave y realiza un ciclo de cifrado/descifrado contra ella con el ID de compartimento del espacio de trabajo como contexto de cifrado, por lo que un problema con la política de clave o con los permisos de tu principal aparece como un error en esa llamada. Si la acción de adjuntar falla con un error de acceso de KMS, verifica lo siguiente:

    • La política de clave nombra al principal de servicio aws-external-anthropic.amazonaws.com y otorga kms:Encrypt, kms:Decrypt y kms:GenerateDataKey, más kms:DescribeKey en una declaración separada que no tiene condición EncryptionContext.
    • La condición aws:SourceArn coincide con el ARN de este espacio de trabajo (tu ID de cuenta, y el espacio de trabajo si enumeraste ARN específicos), y cualquier condición EncryptionContext incluye el ID de compartimento de este espacio de trabajo.
    • La clave está habilitada, es de una sola región y está en la misma cuenta y región de AWS que el espacio de trabajo.
    • El principal con el que iniciaste sesión tiene kms:DescribeKey, kms:Encrypt y kms:Decrypt sobre la clave.
    • Ninguna política de control de servicios ni política de control de recursos en tu organización de AWS impide que el principal de servicio o tu principal usen la clave.
    • Si la política parece correcta y la acción de adjuntar aún falla, busca el evento kms: denegado en CloudTrail en la cuenta de la clave (muestra el principal que llama y, para llamadas criptográficas, el contexto de cifrado), luego reintenta con la condición aws:SourceArn eliminada temporalmente para distinguir una discrepancia de ARN de origen de una discrepancia de contexto de cifrado.

Terraform

Para despliegues de infraestructura como código, los mismos pasos se corresponden con el proveedor aws con los recursos aws_kms_key y aws_kms_alias.

Was this page helpful?