How do I configure a Lambda function to assume an IAM role in another AWS account?

Short description

To have your Lambda function assume an IAM role in another account, complete the following steps:

1. Configure your Lambda function's execution role to allow the function to assume an IAM role in another AWS account.
2. Modify your cross-account IAM role's trust policy to allow your Lambda function to assume the role.
3. Add the AWS Security Token Service (AWS STS) AssumeRole API call to your Lambda function's code.

Note: A Lambda function can assume an IAM role in another account to access resources, such as an Amazon Simple Storage Service (Amazon S3) bucket. The Lambda function can also assume the role to do tasks, such as start and stop instances.

Resolution

Note: The following example procedure references two types of accounts:

• A home account that hosts the Lambda function, 111111111111
• A cross account that includes the IAM role that the Lambda function assumes, 222222222222

Prerequisite

Create the IAM role that you want to use in the cross account.

Configure your Lambda function's execution role to allow the function to assume an IAM role in another account

Add the following policy statement to your Lambda function's IAM role in account 111111111111:

Note: Replace 222222222222 with the account ID of the cross-account role that your function assumes and role-on-source-account with the name of the assumed role.

{
    "Version": "2012-10-17",
    "Statement": {
        "Effect": "Allow",
        "Action": "sts:AssumeRole",
        "Resource": "arn:aws:iam::222222222222:role/role-on-source-account"
    }
}

Modify your cross-account IAM role's trust policy to allow your Lambda function to assume the role

Add the following policy statement to your cross-account IAM role's trust policy in account 222222222222:

Note: Replace 111111111111 with the account ID of the account that your Lambda function is in and my-lambda-execution-role with the name of your function's IAM role.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::111111111111:role/my-lambda-execution-role"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

Add the AWS STS AssumeRole API call to your Lambda function's code

To add the AWS STS AssumeRole API call to your function's code, complete the steps in Configuring Lambda function options.

Note: The AWS STS AssumeRole API call returns credentials that you can use to create a service client. When you use the service client, your Lambda function has the permissions that the assumed role granted. For more information, see assume_role on the AWS Boto 3 website.

Python function code example that includes the AWS STS AssumeRole API call

Note: Replace 222222222222 with the AWS account ID of the cross-account role that your function assumes and role-on-source-account with the name of the assumed role.

import boto3
def lambda_handler(event, context):
 
    sts_connection = boto3.client('sts')
    acct_b = sts_connection.assume_role(
        RoleArn="arn:aws:iam::222222222222:role/role-on-source-account",
        RoleSessionName="cross_acct_lambda"
    )

    ACCESS_KEY = acct_b['Credentials']['AccessKeyId']
    SECRET_KEY = acct_b['Credentials']['SecretAccessKey']
    SESSION_TOKEN = acct_b['Credentials']['SessionToken']

    # create service client using the assumed role credentials, e.g. S3
    client = boto3.client(
        's3',
        aws_access_key_id=ACCESS_KEY,
        aws_secret_access_key=SECRET_KEY,
        aws_session_token=SESSION_TOKEN,
    )

    return "Hello from Lambda"

Related information

Using resource-based policies for AWS Lambda

Lambda resource access permissions

Switching to an IAM role (AWS API)

Troubleshooting IAM roles

Building Lambda functions with Python