Enable Cloud KMS Autokey

This page shows you how to enable and configure Cloud KMS Autokey on a resource folder. For more information about Autokey, see Autokey overview. The steps on this page should be completed by a security administrator.

Before you begin

Before you can enable Cloud KMS Autokey, you must have the following:

• An organization resource that contains a folder where you want to enable Autokey. If you don't have a folder where you want to enable Autokey, you can create a new resource folder. Enabling Autokey on this folder enables Autokey for all resource projects within the folder.
• If you have resource projects where you want to use Autokey but they aren't inside a folder where you will enable Autokey, you can move existing resource projects into new folders.

Required roles

To get the permissions that you need to enable and configure Autokey, ask your administrator to grant you the following IAM roles on the organization or folder:

• Cloud KMS Autokey Admin (roles/cloudkms.autokeyAdmin)
• Folder IAM Admin (roles/resourcemanager.folderIamAdmin)
• Billing Account user (roles/billing.user)

For more information about granting roles, see Manage access to projects, folders, and organizations.

These predefined roles contain the permissions required to enable and configure Autokey. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to enable and configure Autokey:

• cloudkms.autokeyConfigs.*
• cloudkms.projects.showEffectiveAutokeyConfig
• resourcemanager.folders.get
• resourcemanager.folders.getIamPolicy
• resourcemanager.folders.setIamPolicy
• billing.resourceAssociations.create

You might also be able to get these permissions with custom roles or other predefined roles.

Decide how you want to enable Autokey

You can enable Autokey as part of your infrastructure-as-code strategy by using Terraform to make the required configuration changes. If you want to use Terraform to enable Autokey, see Enable Autokey using Terraform on this page. If you don't want to use Terraform, start by following the instructions in the next section.

Set up the key project

We recommend creating a new key project to contain Cloud KMS resources created by Autokey. You should create the key project inside your organization resource. If you already have a key project that you want to use for keys created by Autokey, you can skip the Create a key project section and continue from Configure the Autokey key project on this page.

The key project can be created inside the same folder where you plan to enable Autokey. You shouldn't create other resources inside the key project. If you attempt to create resources protected by Autokey in the key project, Autokey rejects the request for a new key.

If you might want to migrate to Assured Workloads in the future, create the key project inside the same folder as the resources protected by those keys.

If your organization uses the constraints/gcp.restrictCmekCryptoKeyProjects organization policy constraint to ensure that all CMEKs are from specified key projects, you must add your key project to the list of allowed projects. For more information about CMEK organization policy, see CMEK organization policies.

Create a key project

Console

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. For Select organization, select the organization resource where you want to create a project.
3. Click Create project.
4. In the New project window that appears, enter a project name and select a billing account. A project name can contain only letters, numbers, single quotes, hyphens, spaces, or exclamation points, and must be between 4 and 30 characters.
5. For Location, select the resource that you want to be the parent for your key project.
6. To finish creating the project, click Create.

gcloud

• Create a new project:

  gcloud projects create PROJECT_ID \
      --PARENT_TYPE=PARENT_ID
  

  Replace the following:

  • PROJECT_ID: the ID of the project that contains the key ring.
  • PARENT_TYPE: the type of the resource where you want to create the new key project. Enter organization to create the new key project under a given organization, or enter folder to create the new key project under a given folder.
  • PARENT_ID: the ID of the organization or folder where you want to create the key project.

Prepare the Autokey key project

Console

1. Enable the Cloud KMS API on your key project.

   Enable the API

2. If you are using a new key project, grant Cloud KMS administrator permissions on the key project. Repeat the following steps to grant the Cloud KMS Admin role to yourself and each other Cloud KMS administrator user:

   1. In the Google Cloud console, go to the IAM page.

      Go to IAM

   2. Select the key project.

   3. Click Grant Access, and then enter the user's email address.

   4. Select the Cloud KMS Admin role.

   5. Click Save.

gcloud

1. Enable the Cloud KMS API on your key project:

   gcloud services enable cloudkms.googleapis.com
   

2. Grant Cloud KMS administrator permissions on the key project. Repeat the following command to grant the roles/cloudkms.admin role to yourself and each other Cloud KMS administrator users:

   gcloud projects add-iam-policy-binding PROJECT_NUMBER \
       --role=roles/cloudkms.admin \
       --member=user:KEY_ADMIN_EMAIL
   

   Replace the following:

   • PROJECT_NUMBER: the project number of the key project.
   • KEY_ADMIN_EMAIL: the email address of the user who is responsible for managing Cloud KMS keys.

