View a markdown version of this page

使用客户管理的 KMS 密钥加密您的 AgentCore 网关 - Amazon Bedrock AgentCore
加密网关的先决条件 AgentCore

使用客户管理的 KMS 密钥加密您的 AgentCore 网关

默认情况下，Gateway 使用服务托管的 AWS 密钥管理服务密钥对您的静态数据进行加密。但是，在以下情况下，您可以选择提供自己的客户托管的 KMS 密钥，用于加密静态数据：

  • 创建网关。

  • 更新网关的配置。

使用客户管理的密钥可以让你更好地控制加密过程，包括能够：

  • 按自己的时间表轮换密钥

  • 通过 IAM 策略控制对密钥的访问权限

  • 不再需要密钥时将其禁用或删除

  • 通过 CloudWatch 日志和日志审核密钥使用情况 AWS CloudTrail

有关更多信息，请参阅AWS 密钥管理服务开发人员指南。

注意

如果您选择使用客户管理的密钥，则应负责管理该密钥及其权限。如果密钥被禁用或删除，或者 Gateway 失去使用密钥的权限，您将无法访问加密数据。

加密网关的先决条件 AgentCore

在加密网关之前，请确保您已满足以下先决条件：

  • 您可以访问 KMS 密钥。有关创建 KMS 密钥的信息，请参阅创建 KMS 密钥。

  • KMS 密钥附有密钥策略，允许以下权限：

    • 允许网关服务角色执行以下操作的权限：

      • kms: CreateGrant

      • kms: DescribeKey

      • kms:Decrypt

      • kms: GenerateDataKey

    • （如果您为网关启用 CloudWatch 日志）允许 CloudWatch 日志服务解密密钥的权限。

      有关控制 KMS 密钥的 IAM 权限的更多信息，请参阅密钥管理服务开发人员指南中的 KMS AWS 密钥访问和权限。

示例密钥政策

以下示例策略提供了加密网关和使用加密网关所需的权限。第四条语句还允许 CloudWatch 记录加密网关的密钥使用情况。该策略包含符合安全最佳实践的条件密钥。

{
"Version":"2012-10-17",
  "Statement": [
    {
      "Sid": "AllowServiceRoleDescribeKey",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123456789012:role/GatewayServiceRole"
      },
      "Action": [
        "kms:DescribeKey"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": [
            "bedrock-agentcore.us-east-1.amazonaws.com"
          ]
        }
      }
    },
    {
      "Sid": "AllowServiceRoleDecryptKey",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123456789012:role/GatewayServiceRole"
      },
      "Action": [
        "kms:Decrypt",
        "kms:GenerateDataKey"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": [
            "bedrock-agentcore.us-east-1.amazonaws.com"
          ]
        },
        "StringLike": {
          "kms:EncryptionContext:aws:bedrock-agentcore-gateway:arn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/GatewayId"
        }
      }
    },
    {
      "Sid": "AllowServiceRoleCreateGrant",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123456789012:role/GatewayServiceRole"
      },
      "Action": "kms:CreateGrant",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": [
            "bedrock-agentcore.us-east-1.amazonaws.com"
          ],
          "kms:GrantConstraintType": "EncryptionContextSubset"
        },
        "ForAllValues:StringEquals": {
          "kms:GrantOperations": [
            "Decrypt",
            "GenerateDataKey"
          ]
        },
        "StringLike": {
          "kms:EncryptionContext:aws:bedrock-agentcore-gateway:arn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/GatewayId"
        }
      }
    },
    {
      "Sid": "AllowKMSDecryptionLogging",
      "Effect": "Allow",
      "Principal": {
        "Service": "delivery.logs.amazonaws.com"
      },
      "Action": [
        "kms:GenerateDataKey",
        "kms:Decrypt"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "kms:EncryptionContext:SourceArn": "arn:aws:logs:us-east-1:123456789012:*"
        }
      }
    }
  ]
}

