启用 Cloud KMS Autokey

本页面介绍了如何启用和配置 Cloud KMS Autokey，以便在资源文件夹中进行集中式密钥管理，或在项目中进行委托式密钥管理（预览版）。如需详细了解 Autokey，请参阅 Autokey 概览。本文档面向管理员。

准备工作

在为文件夹中的所有项目启用 Cloud KMS Autokey 以使用专用密钥项目进行集中式密钥管理之前，您必须具备以下条件：

包含您要启用 Autokey 的文件夹的组织资源。如果您没有要启用 Autokey 的文件夹，可以创建新的资源文件夹。在此文件夹中启用 Autokey 会为该文件夹中的所有资源项目启用 Autokey。
如果您有资源项目，想要使用 Autokey 实现集中式密钥管理，但这些项目不在您将启用 Autokey 的文件夹内，则可以将现有资源项目移至新文件夹。

在为项目启用 Autokey（预览版）以启用委托密钥管理和同项目密钥之前，您必须具备以下条件之一：

您要启用 Autokey 的 Google Cloud 项目，且 keyHandles.create 权限未被 IAM 拒绝政策阻止。
您要启用 Autokey 的文件夹，其中至少包含一个项目的 keyHandles.create 权限未被 IAM 拒绝政策阻止。 Google Cloud

所需的角色

如需获得启用和配置 Autokey 所需的权限，请让管理员向您授予文件夹、项目或父级资源的以下 IAM 角色：

Cloud KMS Autokey Admin (roles/cloudkms.autokeyAdmin)
Service Usage Admin (roles/serviceusage.serviceUsageAdmin)
如需启用集中式 Autokey，请执行以下操作：
- Folder IAM Admin (roles/resourcemanager.folderIamAdmin)
- Billing Account user (roles/billing.user)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

这些预定义角色包含启用和配置 Autokey 所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

启用和配置 Autokey 需要以下权限：

cloudkms.autokeyConfigs.*
cloudkms.projects.showEffectiveAutokeyConfig
serviceusage.services.enable
如需启用集中式 Autokey，请执行以下操作：
- resourcemanager.folders.get
- resourcemanager.folders.getIamPolicy
- resourcemanager.folders.setIamPolicy
- billing.resourceAssociations.create

您也可以使用自定义角色或其他预定义角色来获取这些权限。

确定要如何启用 Autokey

您可以使用 Terraform 进行所需的配置更改，从而将 Autokey 纳入您的基础设施即代码策略。如果您想使用 Terraform 启用 Autokey，请参阅本页上的使用 Terraform 启用 Autokey。如果您不想使用 Terraform，请先按照下一部分中的说明操作。

设置 Autokey 以实现集中式密钥管理

当您在文件夹中使用 Autokey 进行集中式密钥管理时，需要选择一个密钥项目来包含 Autokey 在该文件夹中创建的所有密钥。如果您使用的是委托密钥管理模型（预览版），则无需专用密钥项目；请继续执行为委托密钥管理启用 Autokey。

建议您创建一个新的密钥项目，以包含 Autokey 创建的 Cloud KMS 资源。您应在组织资源内创建密钥项目。如果您已有要用于 Autokey 创建的密钥的密钥项目，则可以跳过创建密钥项目部分，直接从本页上的配置 Autokey 密钥项目继续操作。

密钥项目可以在您计划启用 Autokey 的同一文件夹内创建。您不应在密钥项目内创建其他资源。如果您尝试在密钥项目中创建受 Autokey 保护的资源，Autokey 会拒绝新密钥请求。

如果您将来可能想迁移到 Assured Workloads，请在与受这些密钥保护的资源相同的文件夹中创建密钥项目。

如果您的组织使用 constraints/gcp.restrictCmekCryptoKeyProjects 组织政策限制条件来确保所有 CMEK 都来自指定的密钥项目，您必须将密钥项目添加到允许的项目列表中。如需详细了解 CMEK 组织政策，请参阅 CMEK 组织政策。