Enable Cloud KMS Autokey on a resource folder

Console

1. In the Google Cloud console, go to the KMS controls page.

   Go to KMS controls

2. From the context picker, select the folder where you want to enable Autokey.

3. Click Enable.

4. Select your key project and then click Submit.

   A message confirms that Cloud KMS Autokey is enabled on the folder.

API

Create the AutokeyConfig for the folder where you want to enable Autokey:

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"}'

Replace the following:

• FOLDER_ID: the ID of the folder where you want to enable Autokey.
• PROJECT_ID: the ID of the key project.

Set up the Cloud KMS service agent

The Cloud KMS service agent for a key project creates keys and applies IAM policy bindings during resource creation, on behalf of a human Cloud KMS administrator. To be able to create and assign keys, the Cloud KMS service agent requires Cloud KMS administrator permissions.

1. Create the Cloud KMS service agent:

   gcloud beta services identity create --service=cloudkms.googleapis.com \
       --project=PROJECT_NUMBER
   

   Replace PROJECT_NUMBER with the project number of the key project.

   The output is similar to the following:

   Service identity created: [e-mail]
   

   The output of the command indicates that the Cloud EKM service account (with the gcp-sa-ekms subdomain) has been created. However, the command also creates the Cloud KMS service agent (with the gcp-sa-cloudkms subdomain), which is the service agent that you use later in these instructions.

2. Grant Cloud KMS administrator permissions to the service agent:

   gcloud projects add-iam-policy-binding PROJECT_NUMBER \
       --role=roles/cloudkms.admin \
       --member=serviceAccount:[e-mail]
   

   Replace PROJECT_NUMBER with the project number of the key project.

Grant Autokey user roles

Before your developers can use Autokey, you must grant them the required role. You can grant the role at the folder level or at the project level. This role lets developers request keys from the Cloud KMS service agent while creating resources in that folder or project.

Choose one or both of the following steps:

• Grant the roles/cloudkms.autokeyUser role at the folder level:

  gcloud resource-manager folders add-iam-policy-binding \
      FOLDER_ID --role=roles/cloudkms.autokeyUser \
      --member=user:USER_EMAIL
  

  Replace the following:

  • FOLDER_ID: the ID of the folder where you want to enable Autokey.
  • USER_EMAIL: the email address of the user to whom you want to grant permission to use Autokey.

• Grant the roles/cloudkms.autokeyUser role at the project level:

  gcloud projects add-iam-policy-binding PROJECT_ID \
      --role=roles/cloudkms.autokeyUser \
      --member=user:USER_EMAIL
  

  Replace the following:

  • PROJECT_ID: the ID of the resource project.
  • USER_EMAIL: the email address of the user to whom you want to grant permission to use Autokey.

Your Autokey developers can now create keys on demand. To learn how to create resources protected using keys created on demand by Autokey, see Create protected resources using Autokey.

Enable Autokey using Terraform

The following Terraform sample automates the following setup steps:

• Create a resource folder
• Create a key project
• Grant user permissions
• Set up the Cloud KMS service agent
• Enable Autokey

You must separately create resource projects within the resource folder.

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 admin 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 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}"
}

Replace the following:

• BILLING_ACCOUNT_ID: your Google Cloud billing account ID. The billing account ID is an 18-character alphanumeric value separated by dashes—for example, 010101-F0FFF0-10XX01.
• AUTOKEY_ADMIN_USER_IDS: a list of email addresses for users that should have the roles/cloudkms.autokeyAdmin role—for example, "[e-mail]", "[e-mail]".
• AUTOKEY_DEVELOPER_USER_IDS: a list of email addresses for users that should have the roles/cloudkms.autokeyUser role—for example, "[e-mail]", "[e-mail]".
• KEY_PROJECT_ADMIN_USER_IDS: a list of email addresses for users that should have the roles/cloudkms.admin role—for example, "[e-mail]", "[e-mail]".
• KEY_PROJECT_ID: the ID to use for the key project—for example, autokey-key-project.

Enforce Autokey usage

If you want to enforce usage of Autokey within a folder, you can do so by combining IAM access controls with CMEK organization policies. This works by removing key creation permissions from principals other than the Cloud KMS service agent, and then requiring that all resources are protected by CMEK using the Autokey key project.

