Set up execution roles with Workflow Studio in Step Functions
You can use Workflow Studio to set up execution roles for your workflows. Every Step Functions state machine requires an Amazon Identity and Access Management (IAM) role which grants the state machine permission to perform actions on Amazon Web Services services and resources or call HTTPS APIs. This role is called an execution role.
The execution role must contain IAM policies for each action, for example, policies that allow the state machine to invoke an Amazon Lambda function, run an Amazon Batch job, or call the Stripe API. Step Functions requires you to provide an execution role in the following cases:
-
You create a state machine in the console, Amazon SDKs or Amazon CLI using the CreateStateMachine API.
-
You test a state in the console, Amazon SDKs, or Amazon CLI using the TestState API.
Topics
- About auto-generated roles
- Automatically generating roles
- Resolving role generation problems
- Role for testing HTTP Tasks in Workflow Studio
- Role for testing an optimized service integration in Workflow Studio
- Role for testing an Amazon SDK service integration in Workflow Studio
- Role for testing flow states in Workflow Studio
About auto-generated roles
When you create a state machine in the Step Functions console, Workflow Studio can automatically create an execution role for you which contains the necessary IAM policies. Workflow Studio analyzes your state machine definition and generates policies with the least privileges necessary to execute your workflow.
Workflow Studio can generate IAM policies for the following:
-
HTTP Tasks that call HTTPS APIs.
-
Task states that call other Amazon Web Services services using optimized integrations, such as Lambda Invoke, DynamoDB GetItem, or Amazon Glue StartJobRun.
-
Task states that run nested workflows.
-
Distributed Map states, including policies to start child workflow executions, list Amazon S3 buckets, and read or write S3 objects.
-
X-Ray tracing. Every role that is auto-generated in Workflow Studio contains a policy which grants permissions for the state machine to send traces to X-Ray.
-
Using CloudWatch Logs to log execution history in Step Functions when logging is enabled on the state machine.
Workflow Studio can't generate IAM policies for Task states that call other Amazon Web Services services using Amazon SDK integrations.
Automatically generating roles
-
Open the Step Functions console
and choose Create state machine. You can also update an existing state machine. Refer Step 4 if you're updating a state machine.
-
In the Choose a template dialog box, select Blank.
-
Choose Select to open Workflow Studio in Design mode.
-
Choose the Config tab.
-
Scroll down to the Permissions section, and do the following:
-
For Execution role, make sure you keep the default selection of Create new role.
Workflow Studio automatically generates all the required IAM policies for every valid state in your state machine definition. It displays a banner in with the message, An execution role will be created with full permissions.
Tip
To review the permissions that Workflow Studio automatically generates for your state machine, choose Review auto-generated permissions.
Note
If you delete the IAM role that Step Functions creates, Step Functions can't recreate it later. Similarly, if you modify the role (for example, by removing Step Functions from the principals in the IAM policy), Step Functions can't restore its original settings later.
If Workflow Studio can't generate all the required IAM policies, it displays a banner with the message Permissions for certain actions cannot be auto-generated. An IAM role will be created with partial permissions only. For information about how to add the missing permissions, see Resolving role generation problems.
-
Choose Create if you're creating a state machine. Otherwise, choose Save.
-
Choose Confirm in the dialog box that appears.
Workflow Studio saves your state machine and creates the new execution role.
-
Resolving role generation problems
Workflow Studio can't automatically generate an execution role with all the required permissions in the following cases:
-
There are errors in your state machine. Make sure to resolve all validation errors in Workflow Studio. Also, make sure that you address any server-side errors you encounter in the course of saving.
-
Your state machine contains tasks use Amazon SDK integrations. Workflow Studio can't auto-generate IAM policies in this case. Workflow Studio displays a banner with the message, Permissions for certain actions cannot be auto-generated. An IAM role will be created with partial permissions only. In the Review auto-generated permissions table, choose the content in Status for more information about the policies your execution role is missing. Workflow Studio can still generate an execution role, but this role will not contain IAM policies for all actions. See the links under Documentation links to write your own policies and add them to the role after it is generated. These links are available even after you save the state machine.
Role for testing HTTP Tasks in Workflow Studio
You require an execution role to test an HTTP Task state. If you don’t have a role with sufficient permissions, use one of the following options to create a role:
-
Auto-generate a role with Workflow Studio (recommended) – This is the secure option. Close the Test state dialog box and follow the instructions in Automatically generating roles. This will require you to create or update your state machine first, then go back into Workflow Studio to test your state.
-
Use a role with Administrator access – If you have permissions to create a role with full access to all services and resources in Amazon, you can use that role to test any type of state in your workflow. To do this, you can create a Step Functions service role and add the AdministratorAccess policy to it in the IAM console https://console.amazonaws.cn/iam/
.
Role for testing an optimized service integration in Workflow Studio
You require an execution role to Task states that call optimized service integrations. If you don’t have a role with sufficient permissions, use one of the following options to create a role:
-
Auto-generate a role with Workflow Studio (recommended) – This is the secure option. Close the Test state dialog box and follow the instructions in Automatically generating roles. This will require you to create or update your state machine first, then go back into Workflow Studio to test your state.
-
Use a role with Administrator access – If you have permissions to create a role with full access to all services and resources in Amazon, you can use that role to test any type of state in your workflow. To do this, you can create a Step Functions service role and add the AdministratorAccess policy to it in the IAM console https://console.amazonaws.cn/iam/
.
Role for testing an Amazon SDK service integration in Workflow Studio
You require an execution role to Task states that call Amazon SDK integrations. If you don’t have a role with sufficient permissions, use one of the following options to create a role:
-
Auto-generate a role with Workflow Studio (recommended) – This is the secure option. Close the Test state dialog box and follow the instructions in Automatically generating roles. This will require you to create or update your state machine first, then go back into Workflow Studio to test your state. Do the following:
-
Close the Test state dialog box
-
Choose the Config tab to view the Config mode.
-
Scroll down to the Permissions section.
-
Workflow Studio displays a banner with the message, Permissions for certain actions cannot be auto-generated. An IAM role will be created with partial permissions only. Choose Review auto-generated permissions.
-
The Review auto-generated permissions table displays a row that shows the action corresponding to the task state you want to test. See the links under Documentation links to write your own IAM policies into a custom role.
-
-
Use a role with Administrator access – If you have permissions to create a role with full access to all services and resources in Amazon, you can use that role to test any type of state in your workflow. To do this, you can create a Step Functions service role and add the AdministratorAccess policy to it in the IAM console https://console.amazonaws.cn/iam/
.
Role for testing flow states in Workflow Studio
You require an execution role to test flow states in Workflow Studio. Flow states are those states that direct execution flow, such as Choice workflow state, Parallel workflow state, Map workflow state, Pass workflow state, Wait workflow state, Succeed workflow state, or Fail workflow state. The TestState API doesn't work with Map or Parallel states. Use one of the following options to create a role for testing a flow state:
-
Use any role in your Amazon Web Services account (recommended) – Flow states do not require any specific IAM policies, because they don’t call Amazon actions or resources. Therefore, you can use any IAM role in your Amazon Web Services account.
-
In the Test state dialog box, select any role from the Execution role dropdown list.
-
If no roles appear in the dropdown list, do the following:
-
In the IAM console https://console.amazonaws.cn/iam/
, choose Roles. -
Choose a role from the list, and copy its ARN from the role details page. You will need to provide this ARN in the Test state dialog box.
-
In the Test state dialog box, select Enter a role ARN from the Execution role dropdown list.
-
Paste the ARN in Role ARN.
-
-
-
Use a role with Administrator access – If you have permissions to create a role with full access to all services and resources in Amazon, you can use that role to test any type of state in your workflow. To do this, you can create a Step Functions service role and add the AdministratorAccess policy to it in the IAM console https://console.amazonaws.cn/iam/
.