Menu
AWS Lambda
Developer Guide

AWS Lambda Permissions Model

Your Lambda function, like other AWS resources, is private by default. Only the AWS account that created the Lambda function can access it (for example, to invoke the Lambda function or get configuration information). The function owner must grant other services and resources permissions to access the function. For example, if your Lambda function is called by Amazon S3 as the result of a bucket event, you must grant Amazon S3 permissions to invoke your Lambda function.

Regardless of how your Lambda function is invoked, AWS Lambda always executes the function. At the time you create a Lambda function, you specify an IAM role that AWS Lambda can assume to execute your Lambda function on your behalf. This role is also referred to as the execution role. If your Lambda function accesses other AWS resources during execution (for example, to create an object in an Amazon S3 bucket, to read an item from a DynamoDB table, or to write logs to CloudWatch Logs), you need to grant the execution role permissions for the specific actions that you want to perform using your Lambda function.

Before AWS Lambda can execute your Lambda function, the function must be invoked. Whether it's the event source or AWS Lambda that invokes the function, the service that invokes the Lambda function must have adequate permissions to invoke it. How the event source invokes your Lambda function depends on the event source as follows:

  • In a pull model, AWS Lambda polls the event source (for example, Amazon DynamoDB Streams) and invokes the Lambda function when events occur (for example, new records in the DynamoDB stream). In this case, you need to grant AWS Lambda service permissions to poll the event source. You can grant these permissions in the same execution role that you created for AWS Lambda to assume when executing your function.

     

  • In a push model, the event source (for example, Amazon S3 or DynamoDB) invokes the Lambda function. For example, you need to grant the Amazon S3 service permissions to invoke your function in response to an Amazon S3 bucket event.

     

    AWS Lambda supports resource policies, which are the recommended way to configure permissions for the push model. Each Lambda function has a resource policy associated with it. You can add permissions to your Lambda function resource policy allowing the event source (for example, Amazon S3 or DynamoDB) permissions to invoke the function.

    Note

    Instead of using a resource policy, you can create another IAM role that grants the event sources (for example, Amazon S3 or DynamoDB) permissions to invoke your Lambda function. However, you might find that resource policies are easier to set up and they make it easier for you to track which event sources have permissions to invoke your Lambda function.

For information about the pull/push models and event sources, see The Pull and Push Event Models: How a Lambda Function Is Invoked and Automatic Lambda Function Invocation: Using Event Sources.

This section explains the permissions you grant to the execution role and how you add permissions to a resource policy associated with your Lambda function.

Granting Permissions Using the Execution Role

The execution role must grant the permissions that your Lambda function needs. For example, suppose your Lambda function needs to access the following resources:

  • Read objects from an S3 bucket and write objects to an S3 bucket.

  • Write logs to CloudWatch Logs.

  • Write items to an Amazon DynamoDB table.

The execution role AWS Lambda assumes that to execute your Lambda function on your behalf it must have permissions for these necessary actions so that your Lambda function can access these resources.

In a pull model, AWS Lambda polls your event source, and therefore you must also grant necessary permissions in the same execution role.

Important

The user that is creating the IAM role is passing permissions to AWS Lambda to assume this role. To grant these permissions, the user must already have permissions to perform the iam:PassRole action. If an administrator user is creating this role, the user has full permissions including the iam:PassRole.

For more information about IAM roles, see Roles (Delegation and Federation) in the IAM User Guide.

When you create an IAM role, you grant permissions as follows and each IAM role has these two policies attached: an access policy and a trust policy.

Access Policy

An access policy grants permissions to the role.

For example, suppose your Lambda function writes logs to Amazon CloudWatch Logs. Then, you need to grant permissions for the following CloudWatch Logs actions to allows AWS Lambda permissions to create a log group, log stream, and write to the log stream as follows:

{
    "Statement": [
        {
            "Action": [
                "logs:CreateLogGroup",
                 "logs:CreateLogStream",
                 "logs:PutLogEvents"
            ],
            "Effect": "Allow",
            "Resource": "arn:aws:logs:*:*:*"
        }
    ]
}

In addition, in a pull model, where AWS Lambda polls the event source, you need to grant additional permissions. For example, if AWS Lambda is polling a DynamoDB stream, you grant permissions for DynamoDB actions as shown:

{
    "Statement": [
      {
      "Effect": "Allow",
          "Action": [
            "dynamodb:GetRecords",
            "dynamodb:GetShardIterator",
            "dynamodb:DescribeStream",
            "dynamodb:ListStreams"
          ],
          "Resource": "stream-arn"
        },
        {
            "Action": [
                "logs:CreateLogGroup",
                 "logs:CreateLogStream",
                 "logs:PutLogEvents"
            ],
            "Effect": "Allow",
            "Resource": "arn:aws:logs:*:*:*"
        }
    ]
}

