(aws-stepfunctions-tasks): Make `iamResources` optional for `CallAwsService`

[paya-cz]

Describe the feature

Make CallAwsService.iamResources optional, so that I can manually attach the necessary permissions later on.

Use Case

I have a recursive task that calls sfn:listExecutions on itself (the state machine). When I declare the task via sfn_tasks.CallAwsService.jsonata(...), the state machine does not exist yet, so I can't pass it to iamResources. Instead, I have to instantiate the step machine first, and then attach a policy to the role later (see #11020 for details). However, because iamResources is not optional, I have to pass in some gibberish data to satisfy the "required" part, even if ultimately that policy won't be used. This doesn't lead itself to a clean code, having to pass in random gibberish data.

sfn_tasks.CallAwsService.jsonata(this, 'ListExecutions', {
    service: 'sfn',
    action: 'listExecutions',
    parameters: {
        StateMachineArn: '{% $states.context.StateMachine.Id %}',
    },
    // HERE! Gibberish ARN is required to satisfy the condition of having at least one resource.
    iamResources: [
        cdk.Arn.format({
            service: 'states',
            resource: 'stateMachine:XYZ',
        }, cdk.Stack.of(this)),
    ],
});

// Create state machine here
const stateMachine = ...

// Attach a new policy to the state machine here to allow the `states:ListExecutions` action itself
const policy = ...
policy.attachToRole(stateMachine.role);

Proposed Solution

Make iamResources optional, or at least make it accept an empty array as a valid value.

Other Information

No response

Acknowledgements

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

AWS CDK Library version (aws-cdk-lib)

aws-cdk-lib@2.211.0

AWS CDK CLI version

2.1025.0 (build 409f8e7)

Environment details (OS name and version, etc.)

Win11 Arm64

[pahud]

Hi @paya-cz,

Thank you for this feature request! This is a valid use case that addresses a real limitation in the current CallAwsService design.

The Problem: The current implementation requires iamResources and always generates automatic IAM policies, but this doesn't work well for:

1. Recursive/self-referencing scenarios (like your Step Functions case)
2. Complex IAM conditions (related to (aws-stepfunctions-tasks): CallAwsService IAM Condition #17185)
3. Dynamic resource ARNs that aren't known at synthesis time

Proposed Solution: Make iamResources optional in the CallAwsServiceOptions interface. When not provided, the construct would skip automatic IAM policy generation, allowing users to manually manage permissions.

This would be a non-breaking change since:

• Existing code with iamResources continues to work unchanged
• New code can omit iamResources for manual policy management
• The implementation change is straightforward in the constructor

Implementation approach:

// In CallAwsServiceOptions interface
readonly iamResources?: string[]; // Make optional

// In constructor
if (props.iamResources) {
 this.taskPolicies = [
   new iam.PolicyStatement({
     resources: props.iamResources,
     actions: [props.iamAction ?? ${iamService}:${props.action}],
   }),
   ...props.additionalIamStatements ?? [],
 ];
} else {
 this.taskPolicies = props.additionalIamStatements ?? [];
}

This would enable your clean use case:

const task = sfnTasks.CallAwsService.jsonata(this, 'ListExecutions', {
   service: 'sfn',
   action: 'listExecutions',
   parameters: {
       StateMachineArn: '{% $states.context.StateMachine.Id %}',
   },
   // No iamResources needed - handle manually later
});

---

Manual IAM Policy Management Options

Option 1: Using additionalIamStatements (Recommended)

Even with optional iamResources, you can still use the existing additionalIamStatements property:

const task = sfnTasks.CallAwsService.jsonata(this, 'ListExecutions', {
    service: 'sfn',
    action: 'listExecutions',
    parameters: {
        StateMachineArn: '{% $states.context.StateMachine.Id %}',
    },
    // No iamResources - skip automatic policy generation
    additionalIamStatements: [
        new iam.PolicyStatement({
            actions: ['states:listExecutions'],
            resources: [stateMachine.stateMachineArn], // Real ARN available here
        }),
    ],
});

Option 2: Direct Role Policy Management

Access the state machine's role directly after creation:

// Create the task without automatic IAM policies
const task = sfnTasks.CallAwsService.jsonata(this, 'ListExecutions', {
    service: 'sfn',
    action: 'listExecutions',
    parameters: {
        StateMachineArn: '{% $states.context.StateMachine.Id %}',
    },
    // No iamResources specified
});

// Create state machine
const stateMachine = new sfn.StateMachine(this, 'MyStateMachine', {
    definitionBody: sfn.DefinitionBody.fromChainable(task),
});

// Now manually add the policy to the state machine's role
stateMachine.addToRolePolicy(new iam.PolicyStatement({
    actions: ['states:listExecutions'],
    resources: [stateMachine.stateMachineArn], // Self-reference now possible
}));

Option 3: Custom IAM Role

Provide a custom role with pre-configured policies:

const customRole = new iam.Role(this, 'CustomStateMachineRole', {
    assumedBy: new iam.ServicePrincipal('states.amazonaws.com'),
    inlinePolicies: {
        'CustomPolicy': new iam.PolicyDocument({
            statements: [
                new iam.PolicyStatement({
                    actions: ['states:listExecutions'],
                    resources: ['*'], // Or specific patterns
                }),
            ],
        }),
    },
});

const task = sfnTasks.CallAwsService.jsonata(this, 'ListExecutions', {
    service: 'sfn',
    action: 'listExecutions',
    parameters: {
        StateMachineArn: '{% $states.context.StateMachine.Id %}',
    },
    // No iamResources needed
});

const stateMachine = new sfn.StateMachine(this, 'MyStateMachine', {
    definitionBody: sfn.DefinitionBody.fromChainable(task),
    role: customRole, // Use custom role
});

For your recursive Step Functions scenario, the cleanest approach would be Option 2:

// Clean task definition - no dummy data
const listExecutionsTask = sfnTasks.CallAwsService.jsonata(this, 'ListExecutions', {
    service: 'sfn',
    action: 'listExecutions',
    parameters: {
        StateMachineArn: '{% $states.context.StateMachine.Id %}',
    },
    // No iamResources - we'll handle this manually
});

// Create state machine
const stateMachine = new sfn.StateMachine(this, 'RecursiveStateMachine', {
    definitionBody: sfn.DefinitionBody.fromChainable(listExecutionsTask),
});

// Now add the self-referencing permission
stateMachine.addToRolePolicy(new iam.PolicyStatement({
    actions: ['states:ListExecutions'],
    resources: [stateMachine.stateMachineArn],
}));

This eliminates the need for gibberish ARNs while providing full control over IAM permissions!

[Michae1CC]

Another easy work around for now (without having to set spurious policies) is to set the iamResources to ["*"]. Of course, the does not follow the principle of least privilege and should be used with discretion.