In Cloud KMS, resources are organized into a hierarchy. This hierarchy helps you manage and grant access to resources at various levels of granularity. Keys are contained within key rings, and key rings exist within a project. EKM connections also exist within a project. Projects can be further organized into folders or organizations.
This topic provides more details about the hierarchy of resources within Cloud KMS. To learn more about Google Cloud resources in general, see Resource hierarchy.
The scope of an IAM role changes depending on the level of the resource
hierarchy where the role is granted. This table shows the effective capabilities
granted by the Cloud KMS CryptoKey Encrypter role
(roles/cloudkms.cryptoKeyEncrypter) at different levels of the hierarchy.
You can manage access to keys or key rings, but not to individual key versions.
IAM helps enforce the interrelated security principles of separation of duties and least privilege:
When you enforce the principle of separation of duties, no single member has all of the access required to complete a critical business function. For example, a bank teller can only withdraw funds from an account when the account holder is physically present and initiates the transaction.
When you enforce the principle of least privilege, a member has only the minimum level of access required to complete that member's specific business functions. For example, a bank teller is not automatically granted the ability to approve a customer loan.
IAM provides predefined roles that grant access for each kind of Google Cloud resources. If no predefined role meets your needs, you can create a custom role.
IAM offers the following predefined roles for Cloud KMS:
| Role | Permissions |
|---|---|
Cloud KMS Admin( Provides access to Cloud KMS resources, except for access to restricted resource types and cryptographic operations. Lowest-level resources where you can grant this role:
|
|
Cloud KMS CryptoKey Encrypter/Decrypter( Provides ability to use Cloud KMS resources for encrypt and decrypt operations only. Lowest-level resources where you can grant this role:
|
|
Cloud KMS Viewer( Enables Get and List operations. Lowest-level resources where you can grant this role:
|
|
Cloud KMS Autokey Admin( Enables management of AutokeyConfig. |
|
Cloud KMS Autokey User( Grants ability to use KeyHandle resources. |
|
Cloud KMS CryptoKey Decrypter( Provides ability to use Cloud KMS resources for decrypt operations only. Lowest-level resources where you can grant this role:
|
|
Cloud KMS CryptoKey Decrypter Via Delegation( Enables Decrypt operations via other Google Cloud services Lowest-level resources where you can grant this role:
|
|
Cloud KMS CryptoKey Encrypter( Provides ability to use Cloud KMS resources for encrypt operations only. Lowest-level resources where you can grant this role:
|
|
Cloud KMS CryptoKey Encrypter/Decrypter Via Delegation( Enables Encrypt and Decrypt operations via other Google Cloud services Lowest-level resources where you can grant this role:
|
|
Cloud KMS CryptoKey Encrypter Via Delegation( Enables Encrypt operations via other Google Cloud services Lowest-level resources where you can grant this role:
|
|
Cloud KMS Crypto Operator( Enables all Crypto Operations. Lowest-level resources where you can grant this role:
|
|
Cloud KMS CryptoKey Decapsulator Beta( Enables Decapsulate and GetPublicKey operations |
|
Cloud KMS EkmConnections Admin( Enables management of EkmConnections. |
|
Cloud KMS Encryption Dashboard Viewer( Enables viewing KMS encryption dashboard. |
|
Cloud KMS Expert PQ Asymmetric Signing Key Manager( Enables PQ asymmetric signing key management. |
|
Cloud KMS Expert Raw AES-CBC Key Manager( Enables raw AES-CBC keys management. Lowest-level resources where you can grant this role:
|
|
Cloud KMS Expert Raw AES-CTR Key Manager( Enables raw AES-CTR keys management. Lowest-level resources where you can grant this role:
|
|
Cloud KMS Expert Raw PKCS#1 Key Manager( Enables raw PKCS#1 keys management. Lowest-level resources where you can grant this role:
|
|
Cloud KMS single-tenant HSM Executor( Grants ability to execute SingleTenantHsmInstanceProposal resources. |
|
Cloud KMS single-tenant HSM Key Creator( Grants ability to use single-tenant HSM instances to create keys. This role must be combined with another role that grants the ability to create cryptoKeys. |
|
Cloud KMS single-tenant HSM Proposer( Grants ability to create SingleTenantHsmInstances and SingleTenantHsmInstanceProposals. |
|
Cloud KMS single-tenant HSM Quorum Member( Grants ability to approve SingleTenantHsmInstanceProposal resources. |
|
Cloud KMS Importer( Enables ImportCryptoKeyVersion, CreateImportJob, ListImportJobs, and GetImportJob operations |
|
Key Access Justifications Enrollment Viewer( Grant ability to view Key Access Justification enrollment configs of a project. |
|
Key Access Justifications Policy Config Admin( Grant ability to manage Key Access Justifications Policy at parent resource level. |
|
Cloud KMS Protected Resources Viewer( Enables viewing protected resources. |
|
Cloud KMS CryptoKey Public Key Viewer( Enables GetPublicKey operations Lowest-level resources where you can grant this role:
|
|
Cloud KMS CryptoKey Signer( Enables Sign operations Lowest-level resources where you can grant this role:
|
|
Cloud KMS CryptoKey Signer/Verifier( Enables Sign, Verify, and GetPublicKey operations Lowest-level resources where you can grant this role:
|
|
Cloud KMS CryptoKey Verifier( Enables Verify and GetPublicKey operations Lowest-level resources where you can grant this role:
|
|
Service agent roles should only be granted to service agents.
| Role | Permissions |
|---|---|
Cloud KMS Organization Service Agent( Gives Cloud KMS organization-level service account access to managed resources. |
|
Cloud KMS Service Agent( Gives Cloud KMS service account access to managed resources. |
|
Cloud KMS KACLS Service Agent( Grants Cloud KMS KACLS Service Agent access to KMS resource permissions to perform DEK encryption/decryption. |
|
In addition to predefined roles, you can create custom roles. Custom roles allow you to enforce the principle of least privilege by granting the role the minimum permissions required to perform a given task.
A custom role includes one or more of the permissions listed in the
IAM reference.
Permissions related to the Cloud Key Management Service API begin with the string cloudkms.
For more information, see
Support levels for permissions in custom roles.
For information about the permissions required to invoke a specific Cloud Key Management Service API method, see that method's API reference.
We recommend that you avoid using basic project-wide roles like owner,
editor, and viewer. These roles do not separate the ability to manage keys
from the ability to use the keys for cryptographic operations, and are not
recommended for production environments. Instead, use predefined roles or create
custom roles that reflect your business requirements.
The following examples help illustrate some good security guidelines:
For a large or complex organization, you might decide on an approach like the following:
roles/cloudkms.admin) across all projects. If different team members
handle different aspects of a key's lifecycle, you can grant those team
members a more granular role, like the Cloud KMS Importer role
(roles/cloudkms.importer).roles/cloudkms.cryptoKeyEncrypterDecrypter) to users or applications
that read or write encrypted data.roles/cloudkms.publicKeyViewer) to users or applications that need to
view the public portion of a key used for asymmetric encryption.For a small organization with simple security requirements, you might choose
to take a simpler approach by granting a broad role such as
Organization Admin (roles/resourcemanager.organizationAdmin).
However, this approach might not scale with your ongoing requirements.
Consider hosting your keys in a separate Google Cloud project from the
data protected by those keys. A user with a basic or highly privileged role
in one project, such as editor, cannot use this role to gain unauthorized
access to keys in a different project.
Avoid granting the owner role to any member. Without the owner role, no
member in the project can both create a key and use it to decrypt data or for
signing, unless each of these permissions is granted to that member. To grant
broad administrative access without granting the ability to encrypt or
decrypt, grant the Cloud KMS Admin role (roles/cloudkms.admin) role instead.
To limit access to encrypted data, such as customer data, you can restrict who can access the key and who can use the key for decryption. If necessary, you can create granular custom roles to meet your business requirements.
For each Cloud KMS object type for which you can set granular
IAM permissions, that object has a testIamPermissions method.
The testIamPermissions method returns the set of permissions the caller has
been granted for that object.
cloudkms.keyRings.testIamPermissions
method.cloudkms.cryptoKeys.testIamPermissions
method.cloudkms.keyRings.importJobs.testIamPermissions
method.cloudkms.ekmConnections.testIamPermissions
method.You cannot set IAM permissions on a key version, so the
CryptoKeyVersion object type does not have this method.
An object's testIamPermissions method returns a
TestIamPermissionsResponse.
For examples of invoking testIamPermissions methods, see the documentation for
testing permissions in the IAM
documentation.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-06-09 UTC.