Provide more grant APIs for the StateMachine construct

[jindriago-scf]

Like StateMachine#grantStartExecution, be able to have a StateMachine#grantDescribeExecution

Use Case

In order to improve readability and have a standard way of give permissions over a StateMachine
As a devops
I'll want to give permission to describe an execution to an aws resource

Proposed Solution

First create an executionArn, like the stateMachineArn, this because the arn are different when giving permissions.
for example:
arn:aws:states:us-east-1:1234567890:stateMachine:StateMachineExample
arn:aws:states:us-east-1:1234567890:execution:StateMachineExample

Then create a method grantDescribeExecution and use the executionArn.

something like this:

abstract class StateMachineBase extends Resource implements IStateMachine {
    // ...
    public abstract readonly stateMachineArn: string;
    public abstract readonly executionArn: 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]
        });
    }
    public grantDescribeExecution(identity: iam.IGrantable): iam.Grant {
        return iam.Grant.addToPrincipal({
            grantee: identity,
            actions: ['states:DescribeExecution'],
            resourceArns: [this.executioArn, "*"] // this I'm not sure because could be a better way?     
            // the idea is to have something like this arn:aws:states:us-east-1:123456:execution:StateMachineExample:*
        });
    }
}

and

export class StateMachine extends StateMachineBase {
    /**
     * The ARN of the state machine
     */
    public readonly stateMachineArn: string;
    /**
     * The ARN of the state machine execution
     */
    public abstract readonly executionArn: string;
    constructor(scope: Construct, id: string, props: StateMachineProps) {
        // ...
        this.stateMachineName = this.getResourceNameAttribute(resource.attrName);
        this.stateMachineArn = this.getResourceArnAttribute(resource.ref, {
          service: 'states',
          resource: 'stateMachine',
          resourceName: this.physicalName,
          sep: ':',
        });

        this.executionArn = this.getResourceArnAttribute(resource.ref, {
          service: 'states',
          resource: 'execution',
          resourceName: this.physicalName,
          sep: ':',
        });
    }

On the other hand and not totally related, this could be done also:

    public grantSendTaskSuccess(identity: iam.IGrantable): iam.Grant {
        return iam.Grant.addToPrincipal({
            grantee: identity,
            actions: ['states:SendTaskSuccess'],
            resourceArns: [this.stateMachineArn]
        });
    }
    public grantSendTaskFailure(identity: iam.IGrantable): iam.Grant {
        return iam.Grant.addToPrincipal({
            grantee: identity,
            actions: ['states:SendTaskFailure'],
            resourceArns: [this.stateMachineArn]
        });
    }

Other

• 👋 I may be able to implement this feature request
• ⚠️ This feature might incur a breaking change

---

This is a 🚀 Feature Request

[nija-at]

I would re-shape these APIs to be -

1. a grantRead() which provides Describe, List and a number of other read operations,
2. a grantTaskResponse() (or something similar) that provides both SendTaskSuccess, SendTaskFailure and SendTaskHeartbeat that allow for the task to report its status, and
3. a general grant() API that takes a list of string IAM action names that can be used by the user for fine-grained control.

[jindriago-scf]

Oh yeah! Good call Niranjan.

Points 1. and 2. makes all more sense.

The only thing to consider when implementing the 3rd point is that, some IAM actions goes over the states resource and some goes over the execution.
So I see 2 possibilities of implementation for point 3:

1. 2 grants API, one for the executions and other for the state machine. grant_over_states() grant_over_execution(), or
2. receive the actions in this grant() API and internally assign it to the correct arn.

[ospfranco]

Maybe off-topic but I'm not finding much information out there, how can one achieve this right now? manually creating an IAM role and attaching the permissions?

[jindriago-scf]

Hi @ospfranco ,
We made it like the example above. First we extended the StateMachine implementation and then used instead the original stepfunctions.StateMachine with the new permissions in order to not do it every single time.

class StateMachine(stepfunctions.StateMachine):

