feat(stepfunctions): add grantStartExecution() (#2793)

Grant the given identity permissions to start an execution of a
state machine (`states:StartExecution`).

Author: jogold

Diff for: packages/@aws-cdk/aws-stepfunctions/lib/state-machine.ts

@@ -37,20 +37,39 @@ export interface StateMachineProps {
 }
 
 /**
- * Define a StepFunctions State Machine
+ * A new or imported state machine.
  */
-export class StateMachine extends Resource implements IStateMachine {
+abstract class StateMachineBase extends Resource implements IStateMachine {
     /**
      * Import a state machine
      */
     public static fromStateMachineArn(scope: Construct, id: string, stateMachineArn: string): IStateMachine {
-        class Import extends Resource implements IStateMachine {
+        class Import extends StateMachineBase {
             public readonly stateMachineArn = stateMachineArn;
         }
 
         return new Import(scope, id);
     }
 
+    public abstract readonly stateMachineArn: string;
+
+    /**
+     * Grant the given identity permissions to start an execution of this state
+     * machine.
+     */
+    public grantStartExecution(identity: iam.IGrantable): iam.Grant {
+        return iam.Grant.addToPrincipal({
+            grantee: identity,
+            actions: ['states:StartExecution'],
+            resourceArns: [this.stateMachineArn]
+        });
+    }
+}
+
+/**
+ * Define a StepFunctions State Machine
+ */
+export class StateMachine extends StateMachineBase {
     /**
      * Execution role of this state machine
      */

Diff for: packages/@aws-cdk/aws-stepfunctions/test/test.state-machine-resources.ts

@@ -129,4 +129,47 @@ export = {
         test.done();
     },
 
-};
+    'Can grant start execution to a role'(test: Test) {
+        // GIVEN
+        const stack = new cdk.Stack();
+        const task = new stepfunctions.Task(stack, 'Task', {
+            task: {
+                bind: () => ({ resourceArn: 'resource' })
+            }
+        });
+        const stateMachine = new stepfunctions.StateMachine(stack, 'StateMachine', {
+            definition: task
+        });
+        const role = new iam.Role(stack, 'Role', {
+            assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com')
+        });
+
+        // WHEN
+        stateMachine.grantStartExecution(role);
+
+        // THEN
+        expect(stack).to(haveResource('AWS::IAM::Policy', {
+            PolicyDocument: {
+                Statement: [
+                    {
+                        Action: 'states:StartExecution',
+                        Effect: 'Allow',
+                        Resource: {
+                            Ref: 'StateMachine2E01A3A5'
+                        }
+                    }
+                ],
+                Version: '2012-10-17',
+            },
+            PolicyName: 'RoleDefaultPolicy5FFB7DAB',
+            Roles: [
+                {
+                    Ref: 'Role1ABCC5F0'
+                }
+            ]
+        }));
+
+        test.done();
+    }
+
+};