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

4 minute read

I want my AWS Lambda function to assume an AWS Identity and Access Management (IAM) role in another AWS account.

Short description

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

Configure your Lambda function's execution role to allow the function to assume an IAM role in another AWS account.
Update your cross-account IAM role's trust policy to allow your Lambda function to assume the role.
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 Amazon Elastic Compute Cloud (Amazon EC2) 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/cross-account-role"
    }
}

Note: Replace 222222222222 with the account ID of the cross-account role that your function assumes and cross-account-role 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 functions.

Because Lambda reuses the execution environment for warm invocations, temporary credentials returned by AssumeRole become stale between invocations. Don't store credentials in global variables without a refresh mechanism because later invocations fail with an ExpiredToken error. Call AssumeRole inside the handler on every invocation or cache the credentials and refresh only when they're near expiration. For more information, see Understanding the Lambda execution environment lifecycle.

Note: The AWS STS AssumeRole API call returns credentials used 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 boto3
def lambda_handler(event, context):

    sts_connection = boto3.client('sts')
    acct_b = sts_connection.assume_role(
        RoleArn="arn:aws:iam::222222222222:role/cross-account-role",
        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 cross-account-role with the name of the assumed role.