Permissions for the Lambda rotation function

Secrets Manager uses a Lambda function to rotate a secret. The Lambda function has a resource policy that allows Secrets Manager to invoke it. Secrets Manager calls the Lambda function by invoking an IAM execution role attached to the Lambda function. Permissions for the Lambda function are granted through the IAM execution role as inline policies. If you turn on rotation by using the Secrets Manager console, the Lambda function, resource policy, execution role, and execution role inline policies are created for you.

In the resource policy for your Lambda function, we recommend that you include the context key aws:SourceAccount to help prevent AWS Lambda from being used as a confused deputy. For some AWS services, to avoid the confused deputy scenario, AWS recommends that you use both the aws:SourceArn and aws:SourceAccount global condition keys. However, if you include the context key aws:SourceArn in your Lambda rotation function policy, the rotation function can only be used to rotate the secret specified by that ARN. We recommend that you include only the context key aws:SourceAccount so that you can use the rotation function for multiple secrets.

If you create the Lambda function another way, you must attach a resource policy to it and make sure it has the correct permissions. You also need to create an execution role and make sure it has the correct permissions.

Lambda function resource policy

The following policy allows Secrets Manager to invoke the Lambda function specified in the Resource. To attach a resource policy to a Lambda function, see Using resource-based policies for AWS Lambda.

{
  "Version": "2012-10-17",
  "Id": "default",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "secretsmanager.amazonaws.com"
      },
      "Action": "lambda:InvokeFunction",
      "Resource": "LambdaRotationFunctionARN",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "111122223333"
        }
      }
    }
  ]
}

Lambda function execution role inline policy

The following examples show inline policies for Lambda function execution roles. To create an execution role and attach a permissions policy, see AWS Lambda execution role.

Example IAM execution role inline policy for single user rotation strategy

For an Amazon RDS, Amazon DocumentDB, or Amazon Redshift secret, Secrets Manager creates the IAM execution role and attaches this policy for you.

The following example policy allows the function to:

• Run Secrets Manager operations for secrets that are configured to use this rotation function.

• Create a new password.

• Set up the required configuration if your database or service runs in a VPC. See Configuring a Lambda function to access resources in a VPC.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "secretsmanager:DescribeSecret",
                "secretsmanager:GetSecretValue",
                "secretsmanager:PutSecretValue",
                "secretsmanager:UpdateSecretVersionStage"
            ],
            "Resource": "SecretARN",
            "Condition": {
                "StringEquals": {
                    "secretsmanager:resource/AllowRotationLambdaArn": "LambdaRotationFunctionARN",
                    "aws:SourceAccount": "111122223333"
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": [
                "secretsmanager:GetRandomPassword"
            ],
            "Resource": "*"
        },
        {
            "Action": [
                "ec2:CreateNetworkInterface",
                "ec2:DeleteNetworkInterface",
                "ec2:DescribeNetworkInterfaces",
                "ec2:DetachNetworkInterface"
            ],
            "Resource": "*",
            "Effect": "Allow"
        }
    ]
}

Example IAM execution role inline policy statement for alternating users strategy

For an Amazon RDS, Amazon DocumentDB, or Amazon Redshift secret, Secrets Manager creates the IAM execution role and attaches this policy for you.

The following example policy allows the function to:

• Run Secrets Manager operations for secrets that are configured to use this rotation function.

• Retrieve the credentials in the separate secret. Secrets Manager uses the credentials in the separate secret to update the credentials in the rotated secret.

• Create a new password.

• Set up the required configuration if your database or service runs in a VPC. For more information, see Configuring a Lambda function to access resources in a VPC.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "secretsmanager:DescribeSecret",
                "secretsmanager:GetSecretValue",
                "secretsmanager:PutSecretValue",
                "secretsmanager:UpdateSecretVersionStage"
            ],
            "Resource": "SecretARN",
            "Condition": {
                "StringEquals": {
                    "secretsmanager:resource/AllowRotationLambdaArn": "LambdaRotationFunctionARN",
                    "aws:SourceAccount": "111122223333"
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": [
                "secretsmanager:GetSecretValue"
            ],
            "Resource": "SeparateSecretARN"
        },
        {
            "Effect": "Allow",
            "Action": [
                "secretsmanager:GetRandomPassword"
            ],
            "Resource": "*"
        },
        {
            "Action": [
                "ec2:CreateNetworkInterface",
                "ec2:DeleteNetworkInterface",
                "ec2:DescribeNetworkInterfaces",
                "ec2:DetachNetworkInterface"
            ],
            "Resource": "*",
            "Effect": "Allow"
        }
    ]
}

Example IAM execution role inline policy statement for customer managed key

If you use a KMS key other than the AWS managed key aws/secretsmanager to encrypt your secret, then you need to grant the Lambda execution role permission to use the key.

The following example shows a statement to add to the execution role policy to allow the function to retrieve the KMS key.

        {
            "Effect": "Allow",
            "Action": [
                "kms:Decrypt",
                "kms:GenerateDataKey"
            ],
            "Resource": "*"
        }