Trust Policy

A trust policy identifies the user that can assume the role. In this case, it is the AWS Lambda service principal as shown:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "",
      "Effect": "Allow",
      "Principal": {
        "Service": "lambda.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Granting Permissions Using a Resource Policy

In a push model the event source (such as Amazon S3 or your custom application) invokes your Lambda function. In this case you add permissions to the resource policy associated with the Lambda function. AWS Lambda provides the AddPermission API to add permissions to a resource policy of your Lambda function. For more information, see AddPermission.

Note

If the user-defined application and the Lambda function it invokes belong to the same AWS account, you don't need to grant explicit permissions.

The following are some of the example resource policies resulting from using the AddPermission API. When you add permissions to the resource policy of your Lambda function using the AWS CLI or programmatically, you use the same values (for example, when granting permissions to Amazon S3, the principal is s3.amazonaws.com).

Example 1: Grant Amazon S3 Permissions to Invoke a Lambda Function

To grant Amazon S3 permissions to invoke your Lambda function, you do the following:

  • Specify s3.amazonaws.com as the principal.

  • Specify lambda:InvokeFunction as the action for which you are granting permissions.

  • Specify the bucket name ARN as the source-arn to restrict events from a specific bucket.

  • Specify the AWS account ID that owns the bucket to ensure that the specified bucket name is owned by the account.

The following is an example AWS CLI command that adds permissions to the resource policy associated with the helloworld Lambda function that allows Amazon S3 to invoke the function.

aws lambda add-permission \
--region us-west-2 \
--function-name helloworld \
--statement-id 1 \
--principal s3.amazonaws.com \
--action lambda:InvokeFunction \
--source-arn arn:aws:s3:::examplebucket \
--source-account 111111111111 \
--profile adminuser 

The AWS CLI returns a JSON script that contains a Statement attribute with value that is stringified-JSON of the permissions policy.

{
    "Statement": "{\"Condition\":{\"StringEquals\":{\"AWS:SourceAccount\":\"111111111111\"},
                   \"ArnLike\":{\"AWS:SourceArn\":\"arn:aws:s3:::examplebucket\"}},
                  \"Action\":[\"lambda:InvokeFunction\"],
                  \"Resource\":\"arn:aws:lambda:us-west-2:111111111111:function:helloworld\",
                  \"Effect\":\"Allow\",\"Principal\":{\"Service\":\"s3.amazonaws.com\"},
                  \"Sid\":\"1\"}"
}


Example 2: Grant Amazon API Gateway Permissions to Invoke Your Lambda Function

To grant Amazon API Gateway permissions to invoke your Lambda function, you do the following:

  • Specify apigateway.amazonaws.com as the principal.

  • Specify lambda:InvokeFunction as the action for which you are granting permission.

  • Specify the API Gateway endpoint ARN as the source-arn.

The following is an example AWS CLI command that adds permissions to the resource policy associated with the helloworld Lambda function that allows API Gateway to invoke the function.

aws lambda add-permission \
--region us-west-2 \
--function-name helloworld \
--statement-id 5 \
--principal apigateway.amazonaws.com \
--action lambda:InvokeFunction \
--source-arn arn:aws:execute-api:us-east-1:1234567890:nh501ngr19/*/GET/test/petstorewalkthrough/pets  \
--profile adminuser

The AWS CLI returns a JSON that contains a Statement attribute with value that is stringified-JSON of the permissions policy statement.

{
    "Statement": "{\"Condition\":{\"ArnLike\":{\"AWS:SourceArn\":\"arn:aws:execute-api:us-east-1:1234567890:nh501ngr19/*/GET/test/petstorewalkthrough/pets\"}},
                  \"Action\":[\"lambda:InvokeFunction\"],
                  \"Resource\":\"arn:aws:lambda:us-west-2:account-id:function:helloworld\",
                  \"Effect\":\"Allow\",
                  \"Principal\":{\"Service\":\"apigateway.amazonaws.com\"},
                  \"Sid\":\"5\"}"
}


Example 3: Grant Cross-account Permissions to a User Application Created by Another AWS Account

To grant cross-account permissions to another AWS account, you specify the AWS account ID as the Principal as shown in the following AWS CLI command:

aws lambda add-permission \
--region us-west-2 \
--function-name helloworld \
--statement-id 3 \
--principal 111111111111 \
--action lambda:InvokeFunction \
--profile adminuser

The AWS CLI returns a JSON that contains a Statement attribute with a value that is stringified-JSON of the permissions policy statement.

{
    "Statement": "{\"Action\":[\"lambda:InvokeFunction\"],
                   \"Resource\":\"arn:aws:lambda:us-west-2:account-id:function:helloworld\",
                   \"Effect\":\"Allow\",
                   \"Principal\":{\"AWS\":\"account-id\"},
                   \"Sid\":\"3\"}"
}