Identity-based policies
You can attach permissions policies to IAM identities: users, user groups, and roles. In an identity-based policy, you specify which secrets the identity can access and the actions the identity can perform on the secrets. For more information, see Adding and removing IAM identity permissions.
You can grant permissions to a role that represents an application or user in another service. For example, an application running on an Amazon EC2 instance might need access to a database. You can create an IAM role attached to the EC2 instance profile and then use a permissions policy to grant the role access to the secret that contains credentials for the database. For more information, see Using an IAM role to grant permissions to applications running on Amazon EC2 instances. Other services that you can attach roles to include Amazon Redshift, AWS Lambda, and Amazon ECS.
You can also grant permissions to users authenticated by an identity system other than IAM. For example, you can associate IAM roles to mobile app users who sign in with Amazon Cognito. The role grants the app temporary credentials with the permissions in the role permission policy. Then you can use a permissions policy to grant the role access to the secret. For more information, see Identity providers and federation.
You can use identity-based policies to:
-
Grant an identity access to multiple secrets.
-
Control who can create new secrets, and who can access secrets that haven't been created yet.
-
Grant an IAM group access to secrets.
Examples:
Example: Permission to retrieve individual secret values
To grant permission to retrieve secret values, you can attach policies to secrets or identities. For help determining which type of policy to use, see Identity-based policies and resource-based policies. For information about how to attach a policy, see Resource-based policies and Identity-based policies.
This example is useful when you want to grant access to an IAM group. To grant permission to retrieve a group of secrets in a batch API call, see Example: Permission to retrieve a group of secret values in a batch.
Example Read a secret that is encrypted using a customer managed key
If a secret is encrypted using a customer managed key, you can grant access to read the secret by attaching the following policy to an identity. \
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "secretsmanager:GetSecretValue", "Resource": "SecretARN" }, { "Effect": "Allow", "Action": "kms:Decrypt", "Resource": "KMSKeyARN" } ] }
Example: Permission to read and describe individual secrets
Example Read and describe one secret
You can grant access to a secret by attaching the following policy to an identity.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:GetSecretValue", "secretsmanager:DescribeSecret" ], "Resource": "SecretARN" } ] }
Example: Permission to retrieve a group of secret values in a batch
Example Read a group of secrets in a batch
You can grant access to retrieve a group of secrets in a batch API call by attaching the following policy to an identity. The policy restricts the caller so that they can only retrieve the secrets specified by SecretARN1, SecretARN2, and SecretARN3, even if the batch call includes other secrets. If the caller also requests other secrets in the batch API call, Secrets Manager won't return them. For more information, see BatchGetSecretValue..
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:BatchGetSecretValue", "secretsmanager:ListSecrets" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "secretsmanager:GetSecretValue" ], "Resource": [ "SecretARN1", "SecretARN2", "SecretARN3" ] } ] }
Example: Wildcards
You can use wildcards to include a set of values in a policy element.
Example Access all secrets in a path
The following policy grants access to retrieve all secrets with a name beginning
with "TestEnv/".
{ "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": "secretsmanager:GetSecretValue", "Resource": "arn:aws:secretsmanager:Region:AccountId:secret:TestEnv/*" } }
Example Access metadata on all secrets
The following policy grants DescribeSecret and permissions beginning
with List: ListSecrets and
ListSecretVersionIds.
{ "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": [ "secretsmanager:DescribeSecret", "secretsmanager:List*" ], "Resource": "*" } }
Example Match secret name
The following policy grants all Secrets Manager permissions for a secret by name. To use this policy, see Identity-based policies.
To match a secret name, you create the ARN for the secret by putting together the
Region, Account ID, secret name, and the wildcard (?) to match
individual random characters. Secrets Manager appends six random characters to secret names as
part of their ARN, so you can use this wildcard to match those characters. If you
use the syntax "another_secret_name-*", Secrets Manager matches not only the
intended secret with the 6 random characters, but also matches
". another_secret_name-<anything-here>a1b2c3"
Because you can predict all of the parts of the ARN of a secret except the 6
random characters, using the wildcard character '??????' syntax enables
you to securely grant permissions to a secret that doesn't yet exist. Be aware,
however, if you delete the secret and recreate it with the same name, the user
automatically receives permission to the new secret, even though the 6 characters
changed.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "secretsmanager:*", "Resource": [ "arn:aws:secretsmanager:Region:AccountId:secret:a_specific_secret_name-a1b2c3", "arn:aws:secretsmanager:Region:AccountId:secret:another_secret_name-??????" ] } ] }
Example: Permission to create secrets
To grant a user permissions to create a secret, we recommend you attach a permissions policy to an IAM group the user belongs to. See IAM user groups.
Example Create secrets
The following policy grants permission to create secrets and view a list of secrets. To use this policy, see Identity-based policies.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:CreateSecret", "secretsmanager:ListSecrets" ], "Resource": "*" } ] }
Example: Deny a specific AWS KMS key to encrypt secrets
Important
To deny a customer managed key, we recommend you restrict access using a key policy or key grant. For more information, see Authentication and access control for AWS KMS in the AWS Key Management Service Developer Guide.
Example Deny the AWS managed key aws/secretsmanager
The following policy shows how to to deny the use of the AWS managed key aws/secretsmanager for creating or updating secrets. This means that secrets must be encrypted using a customer managed key. If the aws/secretsmanager key exists, you must also include its key ID. You also include the empty string because Secrets Manager interprets that as the AWS managed key aws/secretsmanager. The second statement denies requests to create secrets that don't include a KMS key, because Secrets Manager interprets that as the AWS managed key aws/secretsmanager.
{ "Version": "2012-10-17", "Statement": [ { "Sid": "RequireCustomerManagedKeysOnSecrets", "Effect": "Deny", "Action": [ "secretsmanager:CreateSecret", "secretsmanager:UpdateSecret" ], "Resource": "*", "Condition": { "ForAnyValue:StringLikeIfExists": { "secretsmanager:KmsKeyId": [ "*alias/aws/secretsmanager", "*<key_ID_of_the_AWS_managed_key>", "" ] } } }, { "Sid": "RequireKmsKeyIdParameterOnCreate", "Effect": "Deny", "Action": "secretsmanager:CreateSecret", "Resource": "*", "Condition": { "Null": { "secretsmanager:KmsKeyId": "true" } } } ] }