创建密钥项目

控制台

在 Google Cloud 控制台中，前往管理资源页面。
转到“管理资源”
在选择组织部分，选择要在其中创建项目的组织资源。
点击 Create project。
在随即显示的新建项目窗口中，输入项目名称并选择结算账号。项目名称只能包含字母、数字、英文单引号、连字符、空格或英文感叹号，且长度必须介于 4 到 30 个字符之间。
对于位置，选择您希望作为密钥项目父级的资源。
如需完成项目创建，请点击创建。

gcloud

创建新项目：
```
gcloud projects create PROJECT_ID \
    --PARENT_TYPE=PARENT_ID
```
替换以下内容：
- PROJECT_ID：包含密钥环的项目的 ID。
- PARENT_TYPE：您要在其中创建新密钥项目的资源的类型。输入 organization 可在指定组织下创建新的密钥项目，输入 folder 可在指定文件夹下创建新的密钥项目。
- PARENT_ID：您要在其中创建关键项目的组织或文件夹的 ID。

准备 Autokey 密钥项目

控制台

在密钥项目中启用 Cloud KMS API。

启用 API
如果您使用的是新的密钥项目，请授予密钥项目 Cloud KMS 管理员权限。重复执行以下步骤，为您自己和其他 Cloud KMS 管理员用户授予 Cloud KMS Admin 角色：
1. 在 Google Cloud 控制台中，前往 IAM 页面。
  
  转到 IAM
2. 选择密钥项目。
3. 点击 授予访问权限，然后输入用户的电子邮件地址。
4. 选择 Cloud KMS 管理员角色。
5. 点击保存。

gcloud

在密钥项目中启用 Cloud KMS API：

gcloud services enable cloudkms.googleapis.com

在密钥项目上授予 Cloud KMS 管理员权限。重复执行以下命令，向您自己和其他 Cloud KMS 管理员用户授予 roles/cloudkms.admin 角色：
```
gcloud projects add-iam-policy-binding PROJECT_NUMBER \
    --role=roles/cloudkms.admin \
    --member=user:KEY_ADMIN_EMAIL
```
替换以下内容：
- PROJECT_NUMBER：密钥项目的项目编号。
- KEY_ADMIN_EMAIL：负责管理 Cloud KMS 密钥的用户的电子邮件地址。

在资源文件夹中启用 Cloud KMS Autokey

控制台

在 Google Cloud 控制台中，前往 KMS 控制页面。

前往 KMS 控件
在上下文选择器中，选择要启用 Autokey 的文件夹。
点击启用。
选择您的重点项目，然后点击提交。

系统会显示一条消息，确认已在相应文件夹中启用 Cloud KMS Autokey。

API

为要启用 Autokey 的文件夹创建 AutokeyConfig：

curl "https://cloudkms.googleapis.com/v1/folders/FOLDER_ID/autokeyConfig?updateMask=keyProject" \
    --request "PATCH" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{"key_project": "projects/PROJECT_ID"}'

替换以下内容：

FOLDER_ID：您要启用 Autokey 的文件夹的 ID。
PROJECT_ID：密钥项目的 ID。

设置 Cloud KMS 服务代理

密钥项目的 Cloud KMS 服务代理会在资源创建期间代表 Cloud KMS 管理员创建密钥并应用 IAM 政策绑定。为了能够创建和分配密钥，Cloud KMS 服务代理需要 Cloud KMS 管理员权限。

创建 Cloud KMS 服务代理：
```
gcloud beta services identity create --service=cloudkms.googleapis.com \
    --project=PROJECT_NUMBER
```
将 PROJECT_NUMBER 替换为密钥项目的项目编号。

