Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Using resource-based policies for Lambda

Lambda supports resource-based permissions policies for Lambda functions and layers. Resource-based policies let you grant usage permission to other Amazon accounts or organizations on a per-resource basis. You also use a resource-based policy to allow an Amazon service to invoke your function on your behalf.

For Lambda functions, you can grant an account permission to invoke or manage a function. You can also use a single resource-based policy to grant permissions to an entire organization in Amazon Organizations. You can also use resource-based policies to grant invoke permission to an Amazon service that invokes a function in response to activity in your account.

For Lambda layers, you can only use a resource-based policy on a specific layer version, instead of the entire layer. In addition to policies that grant permission to a single account or multiple accounts, for layers, you can also grant permission to all accounts in an organization.

Resource-based policies apply to a single function, version, alias, or layer version. They grant permission to one or more services and accounts. For trusted accounts that you want to have access to multiple resources, or to use API actions that resource-based policies don't support, you can use cross-account roles.

Supported API actions

The following Lambda API actions support resource-based policies:

Granting function access to Amazon services

When you use an Amazon service to invoke your function, you grant permission in a statement on a resource-based policy. You can apply the statement to the entire function to be invoked or managed, or limit the statement to a single version or alias.

Add a statement with the add-permission command. The simplest resource-based policy statement allows a service to invoke a function. The following command grants Amazon SNS permission to invoke a function named my-function.

aws lambda add-permission --function-name my-function --action lambda:InvokeFunction --statement-id sns \
--principal sns.amazonaws.com.cn --output text

You should see the following output:

{"Sid":"sns","Effect":"Allow","Principal":{"Service":"sns.amazonaws.com.cn"},"Action":"lambda:InvokeFunction","Resource":"arn:aws-cn:lambda:cn-north-1:123456789012:function:my-function"}

This lets Amazon SNS call the lambda:Invoke API for the function, but it doesn't restrict the Amazon SNS topic that triggers the invocation. To ensure that your function is only invoked by a specific resource, specify the Amazon Resource Name (ARN) of the resource with the source-arn option. The following command only allows Amazon SNS to invoke the function for subscriptions to a topic named my-topic.

aws lambda add-permission --function-name my-function --action lambda:InvokeFunction --statement-id sns-my-topic \
--principal sns.amazonaws.com.cn --source-arn arn:aws-cn:sns:cn-north-1:123456789012:my-topic

Some services can invoke functions in other accounts. If you specify a source ARN that has your account ID in it, that isn't an issue. For Amazon S3, however, the source is a bucket whose ARN doesn't have an account ID in it. It's possible that you could delete the bucket and another account could create a bucket with the same name. Use the source-account option with your account ID to ensure that only resources in your account can invoke the function.

aws lambda add-permission --function-name my-function --action lambda:InvokeFunction --statement-id s3-account \
--principal s3.amazonaws.com.cn --source-arn arn:aws-cn:s3:::my-bucket-123456 --source-account 123456789012

Granting function access to an organization

To grant permissions to an organization in Amazon Organizations, specify the organization ID as the principal-org-id. The following AddPermission Amazon CLI command grants invocation access to all users in organization o-a1b2c3d4e5f.

aws lambda add-permission --function-name example \
--statement-id PrincipalOrgIDExample --action lambda:InvokeFunction \
--principal * --principal-org-id o-a1b2c3d4e5f 

This command creates a resource-based policy that looks like the following:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "PrincipalOrgIDExample",
            "Effect": "Allow",
            "Principal": "*",
            "Action": "lambda:InvokeFunction",
            "Resource": "arn:aws-cn:lambda:us-west-2:123456789012:function:example",
            "Condition": {
                "StringEquals": {
                    "aws:PrincipalOrgID": "o-a1b2c3d4e5f"
                }
            }
        }
    ]
}

For more information, see aws:PrincipalOrgID in the Amazon Identity and Access Management user guide.

Granting function access to other accounts

To grant permissions to another Amazon account, specify the account ID as the principal. The following example grants account 111122223333 permission to invoke my-function with the prod alias.

aws lambda add-permission --function-name my-function:prod --statement-id xaccount --action lambda:InvokeFunction \
--principal 111122223333 --output text

You should see the following output:

{"Sid":"xaccount","Effect":"Allow","Principal":{"AWS":"arn:aws-cn:iam::111122223333:root"},"Action":"lambda:InvokeFunction","Resource":"arn:aws-cn:lambda:us-east-2:123456789012:function:my-function"}

