啟用 Cloud KMS Autokey

本頁面說明如何啟用及設定 Cloud KMS Autokey，以便在資源資料夾中集中管理金鑰，或在專案中委派金鑰管理權 (搶先版)。如要進一步瞭解 Autokey，請參閱「Autokey 總覽」。本文適用對象為管理員。

事前準備

如要為資料夾中的所有專案啟用 Cloud KMS Autokey，並使用專屬金鑰專案集中管理金鑰，您必須具備下列條件：

機構資源，其中包含要啟用 Autokey 的資料夾。如果沒有要啟用 Autokey 的資料夾，可以建立新的資源資料夾。在這個資料夾中啟用 Autokey 後，資料夾內的所有資源專案都會啟用 Autokey。
如果您有資源專案要透過 Autokey 集中管理金鑰，但這些專案不在您要啟用 Autokey 的資料夾中，可以將現有資源專案移至新資料夾。

如要為專案啟用 Autokey (預覽版)，以啟用委派金鑰管理和同專案金鑰，您必須具備下列其中一項：

您要啟用 Autokey 的 Google Cloud 專案，且 keyHandles.create 權限未遭身分與存取權管理拒絕政策封鎖。
您要啟用 Autokey 的資料夾，其中至少包含一個keyHandles.create權限未遭 IAM 拒絕政策封鎖的專案。 Google Cloud

必要的角色

如要取得啟用及設定 Autokey 所需的權限，請要求管理員在資料夾、專案或父項資源中，授予您下列 IAM 角色：

Cloud KMS Autokey 管理員 (roles/cloudkms.autokeyAdmin)
服務使用情形管理員 (roles/serviceusage.serviceUsageAdmin)
如要啟用集中式 Autokey：
- 資料夾 IAM 管理員 (roles/resourcemanager.folderIamAdmin)
- 帳單帳戶使用者 (roles/billing.user)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這些預先定義的角色具備啟用及設定 Autokey 所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要啟用及設定 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 控制台的「Manage resources」(管理資源) 頁面。
前往「Manage resources」(管理資源)
在「選取機構」部分，選取要建立專案的機構資源。
按一下 [Create Project]。
在顯示的「New project」(新增專案) 視窗中，輸入專案名稱並選取帳單帳戶。專案名稱只能由英文字母、數字、單引號、連字號、空格或驚嘆號組成，而且長度必須介於 4 至 30 個字元之間。
在「Location」(位置) 中，選取要做為金鑰專案父項的資源。
如要完成專案建立程序，請按一下「Create」(建立)。

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 管理員使用者：
1. 前往 Google Cloud 控制台的「IAM」(身分與存取權管理) 頁面。
  
  前往 IAM
2. 選取金鑰專案。
3. 按一下「授予存取權」，然後輸入使用者的電子郵件地址。
4. 選取「Cloud KMS 管理員」角色。
5. 按一下 [儲存]。

gcloud

在金鑰專案中啟用 Cloud KMS API：

gcloud services enable cloudkms.googleapis.com

在金鑰專案中授予 Cloud KMS 管理員權限。重複執行下列指令，將 roles/cloudkms.admin 角色授予自己和每位 Cloud KMS 管理員使用者：
```
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 controls」頁面。

前往 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 保護機制」。
在資料夾中設定機構政策，使用 constraints/gcp.restrictCmekCryptoKeyProjects 限制，要求用於 CMEK 的金鑰必須來自 Autokey 金鑰專案。詳情請參閱「限制使用 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 controls」頁面。

前往 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 '{}'

更改下列內容：

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：您停用 Autokey 的資料夾 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：您停用 Autokey 的資料夾 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：您已停用 Autokey 的資料夾中，資源專案的專案編號。
- 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