输出类似于以下内容：
```
Service identity created: service-PROJECT_NUMBER@gcp-sa-ekms.iam.gserviceaccount.com
```
该命令的输出表明，Cloud EKM 服务账号（具有 gcp-sa-ekms 子网域）已创建。不过，该命令还会创建 Cloud KMS 服务代理（带有 gcp-sa-cloudkms 子网域），这是您稍后在这些说明中使用的服务代理。

向服务代理授予 Cloud KMS 管理员权限：

gcloud projects add-iam-policy-binding PROJECT_NUMBER \
    --role=roles/cloudkms.admin \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudkms.iam.gserviceaccount.com

将 PROJECT_NUMBER 替换为密钥项目的项目编号。

为委托的密钥管理启用 Autokey

当您使用 Autokey 进行委托密钥管理时，Autokey 会在受保护资源所在的同一项目中创建密钥。支持使用 Autokey 进行委托密钥管理的项目可以位于已启用 Autokey 以进行集中式密钥管理的文件夹中。在项目上启用 Autokey 后，项目级 Autokey 配置会覆盖父文件夹中的 Autokey 配置。

如需为单个项目启用 Autokey，请完成以下步骤：

使用 REST API 为要启用 Autokey 的项目创建 AutokeyConfig：

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/autokeyConfig?updateMask=key_project_resolution_mode" \
    --request "PATCH" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{"key_project_resolution_mode": "RESOURCE_PROJECT"}'

将 PROJECT_ID 替换为要启用 Autokey 的项目的 ID。

在 gcloud CLI 中，为项目启用 Cloud KMS API：
```
gcloud services enable cloudkms.googleapis.com
```

如需为文件夹中的所有项目启用 Autokey，请完成以下步骤：

使用 REST API，为要启用 Autokey 以使用委托密钥管理的文件夹创建 AutokeyConfig：

curl "https://cloudkms.googleapis.com/v1/folders/FOLDER_ID/autokeyConfig?updateMask=key_project_resolution_mode" \
    --request "PATCH" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{"key_project_resolution_mode": "RESOURCE_PROJECT"}'

将 FOLDER_ID 替换为要启用 Autokey 的文件夹的 ID。此命令会为相应文件夹中的所有项目启用同项目 Autokey。

在 gcloud CLI 中，在您要使用 Autokey 进行委托密钥管理的每个项目中启用 Cloud KMS API：
```
gcloud services enable cloudkms.googleapis.com
```
您可以一次性在所有项目上启用 Cloud KMS API，也可以根据需要单独在各个项目上启用该 API。在该项目启用 Cloud KMS API 之前，开发者无法在该项目中使用 Autokey。

使用 Terraform 启用 Autokey

使用 Terraform 进行集中式密钥管理

以下 Terraform 示例可自动执行以下设置步骤：

创建资源文件夹
创建密钥项目
授予用户权限
设置 Cloud KMS 服务代理
启用 Autokey

您必须在资源文件夹中单独创建资源项目。

variable "organization_ID" {
  description = "Your Google Cloud Org ID"
  type        = string
  default     = "ORGANIZATION_ID"
}

variable "billing_account" {
  description = "Your Google Cloud Billing Account ID"
  type        = string
  default     = "BILLING_ACCOUNT_ID"
}

/* List the users who should have the authority to enable and configure
   Autokey at a folder level */
variable "autokey_folder_admins" {
  type    = list(string)
  default = [AUTOKEY_ADMIN_USER_IDS]
}

/* List the users who should have the authority to protect their resources
   with Autokey */
variable "autokey_folder_users" {
  type    = list(string)
  default = [AUTOKEY_DEVELOPER_USER_IDS]
}

/* List the users who should have the authority to manage crypto operations in
   the Autokey key project */
variable "autokey_project_kms_admins" {
  type    = list(string)
  default = [KEY_PROJECT_ADMIN_USER_IDS]
}

/* The project ID to use for the key project. The project ID must be 6 to 30
   characters with lowercase letters, digits, hyphens. The project ID must start
   with a letter. Trailing hyphens are prohibited */