    def __init__(
            self,
            scope: core.Construct,
            id_: str,
            definition: IChainable,
            role: Optional[iam.IRole] = None,
            state_machine_name: Optional[str] = None,
            state_machine_type: Optional[StateMachineType] = None,
            timeout: Optional[core.Duration] = None) -> None:
        super().__init__(
            scope=scope,
            id=id_,
            definition=definition,
            timeout=timeout,
            role=role,
            state_machine_name=state_machine_name,
            state_machine_type=state_machine_type
        )
        self.execution_arn = core.Arn.format(
            components=core.ArnComponents(
                resource="execution",
                service="states",
                account=self.stack.account,
                partition=self.stack.partition,
                region=self.stack.region,
                resource_name=self.state_machine_name,
                sep=":"
            ),
            stack=self.stack)

    def grant_describe_execution(
            self,
            identity: iam.IGrantable) -> iam.Grant:
        return iam.Grant.add_to_principal(
            grantee=identity,
            actions=[Action.DESCRIBE_EXECUTION.value],
            resource_arns=[f"{self.execution_arn}:*"]
        )

    def grant_send_task_success_token(
            self,
            identity: iam.IGrantable) -> iam.Grant:
        return iam.Grant.add_to_principal(
            grantee=identity,
            actions=[Action.SEND_TASK_SUCCESS.value],
            resource_arns=[self.state_machine_arn]
        )

    def grant_send_task_failure_token(
            self,
            identity: iam.IGrantable) -> iam.Grant:
        return iam.Grant.add_to_principal(
            grantee=identity,
            actions=[Action.SEND_TASK_FAILURE.value],
            resource_arns=[self.state_machine_arn]
        )

And we use it like this:

class ExampleStateMachine(StateMachine):
    ARN_ENV_VAR = "EXAMPLE_STEP_FUNCTION"

    def __init__(self,
                 scope: core.Construct,
                 example_lambda: ExampleLambda) -> None:
        example_state = LambdaTask( # this is also our extension of a Task
            scope=scope,
            task_id="ExampleState",
            lambda_function=example_state,
            timeout=core.Duration.minutes(5))

        definition = example_state

        super().__init__(
            scope=scope,
            id_="ExampleStateMachine",
            definition=definition,
            timeout=core.Duration.minutes(5))

Then to instance the state machine:

example_state_machine = ExampleStateMachine(
            scope=self,
            example_lambda=example_lambda)

And to grant the permission:

        example_state_machine.grant_start_execution(
            identity=lambda_who_call_the_state_machine.grant_principal)
        example_state_machine.grant_describe_execution(
            identity=lambda_who_call_the_state_machine.grant_principal)

You can also do it as @nija-at suggest, that I think is more elegant

[seansullivan]

Perhaps I'm missing something here, but the grantTaskResponse() does not appropriately set the permission on a Lambda function as it has an UnknownPrincipal as stated here

Upon deploying CDK project, I am met with the warning message:

Add statement to this resource's role: {"action":["states:SendTaskSuccess"],"notAction":[],"principal":{},"notPrincipal":{},"resource":[{"Ref":"myStateMachineStackMyStateMachineA67BBFB7"}],"notResource":[],"condition":{},"effect":"Allow"}

Of course, if I add the permission directly on the Lambda's role as a policy statement, everything works fine:

new PolicyStatement({
        effect: Effect.ALLOW,
        actions: ['states:SendTask*'],
        resources: [`arn:aws:states:${this.region}:${this.account}:stateMachine:*`]
})

Is the intent of these APIs to allow to use as such for a Lambda function?

const myLambdaFunction = Function.fromFunctionArn(myLambdaFunctionArn);

myStateMachine.grantTaskResponse(myLambdaFunction);

For further context, this Lambda lives outside of StepFunctions and is used for manual task response via API Gateway.