Access control with IAM

This document describes the access control options available to you in Secret Manager.

Assign IAM roles

Secret Manager uses Identity and Access Management (IAM) for access control. To create, manage, list, or access a secret, the appropriate IAM permissions must be granted at the project level and at the individual resource level. You can grant one or more predefined roles or create and grant custom roles. IAM roles can't be granted on a secret version.

To add a role:

  1. Go to the IAM page in the Google Cloud console.

    Go to IAM

  2. Click the Project selector list at the top of the page.

  3. In the Select from dialog that appears, select the organization for which you want to enable Secret Manager.

  4. On the IAM page, next to your username, click Edit.

  5. In the Edit permissions panel that appears, add the necessary roles.

    1. Click Add another role. Select a role to add, such as Secret Manager Secret Accessor.

    2. To add more roles, repeat the previous step. Click Save.

Identity and Access Management (IAM) roles prescribe how you can use the Secret Manager API. The following table lists each IAM role available for Secret Manager and the capabilities granted to that role.

Role Permissions

(roles/secretmanager.admin)

Full access to administer Secret Manager resources.

Lowest-level resources where you can grant this role:

  • Secret

resourcemanager.projects.get

resourcemanager.projects.list

secretmanager.*

  • secretmanager.locations.get
  • secretmanager.locations.list
  • secretmanager.secrets.create
  • secretmanager.secrets.delete
  • secretmanager.secrets.get
  • secretmanager.secrets.getIamPolicy
  • secretmanager.secrets.list
  • secretmanager.secrets.setIamPolicy
  • secretmanager.secrets.update
  • secretmanager.versions.access
  • secretmanager.versions.add
  • secretmanager.versions.destroy
  • secretmanager.versions.disable
  • secretmanager.versions.enable
  • secretmanager.versions.get
  • secretmanager.versions.list

(roles/secretmanager.secretAccessor)

Allows accessing the payload of secrets.

Lowest-level resources where you can grant this role:

  • Secret

resourcemanager.projects.get

resourcemanager.projects.list

secretmanager.versions.access

(roles/secretmanager.secretVersionAdder)

Allows adding versions to existing secrets.

Lowest-level resources where you can grant this role:

  • Secret

resourcemanager.projects.get

resourcemanager.projects.list

secretmanager.versions.add

(roles/secretmanager.secretVersionManager)

Allows creating and managing versions of existing secrets.

Lowest-level resources where you can grant this role:

  • Secret

resourcemanager.projects.get

resourcemanager.projects.list

secretmanager.versions.add

secretmanager.versions.destroy

secretmanager.versions.disable

secretmanager.versions.enable

secretmanager.versions.get

secretmanager.versions.list

(roles/secretmanager.viewer)

Allows viewing metadata of all Secret Manager resources

Lowest-level resources where you can grant this role:

  • Secret

resourcemanager.projects.get

resourcemanager.projects.list

secretmanager.locations.*

  • secretmanager.locations.get
  • secretmanager.locations.list

secretmanager.secrets.get

secretmanager.secrets.getIamPolicy

secretmanager.secrets.list

secretmanager.versions.get

secretmanager.versions.list

Principle of least privilege

When you follow the principle of least privilege, you grant the minimum level of access to resources required to perform a given task. For example, if a principal needs access to a single secret, do not give that principal access to other secrets or all secrets in the project or organization. If a principal only needs to read a secret, don't grant that principal the ability to modify the secret.

You can use IAM to grant IAM roles and permissions at the level of the Google Cloud secret, project, folder, or organization. Always apply permissions at the lowest level in the resource hierarchy.

The following table shows the effective capabilities of a service account, based on the level of the resource hierarchy where the Secret Manager Secret Accessor role (roles/secretmanager.secretAccessor) is granted.

Resource hierarchy Capability
Secret Access only that secret
Project Access all secrets in the project
Folder Access all secrets in all projects in the folder
Organization Access all secrets in all projects in the organization

If a principal only needs to access a single secret's value, don't grant that principal the ability to access all secrets. For example, you can grant a service account the Secret Manager Secret Accessor role (roles/secretmanager.secretAccessor) on a single secret.

If a principal only needs to manage a single secret, don't grant that principal the ability to manage all secrets. For example, you can grant a service account the Secret Manager Admin role (roles/secretmanager.admin) on a single secret.

IAM conditions

IAM Conditions allow you to define and enforce conditional, attribute-based access control for some Google Cloud resources, including Secret Manager resources.

In Secret Manager, you can enforce conditional access based on the following attributes:

  • Date/time attributes: Use to set expirable, scheduled, or limited-duration access to Secret Manager resources. For example, you could allow a user to access a secret until a specified date.
  • Resource attributes: Use to configure conditional access based on a resource name, resource type, or resource service attributes. In Secret Manager, you can use attributes of secrets and secret versions to configure conditional access. For example, you can allow a user to manage secret versions only on secrets that begin with a specific prefix, or allow a user to access only a specific secret version.

For more information about IAM Conditions, see the Conditions overview.

What's next