This page describes the Identity and Access Management (IAM) roles you can use to
configure Secret Manager. Roles limit a principal's ability to
access resources. Always grant the minimum set of permissions required to
perform a given task.

## Secret Manager roles

Following are the IAM roles that are associated with
Secret Manager. To learn how to grant, change, or revoke access to resources using
IAM roles, see
[Granting, changing, and revoking access to resources](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).

> [!IMPORTANT]
> **Important:** To use Secret Manager with workloads running on Compute Engine or Google Kubernetes Engine, the underlying instance or node must have the `cloud-platform` OAuth scope. See [accessing the Secret Manager API](https://docs.cloud.google.com/secret-manager/docs/accessing-the-api.md.txt#oauth-scopes) for more information.

| Role | Permissions |
|---|---|
| #### Secret Manager Admin (`roles/secretmanager.admin`) Full access to administer Secret Manager resources. Lowest-level resources where you can grant this role: - Secret | `cloudkms.keyHandles.*` - `cloudkms.keyHandles.create` - `cloudkms.keyHandles.get` - `cloudkms.keyHandles.list` `cloudkms.operations.get` `cloudkms.projects.showEffectiveAutokeyConfig` `resourcemanager.projects.get` `resourcemanager.projects.list` `secretmanager.*` - `secretmanager.backups.create` - `secretmanager.backups.delete` - `secretmanager.backups.get` - `secretmanager.backups.list` - `secretmanager.backups.restore` - `secretmanager.backups.update` - `secretmanager.locations.get` - `secretmanager.locations.list` - `secretmanager.operations.cancel` - `secretmanager.operations.get` - `secretmanager.operations.list` - `secretmanager.secrets.backup` - `secretmanager.secrets.create` - `secretmanager.secrets.createTagBinding` - `secretmanager.secrets.delete` - `secretmanager.secrets.deleteTagBinding` - `secretmanager.secrets.enableManagedRotation` - `secretmanager.secrets.get` - `secretmanager.secrets.getIamPolicy` - `secretmanager.secrets.list` - `secretmanager.secrets.listEffectiveTags` - `secretmanager.secrets.listTagBindings` - `secretmanager.secrets.restore` - `secretmanager.secrets.rotate` - `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` |
| #### Secret Manager Editor (`roles/secretmanager.editor`) Editor role for Secret Manager | `resourcemanager.projects.get` `resourcemanager.projects.list` `secretmanager.backups.create` `secretmanager.backups.delete` `secretmanager.backups.get` `secretmanager.backups.list` `secretmanager.backups.update` `secretmanager.locations.*` - `secretmanager.locations.get` - `secretmanager.locations.list` `secretmanager.operations.*` - `secretmanager.operations.cancel` - `secretmanager.operations.get` - `secretmanager.operations.list` `secretmanager.secrets.create` `secretmanager.secrets.delete` `secretmanager.secrets.enableManagedRotation` `secretmanager.secrets.get` `secretmanager.secrets.getIamPolicy` `secretmanager.secrets.list` `secretmanager.secrets.listEffectiveTags` `secretmanager.secrets.listTagBindings` `secretmanager.secrets.rotate` `secretmanager.secrets.update` `secretmanager.versions.add` `secretmanager.versions.destroy` `secretmanager.versions.disable` `secretmanager.versions.enable` `secretmanager.versions.get` `secretmanager.versions.list` |
| #### Secret Manager Secret Accessor (`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` |
| #### Secret Manager Viewer (`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.backups.get` `secretmanager.backups.list` `secretmanager.locations.*` - `secretmanager.locations.get` - `secretmanager.locations.list` `secretmanager.operations.get` `secretmanager.operations.list` `secretmanager.secrets.get` `secretmanager.secrets.getIamPolicy` `secretmanager.secrets.list` `secretmanager.secrets.listEffectiveTags` `secretmanager.secrets.listTagBindings` `secretmanager.versions.get` `secretmanager.versions.list` |
| #### Secret Manager Secret Version Adder (`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.secrets.rotate` `secretmanager.versions.add` |
| #### Secret Manager Secret Version Manager (`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.secrets.rotate` `secretmanager.versions.add` `secretmanager.versions.destroy` `secretmanager.versions.disable` `secretmanager.versions.enable` `secretmanager.versions.get` `secretmanager.versions.list` |

## Principle of least privilege

[Video](https://www.youtube.com/watch?v=8GZ6516Kao4)

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, don't 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](https://docs.cloud.google.com/iam/docs/overview.md.txt) 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](https://docs.cloud.google.com/resource-manager/docs/cloud-platform-resource-hierarchy.md.txt).

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 |

The role `roles/owner` includes the
\`secretmanager.versions.access\` permission, but the `roles/editor`
and `roles/viewer` do not.

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](https://docs.cloud.google.com/iam/docs/conditions-overview.md.txt)
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](https://docs.cloud.google.com/iam/docs/conditions-attribute-reference.md.txt#date-time)**: 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](https://docs.cloud.google.com/iam/docs/conditions-attribute-reference.md.txt#resource)**: 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](https://docs.cloud.google.com/iam/docs/conditions-overview.md.txt).

## What's next

- Learn how to [manage access to secrets](https://docs.cloud.google.com/secret-manager/docs/manage-access-to-secrets.md.txt).
- Learn how to apply the [principle of least privilege](https://docs.cloud.google.com/iam/docs/using-iam-securely.md.txt#least_privilege) when managing Secret Manager resources by [creating and managing custom roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles.md.txt).
- Learn about [IAM Conditions](https://docs.cloud.google.com/iam/docs/conditions-overview.md.txt).