This page shows you how to enable and configure Cloud KMS Autokey forcentralized key management on a resource folder or for delegated key managementin projects (Preview). For more information about Autokey,seeAutokey overview. This document is intended foradministrators.

Before you begin

Before you can enable Cloud KMS Autokey for centralized key management usinga dedicated key project for all projects in a folder, you must have thefollowing:

• An organization resource that contains a folder where you want to enableAutokey. If you don't have a folder where you want to enableAutokey, you cancreate a new resource folder.Enabling Autokey on this folder enables Autokey for allresource projects within the folder.

• If you have resource projects where you want to use centralized keymanagement with Autokey but they aren't inside a folder where youwill enable Autokey, you canmove existing resource projects intonew folders.

Before you can enable Autokey for projects (Preview) toenable delegated key management and same-project keys, you must have one of thefollowing:

• A Google Cloud project where you want to enable Autokey andwhere thekeyHandles.create permission is not blocked by anIAM deny policy.
• A Google Cloud folder where you want to enable Autokey, whichcontains at least once project where thekeyHandles.create permission isnot blocked by anIAM deny policy.

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 folder, project, or a parent resource:

• Cloud KMS Autokey Admin (roles/cloudkms.autokeyAdmin)
• Service Usage Admin (roles/serviceusage.serviceUsageAdmin)
• To enable centralized Autokey:
  • Folder IAM Admin (roles/resourcemanager.folderIamAdmin)
  • Billing Account user (roles/billing.user)

For more information about granting roles, seeManage 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 theRequired permissions section:

You might also be able to get these permissions withcustom roles or otherpredefined roles.

Decide how you want to enable Autokey

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

Set up Autokey for centralized key management

When you use Autokey for centralized key management in a folder, youneed to choose a single key project to contain all keys created byAutokey in that folder. If you are using the delegated key managementmodel (Preview), then you don't need a dedicated key project;continue fromEnable Autokey for delegated keymanagement.

We recommend creating a new key project to contain Cloud KMS resourcescreated by Autokey. You should create the key project inside yourorganization resource. If you already have a key project that you want to usefor keys created by Autokey, you can skip theCreate a keyproject section and continue fromConfigure theAutokey key project on this page.

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

If you might want to migrate toAssured Workloadsin the future, create the key project inside the same folder as the resourcesprotected by those keys.

If your organization uses theconstraints/gcp.restrictCmekCryptoKeyProjectsorganization policy constraint to ensure that all CMEKs are from specified keyprojects, you must add your key project to the list of allowed projects. Formore information about CMEK organization policy, seeCMEK organizationpolicies.

Create a key project

Prepare the Autokey key project

Enable Cloud KMS Autokey on a resource folder

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

Set up the Cloud KMS service agent

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

1. Create the Cloud KMS service agent:

   gcloudbetaservicesidentitycreate--service=cloudkms.googleapis.com\--project=PROJECT_NUMBER

   ReplacePROJECT_NUMBER with the project number of the keyproject.

   The output is similar to the following:

   Service identity created: service-PROJECT_NUMBER@gcp-sa-ekms.iam.gserviceaccount.com

   The output of the command indicates that theCloud EKMservice account (with thegcp-sa-ekms subdomain) has beencreated. However, the command also creates theCloud KMS serviceagent (with thegcp-sa-cloudkms subdomain), which isthe service agent that you use later in these instructions.

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

   gcloudprojectsadd-iam-policy-bindingPROJECT_NUMBER\--role=roles/cloudkms.admin\--member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudkms.iam.gserviceaccount.com

   ReplacePROJECT_NUMBER with the project number of the keyproject.

Enable Autokey for delegated key management

This product is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA products are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

When you use Autokey for delegated key management,Autokey creates your keys inside the same project as the resources thatthey protect. Projects that support delegated key management withAutokey can exist within folders where Autokey is enabled forcentralized key management. When Autokey is enabled on a project, theproject-level Autokey configuration overrides the Autokeyconfiguration on the parent folder.

To enable Autokey for an individual project, complete the following steps:

1. Using the REST API, create theAutokeyConfig for the project where youwant to enable Autokey:

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

   ReplacePROJECT_ID with the ID of the project where you want toenable Autokey.

2. In the gcloud CLI, enable the Cloud KMS API on the project:

   gcloudservicesenablecloudkms.googleapis.com

To enable Autokey for all projects within a folder, complete thefollowing steps:

1. Using the REST API, create theAutokeyConfig for the folder where youwant to enable Autokey to use delegated key management:

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

   ReplaceFOLDER_ID with the ID of the folder where youwant to enable Autokey. This command enables same-projectAutokey for all projects within the folder.

2. In the gcloud CLI, enable the Cloud KMS API on each projectwhere you want to use Autokey for delegated key management:

   gcloudservicesenablecloudkms.googleapis.com

   You can enable the Cloud KMS API on each project all at once, or enablethe API on individual projects as needed. Your developers can'tuse Autokey in the project until the Cloud KMS API is enabledfor that project.

Enable Autokey using Terraform

