AWS step-functions documentation change
Summary
Updated documentation about IAM policies for Step Functions, including changes to dynamic/static resources, .sync tasks, troubleshooting stuck workflows, and permissions for cancelling workflows. Added more detailed explanations about polling vs. event-based monitoring and specific permission requirements.
Security assessment
The changes primarily focus on clarifying IAM permission requirements and troubleshooting steps for Step Functions. While it discusses IAM policies and permissions, which are security-related, there is no evidence of addressing a specific security vulnerability or incident. The documentation adds more details about security features (IAM permissions) but does not indicate a security issue being fixed.
Diff
diff --git a/step-functions/latest/dg/service-integration-iam-templates.md index 4f7e9a287..79ecdc82a 100644 --- a/step-functions/latest/dg/service-integration-iam-templates.md +++ b/step-functions/latest/dg/service-integration-iam-templates.md @@ -5 +5 @@ -Dynamic vs. Static ResourcesAdditional permissions for tasks using the Run a Job pattern +Dynamic and static resourcesAdditional permissions for tasks using .syncTroubleshooting stuck .sync workflowsPermissions for cancelling workflows @@ -9 +9 @@ Dynamic vs. Static ResourcesAdditional permissions for tasks using the Run a Job -When you create a state machine in the AWS Step Functions console, Step Functions produces an AWS Identity and Access Management (IAM) policy based on the resources used in your state machine definition as follows: +When you create a state machine in the AWS Step Functions console, Step Functions produces an AWS Identity and Access Management (IAM) policy based on the resources used in your state machine definition, as follows: @@ -11 +11 @@ When you create a state machine in the AWS Step Functions console, Step Function - * If your state machine uses one of the Optimized integrations, Step Functions will create a policy with the necessary permissions and roles for your state machine. (Exception: MediaConvert integration requires you to manually set up permissions – see [IAM policies for calling AWS Elemental MediaConvert](./connect-mediaconvert.html#mediaconvert-iam).) + * For **optimized integrations** , Step Functions will create a policy with all the necessary permissions and roles for your state machine. @@ -13 +13 @@ When you create a state machine in the AWS Step Functions console, Step Function - * If your state machine uses one of the AWS SDK integrations, an IAM role with partial permissions will be created. Afterwards, you can use the IAM console to add any missing role policies. +Tip: You can see example policies in each of the service pages under [Integrating optimized services](./integrate-optimized.html). @@ -14,0 +15 @@ When you create a state machine in the AWS Step Functions console, Step Function + * For **standard integrations** integrations, Step Functions will create an IAM role with partial permissions. @@ -15,0 +17 @@ When you create a state machine in the AWS Step Functions console, Step Function +You must add any missing role policies that your state machine needs to interact with the service. @@ -18 +19,0 @@ When you create a state machine in the AWS Step Functions console, Step Function -The following examples show how Step Functions generates an IAM policy based on your state machine definition. Items in the example code such as ```[[resourceName]]``` are replaced with the static resources listed in your state machine definition. If you have multiple static resources, there will be an entry for each in the IAM role. @@ -20 +20,0 @@ The following examples show how Step Functions generates an IAM policy based on -## Dynamic vs. Static Resources @@ -22 +22 @@ The following examples show how Step Functions generates an IAM policy based on -Static resources are defined directly in the task state of your state machine. When you include the information about the resources you want to call directly in your task states, Step Functions creates an IAM role for only those resources. +## Dynamic and static resources @@ -24 +24 @@ Static resources are defined directly in the task state of your state machine. W -Dynamic resources are those that are passed in to your state input, and accessed using a Path (see [Using JSONPath paths](./amazon-states-language-paths.html)). If you are passing dynamic resources to your task, Step Functions will create a more privileged policy that specifies: `"Resource": "*"`. +_Static resources_ are defined **directly** in the task state of your state machine. When you include the information about the resources you want to call directly in your task states, Step Functions can create an IAM role for only those resources. @@ -26 +26 @@ Dynamic resources are those that are passed in to your state input, and accessed -## Additional permissions for tasks using the Run a Job pattern +_Dynamic resources_ are **passed** as input when starting your state machine, or as input to an individual state, and accessed using JSONata or a JSONPath. When you are passing dynamic resources to your task, Step Functions cannot automatically scope-down the permissions, so Step Functions will create a more permissive policy which specifies:`"Resource": "*"`. @@ -28 +28 @@ Dynamic resources are those that are passed in to your state input, and accessed -For tasks that use the [Run a Job](./connect-to-resource.html#connect-sync) pattern (those ending in `.sync`), additional permissions are needed to monitor and receive a response from the API actions of connected services. The related policies include more permissions than for tasks that use the Request Response or Wait for Callback patterns. See [Discover service integration patterns in Step Functions](./connect-to-resource.html) for information about synchronous tasks. +## Additional permissions for tasks using .sync @@ -30 +30,9 @@ For tasks that use the [Run a Job](./connect-to-resource.html#connect-sync) patt -###### Note +Tasks that use the [Run a Job (.sync)](./connect-to-resource.html#connect-sync) pattern require additional permissions for monitoring and receiving a response from the API of connected services. + +Step Functions uses two approaches to monitor a job's status when a job is run on a connected service: **polling** and **events**. + +Polling requires permission for `Describe` or `Get` API actions. For example, for Amazon ECS the state machine must have allow permission for `ecs:DescribeTasks`, for AWS Glue the state machine requires allow permissions for `glue:GetJobRun`. If the necessary permissions are missing from the role, Step Functions may be unable to determine the status of your job. One reason for using the polling method is because some service integrations do not support EventBridge events, and some services only send events on a best-effort basis. + +Alternatively, you might use events sent from AWS services to Amazon EventBridge. Events are routed to Step Functions by EventBridge with a managed rule, so the role requires permissions for `events:PutTargets`, `events:PutRule`, and `events:DescribeRule`. If these permissions are missing from the role, there may be a delay before Step Functions becomes aware of the completion of your job. For more information about EventBridge events, see [Events from AWS services](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-service-event.html). + +## Troubleshooting stuck .sync workflows @@ -32 +40 @@ For tasks that use the [Run a Job](./connect-to-resource.html#connect-sync) patt -You need to provide additional permissions for service integrations that support the Run a Job (.sync) pattern. +For Run a Job (.sync) tasks that support **both** polling and events, your task may complete properly using events, even when the role lacks the required permissions for polling. @@ -34 +42 @@ You need to provide additional permissions for service integrations that support -Step Functions uses two methods to monitor a job's status when a job is run on a connected service, polling and events. +In the previous scenario, you might not notice the polling permissions are missing or incorrect. In the rare case that an event fails to be delivered to or processed by Step Functions, your execution could become stuck. @@ -36 +44 @@ Step Functions uses two methods to monitor a job's status when a job is run on a -Polling requires permission for `Describe` or `Get` API actions, such as `ecs:DescribeTasks` or `glue:GetJobRun`. If these permissions are missing from your role, then Step Functions may be unable to determine the status of your job. This is because some Run a Job (.sync) service integrations do not support EventBridge events, and some services only send events on a best-effort basis. +To verify that your polling permissions are configured correctly, you can run an execution in an environment without EventBridge events in the following ways @@ -38 +46 @@ Polling requires permission for `Describe` or `Get` API actions, such as `ecs:De -Events sent from AWS services to Amazon EventBridge are directed to Step Functions using a managed rule, and require permissions for `events:PutTargets`, `events:PutRule`, and `events:DescribeRule`. If these permissions are missing from your role, there may be a delay before Step Functions becomes aware of the completion of your job. For more information about EventBridge events, see [Events from AWS services](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-service-event.html). + * Delete the managed rule in EventBridge that is responsible for forwarding events to Step Functions. @@ -42 +50,7 @@ Events sent from AWS services to Amazon EventBridge are directed to Step Functio -For Run a Job (.sync) tasks that support both polling and events, your task may still complete properly using events. This can occur even if your role lacks the required permissions for polling. In this case, you may not immediately notice that the polling permissions are incorrect or missing. In the rare instance that the event fails to be delivered to or processed by Step Functions, your execution could become stuck. To verify that your polling permissions are configured correctly, you can run an execution in an environment without EventBridge events in the following ways: +Because managed rules are shared by all state machines in your account, you should use a test or development account to avoid unintentional impact to other state machines. + + * You can identify the specific managed rule to delete by inspecting the `Resource` field used for `events:PutRule` in the policy template for the target service. The managed rule will be recreated the next time you create or update a state machine that uses that service integration. + + * For more information on deleting EventBridge rules, see [Disabling or deleting a rule](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-delete-rule.html). + + @@ -44 +57,0 @@ For Run a Job (.sync) tasks that support both polling and events, your task may - * Delete the managed rule from EventBridge, which is responsible for forwarding events to Step Functions. This managed rule is shared by all state machines in your account, so you should perform this action only in a test or development account to avoid any unintentional impact on other state machines. You can identify the specific managed rule to delete by inspecting the `Resource` field used for `events:PutRule` in the policy template for the target service. The managed rule will be recreated the next time you create or update a state machine that uses that service integration. For more information on deleting EventBridge rules, see [Disabling or deleting a rule](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-delete-rule.html). @@ -46 +59 @@ For Run a Job (.sync) tasks that support both polling and events, your task may - * Test with Step Functions Local, which does not support the use of events to complete Run a Job (.sync) tasks. To use Step Functions Local, assume the IAM role used by your state machine. You may need to edit the Trust Relationship. Set the `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` environment variables to the assumed role's values, then launch Step Functions Local using **java -jar StepFunctionsLocal.jar**. Last, use the AWS CLI with the **\--endpoint-url** parameter to create a state machine, start an execution, and get the execution history. For more information, see [Testing state machines with Step Functions Local (unsupported)](./sfn-local.html). +## Permissions for cancelling workflows @@ -47,0 +61 @@ For Run a Job (.sync) tasks that support both polling and events, your task may +If a task that uses the Run a Job (.sync) pattern is stopped, Step Functions will make a best-effort attempt to cancel the task. @@ -48,0 +63 @@ For Run a Job (.sync) tasks that support both polling and events, your task may +Cancelling a task requires permission to `Cancel`, `Stop`, `Terminate`, or `Delete` API actions, such as `batch:TerminateJob` or `eks:DeleteCluster`. If these permissions are missing from your role, Step Functions will be unable to cancel your task and you may accrue additional charges while it continues to run. For more information on stopping tasks, see [Run a Job](./connect-to-resource.html#connect-sync). @@ -49,0 +65 @@ For Run a Job (.sync) tasks that support both polling and events, your task may +###### Learn more about integration patterns @@ -51 +67 @@ For Run a Job (.sync) tasks that support both polling and events, your task may -If a task that uses the Run a Job (.sync) pattern is stopped, Step Functions will make a best-effort attempt to cancel the task. This requires permission to `Cancel`, `Stop`, `Terminate`, or `Delete` API actions, such as `batch:TerminateJob` or `eks:DeleteCluster`. If these permissions are missing from your role, Step Functions will be unable to cancel your task and you may accrue additional charges while it continues to run. For more information on stopping tasks, see [Run a Job](./connect-to-resource.html#connect-sync). +To learn about synchronous tasks, see [Discover service integration patterns in Step Functions](./connect-to-resource.html).