The resource-based policy grants permission for the other account to access the function, but doesn't allow users in that account to exceed their permissions. Users in the other account must have the corresponding user permissions to use the Lambda API.

To limit access to a user or role in another account, specify the full ARN of the identity as the principal. For example, arn:aws-cn:iam::123456789012:user/developer.

The alias limits which version the other account can invoke. It requires the other account to include the alias in the function ARN.

aws lambda invoke --function-name arn:aws-cn:lambda:us-west-2:123456789012:function:my-function:prod out

You should see the following output:

{
    "StatusCode": 200,
    "ExecutedVersion": "1"
}

The function owner can then update the alias to point to a new version without the caller needing to change the way they invoke your function. This ensures that the other account doesn't need to change its code to use the new version, and it only has permission to invoke the version of the function associated with the alias.

You can grant cross-account access for most API actions that operate on an existing function. For example, you could grant access to lambda:ListAliases to let an account get a list of aliases, or lambda:GetFunction to let them download your function code. Add each permission separately, or use lambda:* to grant access to all actions for the specified function.

To grant other accounts permission for multiple functions, or for actions that don't operate on a function, we recommend that you use IAM roles.

Granting layer access to other accounts

To grant layer-usage permission to another account, add a statement to the layer version's permissions policy using the add-layer-version-permission command. In each statement, you can grant permission to a single account, all accounts, or an organization.

The following example grants account 111122223333 access to version 2 of the bash-runtime layer.

aws lambda add-layer-version-permission --layer-name bash-runtime --statement-id xaccount \
--action lambda:GetLayerVersion --principal 111122223333 --version-number 2 --output text

You should see output similar to the following:

e210ffdc-e901-43b0-824b-5fcd0dd26d16    {"Sid":"xaccount","Effect":"Allow","Principal":{"AWS":"arn:aws-cn:iam::111122223333:root"},"Action":"lambda:GetLayerVersion","Resource":"arn:aws-cn:lambda:us-east-1:123456789012:layer:bash-runtime:2"}

Permissions apply only to a single layer version. Repeat the process each time that you create a new layer version.

To grant permission to all accounts in an organization, use the organization-id option. The following example grants all accounts in an organization permission to use version 3 of a layer.

aws lambda add-layer-version-permission --layer-name my-layer \
--statement-id engineering-org --version-number 3 --principal '*' \
--action lambda:GetLayerVersion --organization-id o-t194hfs8cz --output text

You should see the following output:

b0cd9796-d4eb-4564-939f-de7fe0b42236    {"Sid":"engineering-org","Effect":"Allow","Principal":"*","Action":"lambda:GetLayerVersion","Resource":"arn:aws-cn:lambda:us-east-2:123456789012:layer:my-layer:3","Condition":{"StringEquals":{"aws:PrincipalOrgID":"o-t194hfs8cz"}}}"

To grant permission to all Amazon accounts, use * for the principal, and omit the organization ID. For multiple accounts or organizations, you need to add multiple statements.

Cleaning up resource-based policies

To view a function's resource-based policy, use the get-policy command.

aws lambda get-policy --function-name my-function --output text

You should see the following output:

{"Version":"2012-10-17","Id":"default","Statement":[{"Sid":"sns","Effect":"Allow","Principal":{"Service":"s3.amazonaws.com.cn"},"Action":"lambda:InvokeFunction","Resource":"arn:aws-cn:lambda:cn-north-1:123456789012:function:my-function","Condition":{"ArnLike":{"AWS:SourceArn":"arn:aws-cn:sns:us-east-2:123456789012:lambda*"}}}]}      7c681fc9-b791-4e91-acdf-eb847fdaa0f0

For versions and aliases, append the version number or alias to the function name.

aws lambda get-policy --function-name my-function:PROD

To remove permissions from your function, use remove-permission.

aws lambda remove-permission --function-name example --statement-id sns

Use the get-layer-version-policy command to view the permissions on a layer.

aws lambda get-layer-version-policy --layer-name my-layer --version-number 3 --output text

You should see the following output:

b0cd9796-d4eb-4564-939f-de7fe0b42236    {"Sid":"engineering-org","Effect":"Allow","Principal":"*","Action":"lambda:GetLayerVersion","Resource":"arn:aws-cn:lambda:us-west-2:123456789012:layer:my-layer:3","Condition":{"StringEquals":{"aws:PrincipalOrgID":"o-t194hfs8cz"}}}"

Use remove-layer-version-permission to remove statements from the policy.

aws lambda remove-layer-version-permission --layer-name my-layer --version-number 3 --statement-id engineering-org