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, for example 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 if you haven't already done so.

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:

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

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.

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:

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

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.

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

import boto3def 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"

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.

Related information

Managing permissions in Lambda

Switching to an IAM role (AWS API)

Troubleshooting IAM roles

Building Lambda functions with Python