variable "key_management_project_ID" {
  description = "Sets the project ID for the Key Management Project. This project will contain the Key Rings and Keys generated by Cloud KMS Autokey"
  type        = string
  default     = "KEY_PROJECT_ID"
}

# Create a new folder
resource "google_folder" "autokey_folder" {
  parent       = "organizations/${var.organization_ID}"
  display_name = "autokey_folder"
}

# Set permissions for key admins to use Autokey in this folder
resource "google_folder_iam_binding" "autokey_folder_admin" {
  folder  = google_folder.autokey_folder.name
  role    = "roles/cloudkms.autokeyAdmin"
  members = var.autokey_folder_admins
}

# Set permissions for users to protect resources with Autokey in this folder
resource "google_folder_iam_binding" "autokey_folder_users" {
  folder  = google_folder.autokey_folder.name
  role    = "roles/cloudkms.autokeyUser"
  members = var.autokey_folder_users
}

# Create a key project to store keys created by Autokey
 resource "google_project" "key_management_project" {
  project_id      = var.key_management_project_ID
  name            = var.key_management_project_ID
  billing_account = var.billing_account
  folder_id       = google_folder.autokey_folder.name
}

output "project_number" {
  value = google_project.key_management_project.number
}

# Grant role for Cloud KMS admins to use Autokey in the key project
resource "google_project_iam_binding" "autokey_project_admin" {
  project    = google_project.key_management_project.project_id
  role       = "roles/cloudkms.admin"
  members    = var.autokey_project_kms_admins
  depends_on = [ google_project.key_management_project ]
}

# Enable the Cloud KMS API in the key project
resource "google_project_service" "enable_api" {
  service                    = "cloudkms.googleapis.com"
  project                    = google_project.key_management_project.project_id
  disable_on_destroy         = false
  disable_dependent_services = false
  depends_on                 = [google_project.key_management_project]
}

# Create Cloud KMS service agent
resource "google_project_service_identity" "KMS_Service_Agent" {
  provider   = google-beta
  service    = "cloudkms.googleapis.com"
  project    = google_project.key_management_project.project_id
  depends_on = [google_project.key_management_project]
}

/* Grant role for the Cloud KMS service agent to use delegated
   Cloud KMS administrator permissions */
resource "google_project_iam_member" "autokey_project_admin" {
  project = google_project.key_management_project.project_id
  role    = "roles/cloudkms.admin"
  member  = "serviceAccount:service-${google_project.key_management_project.number}@gcp-sa-cloudkms.iam.gserviceaccount.com"
}

/* Enable AutokeyConfig for centralized key management in this folder */
resource "google_kms_autokey_config" "autokey_config" {
  provider    = google-beta
  folder      = google_folder.autokey_folder.folder_id
  key_project = "projects/${google_project.key_management_project.project_id}"
  key_project_resolution_mode = "DEDICATED_KEY_PROJECT"
  # For folder scope, valid values are: DEDICATED_KEY_PROJECT, RESOURCE_PROJECT, DISABLED
  # With DEDICATED_KEY_PROJECT, define the key_project as well. With RESOURCE_PROJECT,
  #   omit key_project. Keys will be created in the same project as the protected resource.
}

替换以下内容：

BILLING_ACCOUNT_ID：您的 Google Cloud 结算账号 ID。结算账号 ID 是一个 18 个字符的字母数字值，以短划线分隔，例如 010101-F0FFF0-10XX01。
AUTOKEY_ADMIN_USER_IDS：应具有 roles/cloudkms.autokeyAdmin 角色的用户的电子邮件地址列表，例如 "Ariel@example.com", "Charlie@example.com"。
AUTOKEY_DEVELOPER_USER_IDS：应具有 roles/cloudkms.autokeyUser 角色的用户的电子邮件地址列表，例如 "Kalani@example.com", "Mahan@example.com"。
KEY_PROJECT_ADMIN_USER_IDS：应具有 roles/cloudkms.admin 角色的用户的电子邮件地址列表，例如 "Sasha@example.com", "Nur@example.com"。
KEY_PROJECT_ID：专用密钥项目的 ID，例如 autokey-key-project。如果您指定了密钥项目，则 key_project_resolution_mode 必须为 DEDICATED_KEY_PROJECT。

