Execution roles in Workflow Studio - Amazon Step Functions
About auto-generated rolesAutomatically generating rolesResolving role generation problemsRole for testing HTTP Tasks in Workflow StudioRole for testing an optimized service integration in Workflow StudioRole for testing an Amazon SDK service integration in Workflow StudioRole for testing flow states in Workflow Studio
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Execution roles in Workflow Studio

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 and resources or call third-party APIs. This role is called an execution role. This 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.

Workflow Studio has capabilities that makes it easy to manage execution roles for your workflows.

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:

Workflow Studio can't generate IAM policies for Task states that call other Amazon Web Services using Amazon SDK integrations.

Automatically generating roles

  1. 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.

  2. In the Choose a template dialog box, select Blank.

  3. Choose Select. This opens Workflow Studio in Design mode.

  4. Choose the Config tab.

  5. Scroll down to the Permissions section, and do the following:

    1. 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.

      The Config tab that shows the Permissions section. Workflow Studio automatically generates the required IAM permissions for your state machine.
      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.

    2. Choose Create if you're creating a state machine. Otherwise, choose Save.

    3. 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're 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:

  • Use the documentation links in Workflow Studio to write your own IAM policies (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:

  • Use the documentation links in Workflow Studio to write your own IAM policies (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:

    1. Close the Test state dialog box

    2. Choose the Config tab to view the Config mode.

    3. Scroll down to the Permissions section.

    4. 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.

    5. 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, Parallel, Map, Pass, Wait, Succeed, or Fail. 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.

    1. In the Test state dialog box, select any role from the Execution role dropdown list.

    2. If no roles appear in the dropdown list, do the following:

      1. In the IAM console https://console.amazonaws.cn/iam/, choose Roles.

      2. 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.

      3. In the Test state dialog box, select Enter a role ARN from the Execution role dropdown list.

      4. 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/.