# Defining Lambda function permissions with an execution role A Lambda function's execution role is an AWS Identity and Access Management (IAM) role that grants the function permission to access AWS 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 AWS 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)](https://docs.aws.amazon.com/IAM/latest/UserGuide/roles-managingrole-editing-console.html#roles-managingrole_edit-trust-policy) in the IAM User Guide. In order for Lambda to properly assume your execution role, the role's [trust policy](#permissions-executionrole-api) must specify the Lambda service principal (`lambda.amazonaws.com`) as a trusted service. **Topics** + [ ## Creating an execution role in the IAM console ](#permissions-executionrole-console) + [ ## Creating and managing roles with the AWS CLI ](#permissions-executionrole-api) + [ ## Grant least privilege access to your Lambda execution role ](#permissions-executionrole-least-privilege) + [ # Viewing and updating permissions in the execution role ](permissions-executionrole-update.md) + [ # Working with AWS managed policies in the execution role ](permissions-managed-policies.md) + [ # Using source function ARN to control function access behavior ](permissions-source-function-arn.md) ## 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](getting-started.md#getting-started-create-function). Specifically, this execution role includes the [`AWSLambdaBasicExecutionRole` managed policy](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSLambdaBasicExecutionRole.html), which gives your function basic permissions to log events to Amazon CloudWatch Logs. You can select **Create default role** in the **Permissions** section. You can choose an existing role by selecting **Use another role** in the **Permissions** section. If your Lambda function needs additional permissions to perform tasks such as updating entries in an Amazon DynamoDB database in response to events, you can create a custom execution role with the necessary permissions. To do this, select **Use another role** in the **Permissions** section, which opens a drawer where you can customize your permissions. **To configure an execution role from Console** 1. Enter a **role name** in the Role details section. 1. In the **Policy** section, select **Use existing policy**. 1. Select the AWS managed policies that you want to attach to your role. For example, if your function needs to access DynamoDB, select the **AWSLambdaDynamoDBExecutionRole** managed policy. 1. Choose **Create role**. Alternatively, when you [create a function in the Lambda console](https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html#getting-started-create-function), 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](permissions-executionrole-update.md). ## Creating and managing roles with the AWS CLI To create an execution role with the AWS Command Line Interface (AWS 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 ``` 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: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](getting-started.md#getting-started-create-function), 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](permissions-executionrole-update.md#update-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](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege) 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 AWS 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 AWS resources for your specific use case. For more information, see [Generate policies based on access activity](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_generate-policy.html) in the *IAM User Guide*. # Viewing and updating permissions in the execution role This topic covers how you can view and update your function's [execution role](lambda-intro-execution-role.md). **Topics** + [ ## Viewing a function's execution role ](#view-execution-role) + [ ## Updating a function's execution role ](#update-execution-role) ## Viewing a function's execution role To view a function's execution role, use the Lambda console. **To view a function's execution role (console)** 1. Open the [Functions page](https://console.aws.amazon.com/lambda/home#/functions) of the Lambda console. 1. Choose the name of a function. 1. Choose **Configuration**, and then choose **Permissions**. 1. Under **Execution role**, you can view the role that's currently being used as the function's execution role. For convenience, you can view all the resources and actions that the function can access under the **Resource summary** section. You can also choose a service from the dropdown list to see all permissions related to that service. ## Updating a function's execution role You can add or remove permissions from a function's execution role at any time, or configure your function to use a different role. If your function needs access to any other services or resources, you must add the necessary permissions to the execution role. When you add permissions to your function, perform a trivial update to its code or configuration as well. This forces running instances of your function, which have outdated credentials, to stop and be replaced. To update a function's execution role, you can use the Lambda console. **To update a function's execution role (console)** 1. Open the [Functions page](https://console.aws.amazon.com/lambda/home#/functions) of the Lambda console. 1. Choose the name of a function. 1. Choose **Configuration**, and then choose **Permissions**. 1. Under **Execution role**, choose **Edit**. 1. If you want to update your function to use a different role as the execution role, choose the new role in the dropdown menu under **Existing role**. **Note** If you want to update the permissions within an existing execution role, you can only do so in the AWS Identity and Access Management (IAM) console. If you want to create a new role to use as the execution role, choose **Create a new role from AWS policy templates** under **Execution role**. Then, enter a name for your new role under **Role name**, and specify any policies you want to attach to the new role under **Policy templates**. 1. Choose **Save**. # Working with AWS managed policies in the execution role The following AWS managed policies provide permissions that are required to use Lambda features. | Change | Description | Date | | --- | --- | --- | | **[ AWSLambdaMSKExecutionRole](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/service-role/AWSLambdaMSKExecutionRole)** – Lambda added the [kafka:DescribeClusterV2](https://docs.aws.amazon.com/MSK/2.0/APIReference/v2-clusters-clusterarn.html#v2-clusters-clusterarnget) permission to this policy. | `AWSLambdaMSKExecutionRole` grants permissions to read and access records from an Amazon Managed Streaming for Apache Kafka (Amazon MSK) cluster, manage elastic network interfaces (ENIs), and write to CloudWatch Logs. | June 17, 2022 | | **[ AWSLambdaBasicExecutionRole](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole)** – Lambda started tracking changes to this policy. | `AWSLambdaBasicExecutionRole` grants permissions to upload logs to CloudWatch. | February 14, 2022 | | **[ AWSLambdaDynamoDBExecutionRole](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/service-role/AWSLambdaDynamoDBExecutionRole)** – Lambda started tracking changes to this policy. | `AWSLambdaDynamoDBExecutionRole` grants permissions to read records from an Amazon DynamoDB stream and write to CloudWatch Logs. | February 14, 2022 | | **[ AWSLambdaKinesisExecutionRole](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/service-role/AWSLambdaKinesisExecutionRole)** – Lambda started tracking changes to this policy. | `AWSLambdaKinesisExecutionRole` grants permissions to read events from an Amazon Kinesis data stream and write to CloudWatch Logs. | February 14, 2022 | | **[ AWSLambdaMSKExecutionRole](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/service-role/AWSLambdaMSKExecutionRole)** – Lambda started tracking changes to this policy. | `AWSLambdaMSKExecutionRole` grants permissions to read and access records from an Amazon Managed Streaming for Apache Kafka (Amazon MSK) cluster, manage elastic network interfaces (ENIs), and write to CloudWatch Logs. | February 14, 2022 | | **[ AWSLambdaSQSQueueExecutionRole](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/service-role/AWSLambdaSQSQueueExecutionRole)** – Lambda started tracking changes to this policy. | `AWSLambdaSQSQueueExecutionRole` grants permissions to read a message from an Amazon Simple Queue Service (Amazon SQS) queue and write to CloudWatch Logs. | February 14, 2022 | | **[ AWSLambdaVPCAccessExecutionRole](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/service-role/AWSLambdaVPCAccessExecutionRole)** – Lambda started tracking changes to this policy. | `AWSLambdaVPCAccessExecutionRole` grants permissions to manage ENIs within an Amazon VPC and write to CloudWatch Logs. | February 14, 2022 | | **[ AWSXRayDaemonWriteAccess](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/AWSXRayDaemonWriteAccess)** – Lambda started tracking changes to this policy. | `AWSXRayDaemonWriteAccess` grants permissions to upload trace data to X-Ray. | February 14, 2022 | | **[ CloudWatchLambdaInsightsExecutionRolePolicy](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/CloudWatchLambdaInsightsExecutionRolePolicy)** – Lambda started tracking changes to this policy. | `CloudWatchLambdaInsightsExecutionRolePolicy` grants permissions to write runtime metrics to CloudWatch Lambda Insights. | February 14, 2022 | | **[ AmazonS3ObjectLambdaExecutionRolePolicy](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/service-role/AmazonS3ObjectLambdaExecutionRolePolicy)** – Lambda started tracking changes to this policy. | `AmazonS3ObjectLambdaExecutionRolePolicy` grants permissions to interact with Amazon Simple Storage Service (Amazon S3) object Lambda and to write to CloudWatch Logs. | February 14, 2022 | For some features, the Lambda console attempts to add missing permissions to your execution role in a customer managed policy. These policies can become numerous. To avoid creating extra policies, add the relevant AWS managed policies to your execution role before enabling features. When you use an [event source mapping](invocation-eventsourcemapping.md) to invoke your function, Lambda uses the execution role to read event data. For example, an event source mapping for Kinesis reads events from a data stream and sends them to your function in batches. When a service assumes a role in your account, you can include the `aws:SourceAccount` and `aws:SourceArn` global condition context keys in your role trust policy to limit access to the role to only requests that are generated by expected resources. For more information, see [Cross-service confused deputy prevention for AWS Security Token Service](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html#cross-service-confused-deputy-prevention). In addition to the AWS managed policies, the Lambda console provides templates for creating a custom policy with permissions for additional use cases. When you create a function in the Lambda console, you can choose to create a new execution role with permissions from one or more templates. These templates are also applied automatically when you create a function from a blueprint, or when you configure options that require access to other services. Example templates are available in this guide's [GitHub repository](https://github.com/awsdocs/aws-lambda-developer-guide/tree/master/iam-policies). # Using source function ARN to control function access behavior It's common for your Lambda function code to make API requests to other AWS services. To make these requests, Lambda generates an ephemeral set of credentials by assuming your function's execution role. These credentials are available as environment variables during your function's invocation. When working with AWS SDKs, you don't need to provide credentials for the SDK directly in code. By default, the credential provider chain sequentially checks each place where you can set credentials and selects the first one available—usually the environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN`). Lambda injects the source function ARN into the credentials context if the request is an AWS API request that comes from within your execution environment. Lambda also injects the source function ARN for the following AWS API requests that Lambda makes on your behalf outside of your execution environment: | Service | Action | Reason | | --- | --- | --- | | CloudWatch Logs | CreateLogGroup, CreateLogStream, PutLogEvents | To store logs into a CloudWatch Logs log group | | X-Ray | PutTraceSegments | To send trace data to X-Ray | | Amazon EFS | ClientMount | To connect your function to an Amazon Elastic File System (Amazon EFS) file system | Other AWS API calls that Lambda makes outside of your execution environment on your behalf using the same execution role don't contain the source function ARN. Examples of such API calls outside the execution environment include: + Calls to AWS Key Management Service (AWS KMS) to automatically encrypt and decrypt your environment variables. + Calls to Amazon Elastic Compute Cloud (Amazon EC2) to create elastic network interfaces (ENIs) for a VPC-enabled function. + Calls to AWS services, such as Amazon Simple Queue Service (Amazon SQS), to read from an event source that's set up as an [event source mapping](invocation-eventsourcemapping.md). With the source function ARN in the credentials context, you can verify whether a call to your resource came from a specific Lambda function's code. To verify this, use the `lambda:SourceFunctionArn` condition key in an IAM identity-based policy or [service control policy (SCP)](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps.html). **Note** You cannot use the `lambda:SourceFunctionArn` condition key in resource-based policies. With this condition key in your identity-based policies or SCPs, you can implement security controls for the API actions that your function code makes to other AWS services. This has a few key security applications, such as helping you identify the source of a credential leak. **Note** The `lambda:SourceFunctionArn` condition key is different from the `lambda:FunctionArn` and `aws:SourceArn` condition keys. The `lambda:FunctionArn` condition key applies only to [event source mappings](invocation-eventsourcemapping.md) and helps define which functions your event source can invoke. The `aws:SourceArn` condition key applies only to policies where your Lambda function is the target resource, and helps define which other AWS services and resources can invoke that function. The `lambda:SourceFunctionArn` condition key can apply to any identity-based policy or SCP to define the specific Lambda functions that have permissions to make specific AWS API calls to other resources. To use `lambda:SourceFunctionArn` in your policy, include it as a condition with any of the [ARN condition operators](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html#Conditions_ARN). The value of the key must be a valid ARN. For example, suppose your Lambda function code makes an `s3:PutObject` call that targets a specific Amazon S3 bucket. You might want to allow only one specific Lambda function to have `s3:PutObject` access that bucket. In this case, your function's execution role should have a policy attached that looks like this: **Example policy granting a specific Lambda function access to an Amazon S3 resource** **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "ExampleSourceFunctionArn", "Effect": "Allow", "Action": "s3:PutObject", "Resource": "arn:aws:s3:::lambda_bucket/*", "Condition": { "ArnEquals": { "lambda:SourceFunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:source_lambda" } } } ] } ``` This policy allows only `s3:PutObject` access if the source is the Lambda function with ARN `arn:aws:lambda:us-east-1:123456789012:function:source_lambda`. This policy doesn't allow `s3:PutObject` access to any other calling identity. This is true even if a different function or entity makes an `s3:PutObject` call with the same execution role. **Note** The `lambda:SourceFunctionARN` condition key doesn't support Lambda function versions or function aliases. If you use the ARN for a particular function version or alias, your function won't have permission to take the action you specify. Be sure to use the unqualified ARN for your function without a version or alias suffix. You can also use `lambda:SourceFunctionArn` in SCPs. For example, suppose you want to restrict access to your bucket to either a single Lambda function's code or to calls from a specific Amazon Virtual Private Cloud (VPC). The following SCP illustrates this. **Example policy denying access to Amazon S3 under specific conditions** **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": [ "s3:*" ], "Resource": "arn:aws:s3:::lambda_bucket/*", "Effect": "Deny", "Condition": { "StringNotEqualsIfExists": { "aws:SourceVpc": [ "vpc-12345678" ] } } }, { "Action": [ "s3:*" ], "Resource": "arn:aws:s3:::lambda_bucket/*", "Effect": "Deny", "Condition": { "ArnNotEqualsIfExists": { "lambda:SourceFunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:source_lambda" } } } ] } ``` This policy denies all S3 actions unless they come from a specific Lambda function with ARN `arn:aws:lambda:*:123456789012:function:source_lambda`, or unless they come from the specified VPC. The `StringNotEqualsIfExists` operator tells IAM to process this condition only if the `aws:SourceVpc` key is present in the request. Similarly, IAM considers the `ArnNotEqualsIfExists` operator only if the `lambda:SourceFunctionArn` exists.