使用 Terraform 进行委托密钥管理

如需在文件夹中的所有项目上启用 Autokey 以进行委托密钥管理，请使用类似于以下内容的 folder_config 资源：

/* Enable AutokeyConfig on a folder */
resource "google_kms_autokey_config" "folder_config" {
  provider    = google-beta
  folder      = google_folder.autokey_folder.name
  key_project_resolution_mode = "RESOURCE_PROJECT"
  # For folder scope, valid values are: DEDICATED_KEY_PROJECT, RESOURCE_PROJECT, DISABLED
  # With DEDICATED_KEY_PROJECT, define the key_project as well. With RESOURCE_PROJECT,
  #   omit key_project. Keys will be created in the same project as the protected resource.
}

如需在单个项目中启用 Autokey 以进行委托密钥管理，请使用类似于以下内容的 autokey_config_project 资源：

/* To set autokey config for a project */
resource "google_kms_autokey_config" "autokey_config_project" {
  provider = google-beta
  project = "projects/${google_project.key_management_project.project_id}"
  key_project_resolution_mode = "RESOURCE_PROJECT"
  # For project scope, valid values are: RESOURCE_PROJECT, DISABLED
}

强制使用 Autokey

如果您想在文件夹内强制使用 Autokey，可以将 IAM 访问权限控制与 CMEK 组织政策结合使用。为此，您可以从 Cloud KMS 服务代理以外的主账号中移除密钥创建权限，然后要求所有资源都使用 Autokey 密钥项目通过 CMEK 进行保护。

如需在文件夹内强制执行 Autokey 使用，请完成以下步骤：

移除在密钥项目中手动创建密钥的权限。如果无法手动创建密钥，则只能在此项目中创建由 Autokey 创建的密钥。如需详细了解如何控制访问权限，请参阅使用 IAM 进行访问权限控制。
在文件夹中设置组织政策，以要求必须使用 constraints/gcp.restrictNonCmekServices 限制条件通过 CMEK 保护资源。如需了解详情，请参阅要求使用 CMEK 保护。
在文件夹中设置组织政策，要求用于 CMEK 的密钥必须来自 Autokey 密钥项目，方法是使用 constraints/gcp.restrictCmekCryptoKeyProjects 限制条件。如需了解详情，请参阅限制 Cloud KMS 密钥用于 CMEK。

停用 Autokey

Cloud KMS Autokey 在文件夹级别启用和停用。能够为文件夹启用 Autokey 的角色也可以为该文件夹停用 Autokey。如需在文件夹中停用 Autokey，您必须清除 AutokeyConfig 以移除文件夹与 Autokey 密钥项目之间的关联。

移除文件夹中的 Autokey 配置后，当开发者在该文件夹中创建资源时，Cloud KMS 服务代理将无法再为他们创建密钥。移除文件夹与密钥项目之间的关联会停用文件夹中的 Autokey；不过，我们建议您同时移除 roles/cloudkms.autokeyAdmin 和 roles/cloudkms.autokeyUser 角色的 IAM 绑定。

停用 Autokey 不会影响密钥项目中的现有密钥。您可以继续使用这些密钥来保护资源。

清除 AutokeyConfig

控制台

在 Google Cloud 控制台中，前往 KMS 控制页面。

前往 KMS 控件
在上下文选择器中，选择要停用 Autokey 的文件夹。
点击停用。

系统会显示一条消息，提示您确认是否要停用 Autokey。
如需停用 Autokey，请点击确认。

