AWS Systems Manager
User Guide

Method 2: Use IAM to Configure Roles for Automation

If you need to create a service role for Systems Manager Automation, complete the following tasks. For more information on when a service role is required for Automation, see Getting Started with Automation.

Task 1: Create a Service Role for Automation

Use the following procedure to create a service role (or assume role) for Systems Manager Automation.

Note

You can also use this role in Automation documents, such as the AWS-CreateManagedLinuxInstance document. Using this role or the ARNs in Automation documents enables Automation to perform actions in your environment, such as launch new instances and perform actions on your behalf.

To create an IAM role and allow Automation to assume it

  1. Open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane, choose Roles, and then choose Create role.

  3. On the Select type of trusted entity page, under AWS Service, choose EC2.

  4. In the Select your use case section, choose EC2, and then choose Next: Permissions.

  5. On the Attached permissions policy page, search for the AmazonSSMAutomationRole policy, choose it, and then choose Next: Review.

  6. On the Review page, type a name in the Role name box, and then type a description.

  7. Choose Create role. The system returns you to the Roles page.

  8. On the Roles page, choose the role you just created to open the Summary page. Note the Role Name and Role ARN. You will specify the role ARN when you attach the iam:PassRole policy to your IAM account in the next procedure. You can also specify the role name and the ARN in Automation documents.

Note

The AmazonSSMAutomationRole policy assigns the Automation role permission to a subset of AWS Lambda functions within your account. These functions begin with "Automation". If you plan to use Automation with Lambda functions, the Lambda ARN must use the following format:

"arn:aws:lambda:*:*:function:Automation*"

If you have existing Lambda functions whose ARNs do not use this format, then you must also attach an additional Lambda policy to your automation role, such as the AWSLambdaRole policy. The additional policy or role must provide broader access to Lambda functions within the AWS account.

(Optional) Add an Automation Inline Policy to Invoke Other AWS Services

If you run an automation that invokes other AWS services by using an IAM service role, the service role must be configured with permission to invoke those services. This requirement applies to all AWS Automation documents (AWS-* documents) such as the AWS-ConfigureS3BucketLogging, AWS-CreateDynamoDBBackup, and AWS-RestartEC2Instance documents, to name a few. This requirement also applies to any custom Automation documents you create that invoke other AWS services by using actions that call other services. For example, if you use the aws:executeAwsApi, aws:CreateStack, or aws:copyImage actions, to name a few, then you must configure the service role with permission to invoke those services. You can enable permissions to other AWS services by adding an IAM inline policy to the role.

To embed an inline policy for a service role (IAM Console)

  1. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane, choose Roles.

  3. In the list, choose the name of the role that you want to edit.

  4. Choose the Permissions tab.

  5. Choose Add inline policy.

  6. Choose the JSON tab.

  7. Enter a JSON policy document for the AWS services you want to invoke. Here are two example JSON policy documents.

    Amazon S3 PutObject and GetObject Example

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:PutObject", "s3:GetObject" ], "Resource": "arn:aws:s3:::my-bucket-name/*" } ] }

    Amazon EC2 CreateSnapshot and DescribeSnapShots Example

    { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":"ec2:CreateSnapshot", "Resource":"*" }, { "Effect":"Allow", "Action":"ec2:DescribeSnapshots", "Resource":"*" } ] }

    For details about the IAM policy language, see IAM JSON Policy Reference in the IAM User Guide.

  8. When you are finished, choose Review policy. The Policy Validator reports any syntax errors.

  9. On the Review policy page, enter a Name for the policy that you are creating. Review the policy Summary to see the permissions that are granted by your policy. Then choose Create policy to save your work.

  10. After you create an inline policy, it is automatically embedded in your role.

Task 2: Add a Trust Relationship for Automation

Use the following procedure to configure the service role policy to trust Automation.

To add a trust relationship for Automation

  1. In the Summary page for the role you just created, choose the Trust Relationships tab, and then choose Edit Trust Relationship.

  2. Add "ssm.amazonaws.com", as shown in the following example.

    { "Version":"2012-10-17", "Statement":[ { "Sid":"", "Effect":"Allow", "Principal":{ "Service":[ "ec2.amazonaws.com", "ssm.amazonaws.com" ] }, "Action":"sts:AssumeRole" } ] }
  3. Choose Update Trust Policy.

  4. Leave the Summary page open.

Task 3: Attach the iam:PassRole Policy to Your Automation Role

Use the following procedure to attach the iam:PassRole policy to your Automation service role. This enables the Automation service to pass the role to other services or Systems Manager capabilities when running Automation workflows.

To attach the iam:PassRole policy to your Automation role

  1. In the Summary page for the role you just created, choose the Permissions tab.

  2. Choose Add inline policy.

  3. On the Create policy page, choose the Visual editor tab.

  4. Choose Service, and then choose IAM.

  5. Choose Select actions.

  6. In the Filter actions text box, type PassRole, and then choose the PassRole option.

  7. Choose Resources. Verify that Specific is selected, and then choose Add ARN.

  8. In the Specify ARN for role field, paste the Automation role ARN that you copied at the end of Task 1. The system populates the Account and Role name with path fields.

    Note

    If you want the Automation service role to attach an IAM instance profile role to an EC2 instance, then you must add the ARN of the IAM instance profile role. This allows the Automation service role to pass the IAM instance profile role to the target EC2 instance.

  9. Choose Add.

  10. Choose Review policy.

  11. On the Review Policy page, type a name and then choose Create Policy.

Task 4: Configure User Access to Automation

If your AWS Identity and Access Management (IAM) user account, group, or role is assigned administrator permissions, then you have access to Systems Manager Automation. If you don't have administrator permissions, then an administrator must give you permission by assigning the AmazonSSMFullAccess managed policy, or a policy that provides comparable permissions, to your IAM account, group, or role.

Use the following procedure to configure a user account to use Automation. The user account you choose will have permission to configure and run Automation. If you need to create a new user account, see Creating an IAM User in Your AWS Account in the IAM User Guide.

To configure user access and attach the iam:PassRole policy to a user account

  1. In the IAM navigation pane, choose Users, and then choose the user account you want to configure.

  2. On the Permissions tab, in the policies list, verify that either the AmazonSSMFullAccess policy is listed or there is a comparable policy that gives the account permissions to access Systems Manager.

  3. Choose Add inline policy.

  4. On the Create policy page, choose Visual Editor, and then choose Choose a service.

  5. From AWS Services, choose AWS Identity and Access Management.

  6. For Actions, enter PassRole in the Filter actions prompt, and choose PassRole.

  7. In the Resources section, choose Add ARN, paste the ARN for the Automation service role you copied at the end of Task 1, and then choose Add.

  8. Choose Review policy.

  9. On the Review Policy page, provide a Name for the policy and then choose Create policy.

You have finished configuring the required roles for Automation. You can now use the Automation service role ARN in your Automation documents.