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. 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 Cloud Platform 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.
|Organization||Encrypt using all keys in all projects in the organization|
|Folder||Encrypt using all keys in all projects in the folder|
|Project||Encrypt using all keys in the project|
|Key ring||Encrypt using all keys on the key ring|
|Key||Encrypt using only that key|
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 offers the following predefined roles for Cloud KMS:
||Cloud KMS Admin||Provides full access to Cloud KMS resources, except encrypt and decrypt operations.||
||Cloud KMS CryptoKey Decrypter||Provides ability to use Cloud KMS resources for decrypt operations only.||
||Cloud KMS CryptoKey Encrypter||Provides ability to use Cloud KMS resources for encrypt operations only.||
||Cloud KMS CryptoKey Encrypter/Decrypter||Provides ability to use Cloud KMS resources for encrypt and decrypt operations only.||
||Cloud KMS Importer||Enables ImportCryptoKeyVersion, CreateImportJob, ListImportJobs, and GetImportJob operations||
||Cloud KMS CryptoKey Public Key Viewer||Enables GetPublicKey operations||
||Cloud KMS CryptoKey Signer||Enables the AsymmetricSign operation||
||Cloud KMS CryptoKey Signer/Verifier||Enables AsymmetricSign, and GetPublicKey operations||
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
Permissions related to the Cloud Key Management Service API begin with the string
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.
General guidelines for managing access in Cloud KMS
We recommend that you avoid using primitive project-wide roles like
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:
- Grant members of your IT security team the Cloud KMS Admin role
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 (
- Grant the Cloud KMS Encrypter / Decrypter role
roles/cloudkms.cryptoKeyEncrypterDecrypter) to users or applications that read or write encrypted data.
- Grant the Cloud KMS Public Key Viewer role
roles/cloudkms.publicKeyViewer) to users or applications that need to view the public portion of a key used for asymmetric encryption.
- Create predefined roles that match your business requirements. For example, the same user might need to monitor a project's quotas and to view log data.
- Grant members of your IT security team the Cloud KMS Admin role (
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 primitive 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
ownerrole to any member. Without the
ownerrole, 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 returns the set of permissions the caller has
been granted for that object.
- For key rings, you can invoke the
- For keys, you can invoke the
- For key import jobs, you can invoke the
You cannot set IAM permissions on a key version, so the
CryptoKeyVersion object type does not have this method.
testIamPermissions method returns a
For examples of invoking
testIamPermissions methods, see the documentation for
testing permissions in the IAM