To enforce Autokey usage within a folder, complete the following steps:

1. Remove access to create keys manually in the key project. If keys can't be manually created, then only keys created by Autokey can be created in this project. For more information about controlling access, see Access control with IAM.

2. Set an organization policy on the folder to require that resources must be protected with a CMEK using the constraints/gcp.restrictNonCmekServices constraint. For more information, see Require CMEK protection.

3. Set an organization policy on the folder to require that keys used for CMEK must be from the Autokey key project using the constraints/gcp.restrictCmekCryptoKeyProjects constraint. For more information, see Limit the use of Cloud KMS keys for CMEK.

Disable Autokey

Cloud KMS Autokey is enabled and disabled at the folder level. The same roles that can enable Autokey for a folder can disable Autokey for that folder. To disable Autokey on a folder, you must clear the AutokeyConfig to remove the association between the folder and the Autokey key project.

After the Autokey configuration on the folder is removed, the Cloud KMS service agent can no longer create keys for developers when they create resources in the folder. Removing the link between the folder and the key project disables Autokey in the folder; however, we recommend that you also remove the IAM bindings for the roles/cloudkms.autokeyAdmin and roles/cloudkms.autokeyUser roles.

Disabling Autokey doesn't affect existing keys in the key project. You can continue to use these keys to protect your resources.

Clear AutokeyConfig

Console

1. In the Google Cloud console, go to the KMS controls page.

   Go to KMS controls

2. From the context picker, select the folder where you want to disable Autokey.

3. Click Disable.

   A message appears prompting you to confirm that you want to disable Autokey.

4. To disable Autokey, click Confirm.

   A message confirms that Cloud KMS Autokey is disabled on the folder.

API

Clear the AutokeyConfig for the folder where you want to disable Autokey:

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

Replace the following:

• FOLDER_ID: the ID of the folder where you want to disable Autokey.

Revoke Autokey roles

1. Optional: Revoke the roles/cloudkms.autokeyAdmin role:

   gcloud resource-manager folders remove-iam-policy-binding \
       FOLDER_ID --role=roles/cloudkms.autokeyAdmin \
       --member=user:USER_EMAIL
   

   Replace the following:

   • FOLDER_ID: the ID of the folder where you have disabled Autokey.
   • USER_EMAIL: the email address of the user for whom you want to revoke permission to manage Autokey.

2. Optional: Revoke the roles/cloudkms.autokeyUser role at the folder level:

   gcloud resource-manager folders remove-iam-policy-binding \
       FOLDER_ID --role=roles/cloudkms.autokeyUser \
       --member=user:USER_EMAIL
   

   Replace the following:

   • FOLDER_ID: the ID of the folder where you have disabled Autokey.
   • USER_EMAIL: the email address of the user for whom you want to revoke permission to use Autokey.

3. Optional: Revoke the roles/cloudkms.autokeyUser role at the project level:

   gcloud projects remove-iam-policy-binding RESOURCE_PROJECT_NUMBER \
       --role=roles/cloudkms.autokeyUser \
       --member=user:USER_EMAIL
   

   Replace the following:

   • RESOURCE_PROJECT_NUMBER: the project number of a resource project within the folder where you have disabled Autokey.
   • USER_EMAIL: the email address of the user for whom you want to revoke permission to use Autokey.

4. Optional: If you don't plan to continue using the key project for Autokey for other folders, revoke the roles/cloudkms.admin role for the Cloud KMS service agent:

   gcloud projects remove-iam-policy-binding KEY_PROJECT_NUMBER \
       --role=roles/cloudkms.admin \
       --member=serviceAccount:[e-mail]
   

   Replace KEY_PROJECT_NUMBER with the numerical ID of the key project.

5. Optional: If you don't plan to continue using keys created inside the key project, revoke the roles/cloudkms.admin role for the Cloud KMS administrator:

   gcloud projects remove-iam-policy-binding KEY_PROJECT_NUMBER \
       --role=roles/cloudkms.admin \
       --member=user:KEY_ADMIN_EMAIL
   

   Replace the following:

   • KEY_PROJECT_NUMBER: the project number of the key project.
   • USER_EMAIL: the email address of the user for whom you want to revoke permission to use Autokey.

What's next

• Learn more about when to use Autokey.
• Learn more about how Autokey works.
• Your Autokey developers can now create protected resources using Autokey.