Defining Lambda function permissions with an execution role
A Lambda function's execution role is an Amazon Identity and Access Management (IAM) role that grants the function permission to access Amazon Web Services services and resources. For example, you might create an execution role that has permission to send logs to Amazon CloudWatch and upload trace data to Amazon X-Ray. This page provides information on how to create, view, and manage a Lambda function's execution role.
Lambda automatically assumes your execution role when you invoke your function. You should avoid manually
calling sts:AssumeRole
to assume the execution role in your function code. If your use case requires
that the role assumes itself, you must include the role itself as a trusted principal in your role's trust policy.
For more information on how to modify a role trust policy, see
Modifying a role trust policy (console) in the IAM User Guide.
In order for Lambda to properly assume your execution role, the role's
trust policy must specify the Lambda service principal
(lambda.amazonaws.com
) as a trusted service.
Topics
- Creating an execution role in the IAM console
- Creating and managing roles with the Amazon CLI
- Grant least privilege access to your Lambda execution role
- Viewing and updating permissions in the execution role
- Working with Amazon managed policies in the execution role
- Using source function ARN to control function access behavior
Creating an execution role in the IAM console
By default, Lambda creates an execution role with minimal permissions when you create a function in the Lambda console. Specifically,
this execution role includes the AWSLambdaBasicExecutionRole
managed policy, which gives your function
basic permissions to log events to Amazon CloudWatch Logs.
Your functions typically need additional permissions to perform more meaningful tasks. For example, you might have a Lambda function that responds to an event by updating entries in an Amazon DynamoDB database. You can create an execution role with the necessary permissions using the IAM console.
To create an execution role in the IAM console
-
Open the Roles page
in the IAM console. -
Choose Create role.
-
Under Trusted entity type, choose Amazon service.
-
Under Use case, choose Lambda.
-
Choose Next.
-
Select the Amazon managed policies that you want to attach to your role. For example, if your function needs to access DynamoDB, select the AWSLambdaDynamoDBExecutionRole managed policy.
-
Choose Next.
-
Enter a Role name and then choose Create role.
For detailed instructions, see Creating a role for an Amazon service (console) in the IAM User Guide.
After you create your execution role, attach it to your function. When you create a function in the Lambda console, you can attach any execution role that you previously created to the function. If you want to attach a new execution role to an existing function, follow the steps in Updating a function's execution role.
Creating and managing roles with the Amazon CLI
To create an execution role with the Amazon Command Line Interface (Amazon CLI), use the create-role command. When using this command, you can specify the trust policy inline. A role's trust policy gives the specified principals permission to assume the role. In the following example, you grant the Lambda service principal permission to assume your role. Note that requirements for escaping quotes in the JSON string may vary depending on your shell.
aws iam create-role \ --role-name lambda-ex \ --assume-role-policy-document '{"Version": "2012-10-17","Statement": [{ "Effect": "Allow", "Principal": {"Service": "lambda.amazonaws.com"}, "Action": "sts:AssumeRole"}]}'
You can also define the trust policy for the role using a separate JSON file. In the following example,
trust-policy.json
is a file in the current directory.
Example trust-policy.json
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "lambda.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }
aws iam create-role \ --role-name lambda-ex \ --assume-role-policy-document file://trust-policy.json
You should see the following output:
{ "Role": { "Path": "/", "RoleName": "lambda-ex", "RoleId": "AROAQFOXMPL6TZ6ITKWND", "Arn": "arn:aws-cn:iam::123456789012:role/lambda-ex", "CreateDate": "2020-01-17T23:19:12Z", "AssumeRolePolicyDocument": { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "lambda.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } } }
To add permissions to the role, use the attach-policy-to-role command. The following
command adds the AWSLambdaBasicExecutionRole
managed policy to the lambda-ex
execution role.
aws iam attach-role-policy --role-name lambda-ex --policy-arn arn:aws-cn:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
After you create your execution role, attach it to your function. When you create a function in the Lambda console, you can attach any execution role that you previously created to the function. If you want to attach a new execution role to an existing function, follow the steps in Updating a function's execution role.
Grant least privilege access to your Lambda execution role
When you first create an IAM role for your Lambda function during the development phase, you might sometimes grant permissions beyond what is required. Before publishing your function in the production environment, as a best practice, adjust the policy to include only the required permissions. For more information, see Apply least-privilege permissions in the IAM User Guide.
Use IAM Access Analyzer to help identify the required permissions for the IAM execution role policy. IAM Access Analyzer reviews your Amazon CloudTrail logs over the date range that you specify and generates a policy template with only the permissions that the function used during that time. You can use the template to create a managed policy with fine-grained permissions, and then attach it to the IAM role. That way, you grant only the permissions that the role needs to interact with Amazon resources for your specific use case.
For more information, see Generate policies based on access activity in the IAM User Guide.