Centralized key management with 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=stringdefault="ORGANIZATION_ID"}variable"billing_account"{description="Your Google Cloud Billing Account ID"type=stringdefault="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=stringdefault="KEY_PROJECT_ID"}# Create a new folderresource"google_folder""autokey_folder"{parent="organizations/${var.organization_ID}"display_name="autokey_folder"}# Set permissions for key admins to use Autokey in this folderresource"google_folder_iam_binding""autokey_folder_admin"{folder=google_folder.autokey_folder.namerole="roles/cloudkms.autokeyAdmin"members=var.autokey_folder_admins}# Set permissions for users to protect resources with Autokey in this folderresource"google_folder_iam_binding""autokey_folder_users"{folder=google_folder.autokey_folder.namerole="roles/cloudkms.autokeyUser"members=var.autokey_folder_users}# Create a key project to store keys created by Autokeyresource"google_project""key_management_project"{project_id=var.key_management_project_IDname=var.key_management_project_IDbilling_account=var.billing_accountfolder_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 projectresource"google_project_iam_binding""autokey_project_admin"{project=google_project.key_management_project.project_idrole="roles/cloudkms.admin"members=var.autokey_project_kms_adminsdepends_on=[google_project.key_management_project]}# Enable the Cloud KMS API in the key projectresource"google_project_service""enable_api"{service="cloudkms.googleapis.com"project=google_project.key_management_project.project_iddisable_on_destroy=falsedisable_dependent_services=falsedepends_on=[google_project.key_management_project]}# Create Cloud KMS service agentresource"google_project_service_identity""KMS_Service_Agent"{provider=google-betaservice="cloudkms.googleapis.com"project=google_project.key_management_project.project_iddepends_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_idrole="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-betafolder=google_folder.autokey_folder.folder_idkey_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.}

Replace the following:

• BILLING_ACCOUNT_ID: your Google Cloud billingaccount ID. The billing account ID is an 18-character alphanumeric valueseparated by dashes—for example,010101-F0FFF0-10XX01.
• AUTOKEY_ADMIN_USER_IDS: a list of email addresses forusers that should have theroles/cloudkms.autokeyAdmin role—forexample,"Ariel@example.com", "Charlie@example.com".
• AUTOKEY_DEVELOPER_USER_IDS: a list of email addresses forusers that should have theroles/cloudkms.autokeyUser role—forexample,"Kalani@example.com", "Mahan@example.com".
• KEY_PROJECT_ADMIN_USER_IDS: a list of email addresses forusers that should have theroles/cloudkms.admin role—for example,"Sasha@example.com", "Nur@example.com".
• KEY_PROJECT_ID: the ID to use for the dedicated keyproject—for example,autokey-key-project. If you specify a keyproject, thekey_project_resolution_mode must beDEDICATED_KEY_PROJECT.

Delegated key management with Terraform

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

To enable Autokey on all projects in a folder for delegated keymanagement, use afolder_config resource similar to the following:

/* Enable AutokeyConfig on a folder */resource"google_kms_autokey_config""folder_config"{provider=google-betafolder=google_folder.autokey_folder.namekey_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.}

To enable Autokey on an individual projects for delegated keymanagement, use aautokey_config_project resource similar to the following:

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

Enforce Autokey usage

If you want to enforce usage of Autokey within a folder, you can do soby combining IAM access controls with CMEK organization policies. This works byremoving key creation permissions from principals other than theCloud KMS service agent, and then requiring that all resources areprotected 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 bemanually created, then only keys created by Autokey can be createdin this project. For more information about controlling access, seeAccess control with IAM.

2. Set an organization policy on the folder to require that resources must beprotected with a CMEK using theconstraints/gcp.restrictNonCmekServicesconstraint. For more information, seeRequire CMEK protection.

3. Set an organization policy on the folder to require that keys used for CMEKmust be from the Autokey key project using theconstraints/gcp.restrictCmekCryptoKeyProjects constraint. For moreinformation, seeLimit the use of Cloud KMS keys for CMEK.

Disable Autokey

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

After the Autokey configuration on the folder is removed, theCloud KMS service agent can no longer create keys for developers whenthey create resources in the folder. Removing the link between the folder andthe key project disables Autokey in the folder; however, werecommend that you also remove the IAM bindings for theroles/cloudkms.autokeyAdmin androles/cloudkms.autokeyUser roles.

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

Clear AutokeyConfig

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

Revoke Autokey roles

1. Optional: Revoke theroles/cloudkms.autokeyAdmin role:

   gcloudresource-managerfoldersremove-iam-policy-binding\FOLDER_ID--role=roles/cloudkms.autokeyAdmin\--member=user:USER_EMAIL

   Replace the following:

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

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

   gcloudresource-managerfoldersremove-iam-policy-binding\FOLDER_ID--role=roles/cloudkms.autokeyUser\--member=user:USER_EMAIL

   Replace the following:

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

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

   gcloudprojectsremove-iam-policy-bindingRESOURCE_PROJECT_NUMBER\--role=roles/cloudkms.autokeyUser\--member=user:USER_EMAIL

   Replace the following:

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

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

   gcloudprojectsremove-iam-policy-bindingKEY_PROJECT_NUMBER\--role=roles/cloudkms.admin\--member=serviceAccount:service-KEY_PROJECT_NUMBER@gcp-sa-cloudkms.iam.gserviceaccount.com

   ReplaceKEY_PROJECT_NUMBER with the numerical ID of the key project.

5. Optional: If you don't plan to continue using keys created inside the keyproject, revoke theroles/cloudkms.admin role for the Cloud KMSadministrator:

   gcloudprojectsremove-iam-policy-bindingKEY_PROJECT_NUMBER\--role=roles/cloudkms.admin\--member=user:KEY_ADMIN_EMAIL

   Replace the following:

   • KEY_PROJECT_NUMBER: the project number of thekey project.
   • USER_EMAIL: the email address of the user for whomyou want to revoke permission to use Autokey.

What's next

• Learn more aboutwhen to use Autokey.
• Learn more abouthow Autokey works.
• Your Autokey developers can nowcreate protected resources usingAutokey.