Menu
Amazon EC2 Systems Manager
User Guide

Controlling Access to Maintenance Windows

Use one of the following methods to control access to Maintenance Windows by configuring security roles and permissions.

Controlling Access to Maintenance Windows Using the AWS Console

The following procedures describe how to create the required roles and permissions for Maintenance Windows by using the Amazon EC2 console.

Create an IAM Role for Systems Manager

Use the following procedure to create a role so that Systems Manager can execute tasks in Maintenance Windows on your behalf.

To create an IAM role for Maintenance Windows

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

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

  3. In Step 1: Select Role Type, choose Amazon EC2. The system skips Step 2: Establish Trust because this is a managed policy.

  4. In Step 3: Attach Policy, choose AmazonSSMMaintenanceWindowRole, and then choose Next Step.

  5. In Step 4: Set role name and review, enter a name that identifies this role as a Maintenance Windows role.

  6. Choose Create Role. The system returns you to the Roles page.

  7. Locate the role you just created and double-click it.

  8. Choose the Trust Relationships tab, and then choose Edit Trust Relationship.

  9. Delete the current policy, and then copy and paste the following policy into the Policy Document field:

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

  11. Copy or make a note of the role name and the Role ARN. You will specify this information when you create your Maintenance Window.

Assign the IAM PassRole Policy to an IAM User Account

When you register a task with a Maintenance Window, you specify the role you created in the previous procedure. This is the role that the service will assume when it runs tasks on your behalf. In order to register the task, you must assign the IAM PassRole policy to your IAM user account. The policy in the following procedure provides the minimum permissions required to register tasks with a Maintenance Window.

To assign the IAM PassRole policy to an IAM user account

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

  2. In the policies list, verify that either the AmazonSSMFullAccess policy is listed or there is a comparable policy that gives the IAM user permission to call the Systems Manager API.

  3. Choose Add inline policy.

  4. On the Set Permissions page, choose Policy Generator, and then choose Select.

  5. Verify that Effect is set to Allow.

  6. From AWS Services choose AWS Identity and Access Management.

  7. From Actions, choose PassRole.

  8. In the Amazon Resource Name (ARN) field, paste the role ARN you created in the previous procedure.

  9. Choose Add Statement, and then choose Next Step.

  10. On the Review Policy page, choose Apply Policy.

Controlling Access to Maintenance Windows Using the AWS CLI

Use the following procedure to create an IAM role for Maintenance Windows using the AWS CLI.