系统会显示一条消息，确认已在相应文件夹中停用 Cloud KMS Autokey。

API

清除要停用自动键入功能的文件夹的 AutokeyConfig：

curl "https://cloudkms.googleapis.com/v1/folders/FOLDER_ID/autokeyConfig?updateMask=keyProject" \
    --request "PATCH" \
    --header "authorization: Bearer TOKEN" \
    --header "content-type: application/json" \
    --data '{}'

替换以下内容：

FOLDER_ID：您要停用 Autokey 的文件夹的 ID。

撤消 Autokey 角色

可选：撤消 roles/cloudkms.autokeyAdmin 角色：
```
gcloud resource-manager folders remove-iam-policy-binding \
    FOLDER_ID --role=roles/cloudkms.autokeyAdmin \
    --member=user:USER_EMAIL
```
替换以下内容：
- FOLDER_ID：您已停用自动密钥的文件夹的 ID。
- USER_EMAIL：您要撤消其 Autokey 管理权限的用户的电子邮件地址。
可选：在文件夹级层撤消 roles/cloudkms.autokeyUser 角色：
```
gcloud resource-manager folders remove-iam-policy-binding \
    FOLDER_ID --role=roles/cloudkms.autokeyUser \
    --member=user:USER_EMAIL
```
替换以下内容：
- FOLDER_ID：您已停用自动密钥的文件夹的 ID。
- USER_EMAIL：您要撤消其使用 Autokey 权限的用户的电子邮件地址。
可选：在项目级层撤消 roles/cloudkms.autokeyUser 角色：
```
gcloud projects remove-iam-policy-binding RESOURCE_PROJECT_NUMBER \
    --role=roles/cloudkms.autokeyUser \
    --member=user:USER_EMAIL
```
替换以下内容：
- RESOURCE_PROJECT_NUMBER：您已停用自动密钥的文件夹内资源项目的项目编号。
- USER_EMAIL：您要撤消其使用 Autokey 权限的用户的电子邮件地址。

可选：如果您不打算继续将密钥项目用于其他文件夹的 Autokey，请撤消 Cloud KMS 服务代理的 roles/cloudkms.admin 角色：

gcloud projects remove-iam-policy-binding KEY_PROJECT_NUMBER \
    --role=roles/cloudkms.admin \
    --member=serviceAccount:service-KEY_PROJECT_NUMBER@gcp-sa-cloudkms.iam.gserviceaccount.com

将 KEY_PROJECT_NUMBER 替换为密钥项目的数字 ID。

可选：如果您不打算继续使用在密钥项目中创建的密钥，请撤消 Cloud KMS 管理员的 roles/cloudkms.admin 角色：
```
gcloud projects remove-iam-policy-binding KEY_PROJECT_NUMBER \
    --role=roles/cloudkms.admin \
    --member=user:KEY_ADMIN_EMAIL
```
替换以下内容：
- KEY_PROJECT_NUMBER：密钥项目的项目编号。
- USER_EMAIL：您要撤消其使用 Autokey 权限的用户的电子邮件地址。

后续步骤

详细了解何时使用 Autokey。
详细了解 Autokey 的运作方式。
Autokey 开发者现在可以使用 Autokey 创建受保护的资源。

启用 Cloud KMS Autokey 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

所需的角色

所需权限

确定要如何启用 Autokey

设置 Autokey 以实现集中式密钥管理

创建密钥项目

控制台

gcloud

准备 Autokey 密钥项目

控制台

gcloud

在资源文件夹中启用 Cloud KMS Autokey

控制台

API

设置 Cloud KMS 服务代理

为委托的密钥管理启用 Autokey

使用 Terraform 启用 Autokey

使用 Terraform 进行集中式密钥管理

使用 Terraform 进行委托密钥管理

强制使用 Autokey

停用 Autokey

清除 AutokeyConfig

控制台

API

撤消 Autokey 角色

后续步骤

启用 Cloud KMS Autokey