AWS services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with AWS services in China.

Identity and Access Management in Amazon Simple Workflow Service

Access to AWS Step Functions requires credentials that AWS can use to authenticate your requests. Those credentials must have permissions to access AWS resources, such as retrieving event data from other AWS resources. The following sections provide details on how you can use AWS Identity and Access Management (IAM) and Step Functions to help secure your resources by controlling who can access them:

Authentication

You can access AWS as any of the following types of identities:

Access Control

You can have valid credentials to authenticate your requests, but unless you have permissions you cannot create or access Amazon SWF resources. For example, you must have permissions to invoke AWS Lambda, Amazon Simple Notification Service (Amazon SNS), and Amazon Simple Queue Service (Amazon SQS) targets associated with your Amazon SWF rules.

The following sections describe how to manage permissions for Amazon SWF. We recommend that you read the overview first.

Basic Principles

Amazon SWF access control is based primarily on two types of permissions:

The simplest approach is to grant full account access—call any Amazon SWF action in any domain—or deny access entirely. However, IAM supports a more granular approach to access control that is often more useful. For example, you could:

Amazon SWF access control is based on the following principles:

For a summary of which regular and pseudo API parameters can be constrained by using conditions, see API Summary.

Amazon SWF IAM Policies

An IAM policy contains one or more Statement elements, each of which contains a set of elements that define the policy. For a complete list of elements and a general discussion of how to construct policies, see The Access Policy Language. Amazon SWF access control is based on the following elements:

The following section provides examples of how to construct Amazon SWF policies. For details, see String Conditions.

Amazon SWF Policy Examples

A workflow consists of multiple actors—activities, deciders, and so on. You can control access for each actor by attaching an appropriate IAM policy. This section provides some examples. The following shows the simplest case:

{
   "Version": "2012-10-17",
   "Statement" : [ {
      "Effect" : "Allow",
      "Action" : "swf:*",
      "Resource" : "arn:aws-cn:swf:*:123456789012:/domain/*"
   } ]
}        

If you attach this policy to an actor, it has full account access across all regions. You can use wildcards to have a single value represent multiple resources, actions, or regions.

For details on how to use wildcards, see Element Descriptions

The following sections show examples of policies that grant permissions in a more granular way.

Domain Permissions

If you want to restrict a department's workflows to a particular domain, you can use something like:

{
   "Version": "2012-10-17",
   "Statement": [ {
      "Effect" : "Allow",
      "Action" : "swf:*",
      "Resource" : "arn:aws-cn:swf:*:123456789012:/domain/department1"
   } ]
}           

If you attach this policy to an actor, it can call any action, but only for the department1 domain.

If you want an actor to have access to more than one domain, you can express permission for each domain separately, as follows:

{
   "Version": "2012-10-17",
   "Statement": [
      {
         "Effect" : "Allow",
         "Action" : "swf:*",
         "Resource" : "arn:aws-cn:swf:*:123456789012:/domain/department1"
      }, {
         "Effect" : "Allow",
         "Action" : "swf:*",
         "Resource" : "arn:aws-cn:swf:*:123456789012:/domain/department2"
      }
   ]
}           

If you attach this policy to an actor, it can use any Amazon SWF action in the department1 and department2 domains. You can also sometimes use wildcards to represent multiple domains.

API Permissions and Constraints

You control which actions an actor can use with the Action element. Optionally, you can constrain the action's allowable parameter values by using a Condition element.

If you want to restrict an actor to only certain actions, you can use something like the following:

{
   "Version": "2012-10-17",
   "Statement": [ {
      "Effect" : "Allow",
      "Action" : "swf:StartWorkflowExecution",
      "Resource" : "arn:aws-cn:swf:*:123456789012:/domain/department2"
   } ]
}           

If you attach this policy to an actor, it can call StartWorkflowExecution to start workflows in the department2 domain. It can't use any other actions or start workflows in any other domains.

You can further restrict which workflows an actor can start by constraining one or more of the StartWorkflowExecution parameter values, as follows:

{
   "Version": "2012-10-17",
   "Statement": [
      {
         "Effect" : "Allow",
         "Action" : "swf:StartWorkflowExecution",
         "Resource" : "arn:aws-cn:swf:*:123456789012:/domain/department1",
         "Condition" : {
            "StringEquals" : { 
               "swf:workflowType.name" : "workflow1",
               "swf:workflowType.version" : "version2" 
            }
         }
      }
   ]
}           

This policy constrains the StartWorkflowExecution action's name and version parameters. If you attach the policy to an actor, it can run only version2 of workflow1 in the department1 domain and both parameters must be included in the request.

You can constrain a parameter without requiring it to be included in a request by using a StringEqualsIfExists operator, as follows:

{
   "Version": "2012-10-17",
   "Statement" : [ {
      "Effect" : "Allow",
      "Action" : "swf:StartWorkflowExecution",
      "Resource" : "arn:aws-cn:swf:*:123456789012:/domain/some_domain",
      "Condition" : {
         "StringEqualsIfExists" : { "swf:taskList.name" : "task_list_name" }
      }
   } ]
}           

This policy allows an actor to optionally specify a task list when starting a workflow execution.

You can constrain a list of tags for some actions. In that case, each tag has a separate key, so you use swf:tagList.member.0 to constrain the first tag in the list, swf:tagList.member.1 to constrain the second tag in the list, and so on, up to a maximum of 5. However, you must be careful how you constrain tag lists. For instance, here is an example of a policy that is not recommended:

