Control access to maintenance windows using the AWS CLI
The following procedures describe how to use the AWS Command Line Interface (AWS CLI) to create the required permissions and roles for Maintenance Windows, a capability of AWS Systems Manager.
Topics
- Task 1: Create trust policy and customer managed policy files in JSON format
- Task 2: Create and verify a custom service role for maintenance windows using the AWS CLI
- Task 3: Grant permissions to specified users to register maintenance window tasks using the AWS CLI
- Task 4: Prevent specified users from registering maintenance window tasks using the AWS CLI
Task 1: Create trust policy and customer managed policy files in JSON format
Maintenance window tasks require an IAM role to provide the permissions required to run on the target resources. The permissions are provided through an IAM policy attached to the role. The types of tasks you run and your other operational requirements determine the contents of this policy. We provide a base policy you can adapt to your needs. Depending on the tasks and types of tasks your maintenance windows run, you might not need all the permissions in this policy, and you might need to include additional permissions.
In this task, you specify the permissions needed for your custom maintenance window role in a pair of JSON files. You attach this policy to the role that you create later in Task 2: Create and verify a custom service role for maintenance windows using the AWS CLI.
To create trust policy and customer managed policy files
-
Copy and paste the following trust policy into a text file. Save this file with the following name and file extension:
mw-role-trust-policy.json
.{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "ssm.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }
-
Copy and paste the following JSON policy into a different text file. In the same directory where you created the first file, save this file with the following name and file extension:
mw-role-custom-policy.json
.{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ssm:SendCommand", "ssm:CancelCommand", "ssm:ListCommands", "ssm:ListCommandInvocations", "ssm:GetCommandInvocation", "ssm:GetAutomationExecution", "ssm:StartAutomationExecution", "ssm:ListTagsForResource", "ssm:GetParameters" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "states:DescribeExecution", "states:StartExecution" ], "Resource": [ "arn:aws:states:*:*:execution:*:*", "arn:aws:states:*:*:stateMachine:*" ] }, { "Effect": "Allow", "Action": [ "lambda:InvokeFunction" ], "Resource": [ "arn:aws:lambda:*:*:function:*" ] }, { "Effect": "Allow", "Action": [ "resource-groups:ListGroups", "resource-groups:ListGroupResources" ], "Resource": [ "*" ] }, { "Effect": "Allow", "Action": [ "tag:GetResources" ], "Resource": [ "*" ] }, { "Effect": "Allow", "Action": "iam:PassRole", "Resource": "*", "Condition": { "StringEquals": { "iam:PassedToService": [ "ssm.amazonaws.com" ] } } } ] }
-
Modify the the content of
mw-role-custom-policy.json
as needed for the maintenance tasks that you run in your account. The changes you make are specific to your planned operations.For example:
-
You can provide Amazon Resource Names (ARNs) for specific functions and state machines instead of using wildcard (*) qualifiers.
-
If you don’t plan to run AWS Step Functions tasks, you can remove the
states
permissions and (ARNs). -
If you don’t plan to run AWS Lambda tasks, you can remove the
lambda
permissions and ARNs. -
If you don't plan to run Automation tasks, you can remove the
ssm:GetAutomationExecution
andssm:StartAutomationExecution
permissions. -
Add additional permissions that might be needed for the tasks to run. For example, some Automation actions work with AWS CloudFormation stacks. Therefore, the permissions
cloudformation:CreateStack
,cloudformation:DescribeStacks
, andcloudformation:DeleteStack
are required.For another example, the Automation runbook
AWS-CopySnapshot
requires permissions to create an Amazon Elastic Block Store (Amazon EBS) snapshot. Therefore, the service role needs the permissionec2:CreateSnapshot
.For information about the role permissions needed by Automation runbooks, see the runbook descriptions in the AWS Systems Manager Automation runbook reference.
Save the file again after making any needed changes.
-
Task 2: Create and verify a custom service role for maintenance windows using the AWS CLI
The policy you created in the previous task is attached to the maintenance window service role you create in this task. When users register a maintenance window task, they specify this IAM role as part of the task configuration. The permissions in this role allow Systems Manager to run tasks in maintenance windows on your behalf.
Important
Previously, the Systems Manager console provided you with the ability to choose
the AWS managed IAM service-linked role
AWSServiceRoleForAmazonSSM
to use as the maintenance
role for your tasks. Using this role and its associated policy,
AmazonSSMServiceRolePolicy
, for maintenance window tasks is no
longer recommended. If you're using this role for maintenance window
tasks now, we encourage you to stop using it. Instead, create your own
IAM role that enables communication between Systems Manager and other AWS services
when your maintenance window tasks run.
In this task, you run CLI commands to create your maintenance windows service role, adding the policy content from the JSON files you created.
Create a custom service role for maintenance windows using the AWS CLI
-
Open the AWS CLI and run the following command in the directory where you placed
mw-role-custom-policy.json
andmw-role-trust-policy.json
. The command creates a maintenance window service role calledmy-maintenance-window-role
and attaches the trust policy to it.The system returns information similar to the following.
{ "Role": { "AssumeRolePolicyDocument": { "Version": "2012-10-17", "Statement": [ { "Action": "sts:AssumeRole", "Effect": "Allow", "Principal": { "Service": "ssm.amazonaws.com" } } ] }, "RoleId": "AROAIIZKPBKS2LEXAMPLE", "CreateDate": "2024-08-19T03:40:17.373Z", "RoleName": "my-maintenance-window-role", "Path": "/", "Arn": "arn:aws:iam::123456789012:role/my-maintenance-window-role" } }
Note
Make a note of the
RoleName
and theArn
values. You include them in the next command. -
Run the following command to attach the customer managed policy to the role. Replace the
account-id
placeholder with your own AWS account ID -
Run the following command to verify that your role has been created, and that the trust policy has been attached.
aws iam get-role --role-name my-maintenance-window-role
The command returns information similar to the following:
{ "Role": { "Path": "/", "RoleName": "my-maintenance-window-role", "RoleId": "AROA123456789EXAMPLE", "Arn": "arn:aws:iam::123456789012:role/my-maintenance-window-role", "CreateDate": "2024-08-19T14:13:32+00:00", "AssumeRolePolicyDocument": { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "ssm.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }, "MaxSessionDuration": 3600, "RoleLastUsed": { "LastUsedDate": "2024-08-19T14:30:44+00:00", "Region": "us-east-2" } } }
-
Run the following command to verify that the customer managed policy has been attached to the role.
aws iam list-attached-role-policies --role-name my-maintenance-window-role
The command returns information similar to the following:
{ "AttachedPolicies": [ { "PolicyName": "mw-role-custom-policy", "PolicyArn": "arn:aws:iam::123456789012:policy/mw-role-custom-policy" } ] }
Task 3: Grant permissions to specified users to register maintenance window tasks using the AWS CLI
Providing users with permissions to access the custom service role for maintenance windows lets them use it with their maintenance windows tasks. This is in addition to permissions that you’ve already given them to work with the Systems Manager API commands for the Maintenance Windows capability. This IAM role conveys the permissions need to run a maintenance window task. As a result, a user can't register tasks with a maintenance window using your custom service role without the ability to pass these IAM permissions.
When you register a task with a maintenance window, you specify a
service role to run the actual task operations.
This is the role that the service assumes when it runs tasks on your behalf. Before
that, to register the task itself, assign the IAM PassRole
policy to an
IAM entity (such as a user or group). This allows the IAM entity
to specify, as part of registering those tasks with the maintenance window, the role that
should be used when running tasks. For information, see Grant a user permissions to pass a role
to an AWS service in the IAM User Guide.
To configure permissions for users who are allowed to register maintenance window tasks using the AWS CLI
-
Copy and paste the following AWS Identity and Access Management (IAM) policy into a text editor and save it with the following name and file extension:
mw-passrole-policy.json
.{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iam:PassRole", "Resource": "arn:aws:iam::
account-id
:role/my-maintenance-window-role
" }, { "Effect": "Allow", "Action": "iam:ListRoles", "Resource": "arn:aws:iam::account-id
:role/" }, { "Effect": "Allow", "Action": "iam:ListRoles", "Resource": "arn:aws:iam::account-id
:role/aws-service-role/ssm.amazonaws.com/" } ] }Replace
my-maintenance-window-role
with the name of the custom maintenance window role you created earlier.Replace
account-id
with the ID of your AWS account. Adding this permission for the resourcearn:aws:iam::
allows users in the group to view and choose from customer roles in the console when they create a maintenance window task. Adding this permission foraccount-id
:role/arn:aws:iam::
allows users in the group to choose the Systems Manager service-linked role in the console when they create a maintenance window task.account-id
:role/aws-service-role/ssm.amazonaws.com/ -
Open the AWS CLI.
-
Depending on whether you're assigning the permission to an IAM entity (user or group), run one of the following commands.
-
For an IAM entity:
For
user-name
, specify the user who assigns tasks to maintenance windows. Forpolicy-name
, specify the name you want to use to identify the policy, such asmy-iam-passrole-policy
. Forpath-to-document
, specify the path to the file you saved in step 1. For example:file://C:\Temp\mw-passrole-policy.json
Note
To grant access for a user to register tasks for maintenance windows using the Systems Manager console, you must also assign the
AmazonSSMFullAccess
policy to your user (or an IAM policy that provides a smaller set of access permissions for Systems Manager that covers maintenance window tasks). Run the following command to assign theAmazonSSMFullAccess
policy to your user. -
For an IAM group:
For
group-name
, specify the group whose members assign tasks to maintenance windows. Forpolicy-name
, specify the name you want to use to identify the policy, such asmy-iam-passrole-policy
. Forpath-to-document
, specify the path to the file you saved in step 1. For example:file://C:\Temp\mw-passrole-policy.json
Note
To grant access for members of a group to register tasks for maintenance windows using the Systems Manager console, you must also assign the
AmazonSSMFullAccess
policy to your group. Run the following command to assign this policy to your group.
-
-
Run the following command to verify that the policy has been assigned to the group.
Task 4: Prevent specified users from registering maintenance window tasks using the AWS CLI
You can deny the ssm:RegisterTaskWithMaintenanceWindow
permission
for the users in your AWS account who you don't want to register tasks with
maintenance windows. This provides an extra layer of prevention for users who
shouldn’t register maintenance window tasks.
Depending on whether you're denying the
ssm:RegisterTaskWithMaintenanceWindow
permission for an
individual user or a group, use one of the following procedures to prevent users
from registering tasks with a maintenance window.
To configure permissions for users who aren't allowed to register maintenance window tasks using the AWS CLI
-
Copy and paste the following IAM policy into a text editor and save it with the following name and file extension:
deny-mw-tasks-policy.json
.{ "Version": "2012-10-17", "Statement": [ { "Effect": "Deny", "Action": "ssm:RegisterTaskWithMaintenanceWindow", "Resource": "*" } ] }
-
Open the AWS CLI.
-
Depending on whether you're assigning the permission to an IAM entity (user or group), run one of the following commands.
-
For a user:
For
user-name
, specify the user to prevent from assigning tasks to maintenance windows. Forpolicy-name
, specify the name you want to use to identify the policy, such asmy-deny-mw-tasks-policy
. Forpath-to-document
, specify the path to the file you saved in step 1. For example:file://C:\Temp\deny-mw-tasks-policy.json
-
For a group:
For
group-name
, specify the group whose to prevent from assigning tasks to maintenance windows. Forpolicy-name
, specify the name you want to use to identify the policy, such asmy-deny-mw-tasks-policy
. Forpath-to-document
, specify the path to the file you saved in step 1. For example:file://C:\Temp\deny-mw-tasks-policy.json
-
-
Run the following command to verify that the policy has been assigned to the group.