To create an IAM role for Maintenance Windows

  1. Copy and paste the following trust policy into a text file. Save the file with the following name and file extension: mw-role-trust-policy.json.

    Copy
    { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Principal":{ "Service":[ "ssm.amazonaws.com", "ec2.amazonaws.com" ] }, "Action":"sts:AssumeRole" } ] }
  2. Open the AWS CLI and execute the following command to create a Maintenance Window role called mw-task-role. The command assigns the policy you created in the previous step to this role.

    Copy
    aws iam create-role --role-name mw-task-role --assume-role-policy-document file://mw-role-trust-policy.json

    The system returns information like the following.

    {
       "Role":{
          "AssumeRolePolicyDocument":{
             "Version":"2012-10-17",
             "Statement":[
                {
                   "Action":"sts:AssumeRole",
                   "Effect":"Allow",
                   "Principal":{
                      "Service":[
                         "ssm.amazonaws.com",
                         "ec2.amazonaws.com"
                      ]
                   }
                }
             ]
          },
          "RoleId":"AROAIIZKPBKS2LEXAMPLE",
          "CreateDate":"2017-04-04T03:40:17.373Z",
          "RoleName":"mw-task-role",
          "Path":"/",
          "Arn":"arn:aws:iam::123456789012:role/mw-task-role"
       }
    }

    Note

    Make a note of the RoleName and the Arn. You will specify these when you create a Maintenance Window.

  3. Execute the following command to attach the AmazonSSMMaintenanceWindowRole managed policy to the role you created in step 2.

    Copy
    aws iam attach-role-policy --role-name mw-task-role --policy-arn arn:aws:iam::aws:policy/service-role/AmazonSSMMaintenanceWindowRole

Assign the IAM PassRole Policy to an IAM User Account Using the AWS CLI

When you register a task with a Maintenance Window, you specify the role you created in the previous procedure. This is the role that the service will assume when it runs tasks on your behalf. In order to register the task, you must assign the IAM PassRole policy to your IAM user account. The policy in the following procedure provides the minimum permissions required to register tasks with a Maintenance Window.

To assign the IAM PassRole policy to an IAM user account

  1. Copy and paste the following IAM policy into a text editor and save it with the .json file extension.

    Copy
    { "Version":"2012-10-17", "Statement":[ { "Sid":"Stmt1491345526000", "Effect":"Allow", "Action":[ "iam:GetRole", "iam:PassRole", "ssm:RegisterTaskWithMaintenanceWindow" ], "Resource":[ "*" ] } ] }
  2. Open the AWS CLI.

  3. Execute the following command. For user-name, specify the IAM user who will assign tasks to Maintenance Windows. For policy-document, specify the path to the file you saved in step 1.

    Copy
    aws iam put-user-policy --user-name name of user --policy-name a name for the policy --policy-document path to document, for example: file://C:\Temp\passrole.json

    Note

    If you plan to register tasks for Maintenance Windows using the Amazon EC2 console, you must also assign the AmazonSSMReadOnlyAccess policy to your user account. Execute the following command to assign this policy to your account.

    Copy
    aws iam attach-user-policy --policy-arn arn:aws:iam::aws:policy/AmazonSSMReadOnlyAccess --user-name IAM account name
  4. Execute the following command to verify that the policy has been assigned to the user.

    Copy
    aws iam list-user-policies --user-name name of user

Controlling Access to Maintenance Windows Using Tools for Windows PowerShell

Use the following procedure to create an IAM role for Maintenance Windows using the Tools for Windows PowerShell.

To create an IAM role for Maintenance Windows

  1. Copy and paste the following trust policy into a text file. Save the file with the following name and file extension: mw-role-trust-policy.json.

    Copy
    { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Principal":{ "Service":[ "ssm.amazonaws.com", "ec2.amazonaws.com" ] }, "Action":"sts:AssumeRole" } ] }
  2. Open Tools for Windows PowerShell and execute the following command to create a role called mw-task-role. The role uses the policy that you created in the previous step.

    Copy
    New-IAMRole -RoleName "mw-task-role" -AssumeRolePolicyDocument (Get-Content -raw .\mw-role-trust-policy.json)

    The systems returns information like the following.

    Arn : arn:aws:iam::123456789012:role/mw-task-role
    AssumeRolePolicyDocument : ExampleDoc12345678
    CreateDate : 4/4/2017 11:24:43
    Path : /
    RoleId : AROAIIZKPBKS2LEXAMPLE
    RoleName : mw-task-role
  3. Execute the following command to attach the AmazonSSMMaintenanceWindowRole managed policy to the role you created in the previous step.

    Copy
    Register-IAMRolePolicy -RoleName mw-task-role -PolicyArn arn:aws:iam::aws:policy/service-role/AmazonSSMMaintenanceWindowRole

Assign the IAM PassRole Policy to an IAM User Account Using Tools for Windows PowerShell

When you register a task with a Maintenance Window, you specify the role you created in the previous procedure. This is the role that the service will assume when it runs tasks on your behalf. In order to register the task, you must assign the IAM PassRole policy to your IAM user account. The policy in the following procedure provides the minimum permissions required to register tasks with a Maintenance Window.

To assign the IAM PassRole policy to an IAM user account

  1. Copy and paste the following IAM policy into a text editor and save it with the .json file extension.

    Copy
    { "Version":"2012-10-17", "Statement":[ { "Sid":"Stmt1491345526000", "Effect":"Allow", "Action":[ "iam:GetRole", "iam:PassRole", "ssm:RegisterTaskWithMaintenanceWindow" ], "Resource":[ "*" ] } ] }
  2. Open Tools for Windows PowerShell.

  3. Execute the following command. For user-name, specify the IAM user who will assign tasks to Maintenance Windows. For policy-document, specify the path to the file you saved in step 1.

    Copy
    Write-IAMUserPolicy -UserName name of IAM user -PolicyDocument (Get-Content -raw path to document, for example: C:\temp\passrole-policy.json) -PolicyName a name for the policy

    Note

    If you plan to register tasks for Maintenance Windows using the Amazon EC2 console, you must also assign the AmazonSSMReadOnlyAccess policy to your user account. Execute the following command to assign this policy to your account.

    Copy
    Register-IAMUserPolicy -UserName IAM account name -PolicyArn arn:aws:iam::aws:policy/AmazonSSMReadOnlyAccess
  4. Execute the following command to verify that the policy has been assigned to the user.

    Copy
    Get-IAMUserPolicies -UserName name of user