Accessing cross-account Amazon resources in Step Functions
With the cross-account access support in Step Functions, you can share resources configured in different Amazon Web Services accounts. In this tutorial, we walk you through the process of accessing a cross-account Lambda function defined in an account called Production. This function is invoked from a state machine in an account called Development. In this tutorial, the Development account is referred to as the source account and the Production account is the target account containing the target IAM role.
To start, in your Task
state’s definition, you specify the target IAM role the
state machine must assume before invoking the cross-account Lambda function. Then, modify the
trust policy in the target IAM role to allow the source account to assume the target role
temporarily. Also, to call the Amazon resource, define the appropriate permissions in the
target IAM role. Finally, update the source account’s execution role to specify the required
permission to assume the target role.
You can configure your state machine to assume an IAM role for accessing resources
from multiple Amazon Web Services accounts. However, a state machine can assume only one IAM role at
a given time based on the Task
state’s definition.
Note
Currently, cross-Region Amazon SDK integration and cross-Region Amazon resource access aren't available in Step Functions.
Prerequisites
-
This tutorial uses the example of a Lambda function for demonstrating how to set up cross-account access. You can use any other Amazon resource, but make sure you’ve configured the resource in a different account.
Important
IAM roles and resource-based policies delegate access across accounts only within a single partition. For example, assume that you have an account in US West (N. California) in the standard
aws
partition. You also have an account in China (Beijing) in theaws-cn
partition. You can't use an Amazon S3 resource-based policy in your account in China (Beijing) to allow access for users in your standardaws
account. -
Make a note of the cross-account resource's Amazon Resource Name (ARN) in a text file. Later in this tutorial, you'll provide this ARN in your state machine's
Task
state definition. The following is an example of a Lambda function ARN:arn:aws-cn:lambda:us-west-2:123456789012:function:
functionName
-
Make sure you've created the target IAM role that the state machine needs to assume.
Step 1: Update the Task state definition to specify the target role
In the Task
state of your workflow, add a Credentials
field containing the identity the state machine must assume before invoking the
cross-account Lambda function.
The following procedure demonstrates how to access a cross-account Lambda function
called Echo
. You can call any Amazon resource by following these
steps.
-
Open the Step Functions console
and choose Create state machine. -
On the Choose authoring method page, choose Design your workflow visually and keep all the default selections.
-
To open Workflow Studio, choose Next.
On the Actions tab, drag and drop a
Task
state on the canvas. This invokes the cross-account Lambda function that's using thisTask
state.-
On the Configuration tab, do the following:
-
Rename the state to
Cross-account call
. -
For Function name, choose Enter function name, and then enter the Lambda function ARN in the box. For example,
arn:aws-cn:lambda:us-west-2:111122223333:function:
.Echo
-
For Provide IAM role ARN, specify the target IAM role ARN. For example,
arn:aws-cn:iam::111122223333:role/LambdaRole
.Tip
Alternatively, you can also specify a reference path to an existing key-value pair in the state’s JSON input that contains the IAM role ARN. To do this, choose Get IAM role ARN at runtime from state input. For an example of specifying a value by using a reference path, see .
-
-
Choose Next.
-
On the Review generated code page, choose Next.
-
On the Specify state machine settings page, specify details for the new state machine, such as a name, permissions, and logging level.
-
Choose Create state machine.
-
Make a note of the state machine's IAM role ARN and the state machine ARN in a text file. You'll need to provide these ARNs in the target account's trust policy.
Your Task
state definition should now look similar to the following definition.
{
"StartAt": "Cross-account call",
"States": {
"Cross-account call": {
"Type": "Task",
"Resource": "arn:aws-cn:states:::lambda:invoke",
"Credentials": {
"RoleArn": "arn:aws-cn:iam::111122223333:role/LambdaRole"
},
"Parameters": {
"FunctionName": "arn:aws-cn:lambda:us-west-2:111122223333:function:Echo
",
},
"End": true
}
}
}
Step 2: Update the target role's trust policy
The IAM role must exist in the target account and you must modify its trust policy to allow the source account to assume this role temporarily. Additionally, you can control who can assume the target IAM role.
After you create the trust relationship, a user from the source account can use the Amazon Security Token Service (Amazon STS) AssumeRole API operation. This operation provides temporary security credentials that enable access to Amazon resources in a target account.
-
Open the IAM console at https://console.amazonaws.cn/iam/
. -
On the navigation pane of the console, choose Roles and then use the Search box to search for the target IAM role. For example,
.LambdaRole
-
Choose the Trust relationships tab.
-
Choose Edit trust policy and paste the following trust policy. Make sure to replace the Amazon Web Services account number and IAM role ARN. The
sts:ExternalId
field further controls who can assume the role. The state machine's name must include only characters that the Amazon Security Token ServiceAssumeRole
API supports. For more information, see AssumeRole in the Amazon Security Token Service API Reference.{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "sts:AssumeRole", "Principal": { "AWS": "arn:aws-cn:iam::123456789012:role/ExecutionRole" // The source account's state machine execution role ARN }, "Condition": { // Control which account and state machine can assume the target IAM role "StringEquals": { "sts:ExternalId": "arn:aws-cn:states:us-east-1:123456789012:stateMachine:testCrossAccount" //// ARN of the state machine that will assume the role. } } } ] }
-
Keep this window open and proceed to the next step for further actions.
Step 3: Add the required permission in the target role
Permissions in the IAM policies determine whether a specific request is allowed or denied. The target IAM role must have the correct permission to invoke the Lambda function.
-
Choose the Permissions tab.
-
Choose Add permissions and then choose Create inline policy.
-
Choose the JSON tab and replace the existing content with the following permission. Make sure to replace your Lambda function ARN.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "lambda:InvokeFunction", "Resource": "arn:aws-cn:lambda:us-west-2:111122223333:function:
Echo
" // The cross-account Amazon resource being accessed } ] } -
Choose Review policy.
-
On the Review policy page, enter a name for the permission, and then choose Create policy.
Step 4: Add permission in execution role to assume the target role
Step Functions doesn’t automatically generate the AssumeRole policy for all cross-account service integrations. You must add the required permission in the state machine's execution role to allow it to assume a target IAM role in one or more Amazon Web Services accounts.
-
Open your state machine's execution role in the IAM console at https://console.amazonaws.cn/iam/
. To do this: -
Open the state machine that you created in Step 1 in the source account.
-
On the State machine detail page, choose IAM role ARN.
-
-
On the Permissions tab, choose Add permissions and then choose Create inline policy.
-
Choose the JSON tab and replace the existing content with the following permission. Make sure to replace your Lambda function ARN.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws-cn:iam::111122223333:role/
LambdaRole
" // The target role to be assumed } ] } -
Choose Review policy.
-
On the Review policy page, enter a name for the permission, and then choose Create policy.