{
   "Version": "2012-10-17",
   "Statement" : [ {
      "Effect" : "Allow",
      "Action" : "swf:StartWorkflowExecution",
      "Resource" : "arn:aws-cn:swf:*:123456789012:/domain/some_domain",
      "Condition" : {
         "StringEqualsIfExists" : {
            "swf:tagList.member.0" : "some_ok_tag", "another_ok_tag"
         }
      }
   } ]
}           

This policy allows you to optionally specify either some_ok_tag or another_ok_tag. However, this policy constrains only the first element of the tag list. The list could have additional elements with arbitrary values that would all be allowed because this policy doesn't apply any conditions to swf:tagList.member.1, swf:tagList.member.2, and so on .

One way to address this issue is to disallow the use of tag lists. The following policy ensures that only some_ok_tag or another_ok_tag are allowed by requiring the list to have only one element.

{
   "Version": "2012-10-17",
   "Statement" : [ {
      "Effect" : "Allow",
      "Action" : "swf:StartWorkflowExecution",
      "Resource" : "arn:aws-cn:swf:*:123456789012:/domain/some_domain",
      "Condition" : {
         "StringEqualsIfExists" : {
            "swf:tagList.member.0" : "some_ok_tag", "another_ok_tag"
         },
         "Null" : { "swf:tagList.member.1" : "true" }
      }
   } ]
}          

Pseudo API Permissions and Constraints

If you want to restrict the decisions available to RespondDecisionTaskCompleted, you must first allow the actor to call RespondDecisionTaskCompleted. You can then express permissions for the appropriate pseudo API members by using the same syntax as for the regular API, as follows:

{
   "Version": "2012-10-17",
   "Statement" : [
      {
         "Resource" : "arn:aws-cn:swf:*:123456789012:/domain/*",
         "Action" : "swf:RespondDecisionTaskCompleted",
         "Effect" : "Allow"
      }, {
         "Resource" : "*",
         "Action" : "swf:ScheduleActivityTask",
         "Effect" : "Allow",
         "Condition" : {
            "StringEquals" : { "swf:activityType.name" : "SomeActivityType" }
         }
      }
   ]
}           

If you attach this policy to an actor, the first Statement element allows the actor to call RespondDecisionTaskCompleted. The second element allows the actor to use the ScheduleActivityTask decision to direct Amazon SWF to schedule an activity task. To allow all decisions, replace "swf:ScheduleActivityTask" with "swf:*".

You can use Condition operators to constrain parameters just as with the regular API. The StringEquals operator in this Condition allows RespondDecisionTaskCompleted to schedule an activity task for the SomeActivityType activity, and it must schedule that task. If you want to allow RespondDecisionTaskCompleted to use a parameter value but not require it to do so, you can instead use the StringEqualsIfExists operator.

Service Model Limitations on IAM Policies

You must consider service model constraints when creating IAM policies. It is possible to create a syntactically valid IAM policy that represents an invalid Amazon SWF request; a request that is allowed in terms of access control can still fail because it is an invalid request.

For instance, the following policy for ListOpenWorkflowExecutions is not recommended:

{
   "Version": "2012-10-17",
   "Statement" : [ {
      "Effect" : "Allow",
      "Action" : "swf:ListOpenWorkflowExecutions",
      "Resource" : "arn:aws-cn:swf:*:123456789012:/domain/domain_name",
      "Condition" : {
         "StringEquals" : { 
            "swf:typeFilter.name" : "workflow_name",
            "swf:typeFilter.version" : "workflow_version",
            "swf:tagFilter.tag" : "some_tag" 
         }
      }
   } ]
}        

The Amazon SWF service model doesn't allow the typeFilter and tagFilter parameters to be used in the same ListOpenWorkflowExecutions request. The policy therefore allows calls that the service will reject—by throwing ValidationException—as an invalid request.

API Summary

This section briefly describes how you can use IAM policies to control how an actor can use each API and pseudo API to access Amazon SWF resources.

The following sections list the parameters that can be constrained for each member of the regular and pseudo API and provide the associated key, and note any limitations on how you can control domain access.

Regular API

This section lists the regular API members, and briefly describes the parameters that can be constrained and the associated keys. It also notes any limitations on how you can control domain access.

CountClosedWorkflowExecutions

CountOpenWorkflowExecutions

CountPendingActivityTasks

CountPendingDecisionTasks

DeprecateActivityType

DeprecateDomain

DeprecateWorkflowType

DescribeActivityType

DescribeDomain

DescribeWorkflowExecution

DescribeWorkflowType

GetWorkflowExecutionHistory

ListActivityTypes

ListClosedWorkflowExecutions

ListDomains

ListOpenWorkflowExecutions

ListWorkflowTypes

PollForActivityTask

PollForDecisionTask

RecordActivityTaskHeartbeat

RegisterActivityType

RegisterDomain

RegisterWorkflowType

RequestCancelWorkflowExecution

RespondActivityTaskCanceled

RespondActivityTaskCompleted

RespondActivityTaskFailed

RespondDecisionTaskCompleted

SignalWorkflowExecution

StartWorkflowExecution

TerminateWorkflowExecution

Pseudo API

This section lists the members of the pseudo API, which represent the decisions included in RespondDecisionTaskCompleted. If you have granted permission to use RespondDecisionTaskCompleted, your policy can express permissions for the members of this API in the same way as the regular API. You can further restrict some members of the pseudo-API by setting conditions on one or more parameters. This section lists the pseudo API members, and briefly describes the parameters that can be constrained and the associated keys.

CancelTimer

CancelWorkflowExecution

CompleteWorkflowExecution

ContinueAsNewWorkflowExecution

FailWorkflowExecution

RecordMarker

RequestCancelActivityTask

RequestCancelExternalWorkflowExecution

ScheduleActivityTask

SignalExternalWorkflowExecution

StartChildWorkflowExecution

StartTimer