该政策包含以下声明：

  • AllowServiceRoleDescribeKKey— 如果请求是通过 AgentCore 服务发出的，则允许指定的委托人描述密钥。替换以下字段中的值：

    • Principal— 将该AWS值替换为网关服务角色的实际 ARN。

    • Condition— 在kms:ViaService数组中，us-east-1替换为要允许描述密钥的实际 AWS 区域。

  • AllowServiceRoleDecryptKey— 如果请求是通过 AgentCore 服务发出的，并且发出请求的网关的 ARN 与字段中的 ARN 匹配，则允许指定的委托人解密密钥。kmsEncryptionContext:aws:bedrock-agentcore-gateway-arn替换以下值：

    • Principal— 将该AWS值替换为网关服务角色的实际 ARN。

    • Condition— 执行以下操作：

      • 在kms:ViaService数组中，us-east-1替换为要允许解密密钥的实际 AWS 区域。

      • 将该kmsEncryptionContext:aws:bedrock-agentcore-gateway-arn值替换为网关的实际 ARN。

  • AllowServiceRoleCreateGrant— 如果请求是通过 AgentCore 服务发出的，并且请求所针对的网关的 ARN 与字段中的 ARN 相匹配，则允许指定的委托人为密钥创建授权。kmsEncryptionContext:aws:bedrock-agentcore-gateway-arn替换以下值：

    • Principal— 将该AWS值替换为网关服务角色的实际 ARN。

    • Condition— 执行以下操作：

      • 在kms:ViaService数组中，us-east-1替换为要允许解密密钥的实际 AWS 区域。

      • 将该kmsEncryptionContext:aws:bedrock-agentcore-gateway-arn值替换为网关的实际 ARN（如果您想允许）。

  • AllowKMSDecryptionLogging— 允许指定的委托人解密客户管理的 KMS 密钥，以便通过日志审核密钥的使用情况。 CloudWatch 在kms:EncryptionContext:SourceArn值中，用您的实际 AWS 区域和账户 ID 替换us-east-1和123456789012值。

例
Console

  1. ====== 使用客户管理的 KMS 密钥加密您的网关

  2. 按照创建 Amazon Bedrock AgentCore 网关中的控制台步骤进行操作，然后展开 KMS 密钥-可选部分。

  3. 选择 “自定义加密设置（高级）”。

  4. 选择 KMS 密钥并确认其详细信息。

    注意

    如果您看不到您的 KMS 密钥，请查看加密 AgentCore 网关的先决条件，并检查权限配置是否正确。

  5. 继续完成其余的控制台步骤。

CLI

  1. 要使用 AWS CLI 加密网关，请在通过AgentCore 控制平面客户端发送以下任一请求kms-key-arn时加上。 :

    • 创建网关

    • 更新网关

      以下示例显示了使用kms-key-arn参数指定的 AWS KMS 密钥创建网关的 CLI 请求示例：

      aws bedrock-agentcore-control create-gateway \
  --name "MyGateway" \
  --role-arn "arn:aws:iam::123456789012:role/GatewayRole" \
  --protocol-type "MCP" \
  --kms-key-arn "arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab" \
  --authorizer-type "CUSTOM_JWT" \
  --authorizer-configuration '{
    "customJWTAuthorizer": {
      "allowedAudience": ["myAudience"],
      "discoveryUrl": "https://example.com/.well-known/openid-configuration"
    }
  }'
Python (Boto3)

  1. 要使用 AWS Python SDK (Boto3) 加密网关，请在通过AgentCore 控制平面客户端发送以下任一请求kms-key-arn时加上。 :

    • 创建网关

    • 更新网关

      以下示例显示了使用参数指定的 AWS KMS 密钥创建网关的 Boto3 请求示例：kmsKeyArn

      import boto3
# Create client
agentcore_client = boto3.client('bedrock-agentcore-control')

# Create gateway and specify
gateway = agentcore_client.create_gateway(
  name="MyGateway",
  roleArn="arn:aws:iam::123456789012:role/GatewayRole",
  protocolType="MCP",
  kmsKeyArn="arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab"
  authorizerType="CUSTOM_JWT",
  authorizerConfiguration= {
    "customJWTAuthorizer": {
      "allowedAudience": ["myAudience"],
      "discoveryUrl": "https://example.com/.well-known/openid-configuration"
    }
  }
)