Menu
Amazon EC2 Systems Manager
User Guide

Configuring Access Using Custom Roles and Polices

If you choose not to use Systems Manager managed policies, then use the following procedures to create and configure a custom instance role and user account for Systems Manager.

Important

If you want to use an existing instance role and user account, you must attach the policies shown in this section to the role and the user account. You must also verify that ec2.amazonaws.com is listed in the trust policy for the instance role. For more information, see Task 4: Verify the Trust Policy.

Task 1: Create a Custom IAM Policy for Systems Manager Managed Instances

The following IAM policy enables managed instances to communicate with the Systems Manager API. You will create the role and attach this policy to that role later in this topic.

To create an IAM policy for Systems Manager managed instances

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

  2. In the navigation pane, choose Policies.

  3. In the filter field, type AmazonEC2RoleforSSM.

  4. Choose the AmazonEC2RoleforSSM policy. The system displays the Policy Document for the policy.

  5. Copy the contents of the policy document.

    Note

    You can't alter the content of the policy document in the IAM console because it is a managed policy, but you can copy it.

  6. In the navigation pane, choose Policies.

  7. Choose Create Policy.

  8. Beside Create Your Own Policy, choose Select.

  9. Type a policy name (for example, SystemsManagerInstance) and description, and then paste the policy you copied earlier into the Policy Document field.

  10. Change the policy as you want.

    Important

    In the last section of this IAM policy, you can restrict access to the Amazon S3 bucket by specifying an Amazon Resource Name (ARN). For example, you can change the last "Resource": "*" item to "Resource": "arn:aws:s3:::AnS3Bucket/*

  11. Choose Validate Policy. Verify that the policy is valid. If you receive an error, verify that you included the opening and closing brackets { }. After the policy is validated, choose Create Policy.

Task 2: Create a Custom IAM User Policy

The IAM user policy determines which Systems Manager documents a user can see in the Document list. Users can see this list in either the Amazon EC2 console or by calling ListDocuments using the AWS CLI or AWS Tools for Windows PowerShell. The policy also limits the actions the user can perform with a Systems Manager Document.

Note

You will create a user account and attach this policy to that account later on.

The IAM policy in the following procedure enables the user to perform any Systems Manager action on the instance. Assign this policy only to trusted administrators. For all other users, create a restrictive IAM policy, as described in this section, or use the AmazonSSMReadOnlyAccess policy.

To create an IAM user policy for Systems Manager

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

  2. In the navigation pane, choose Policies.

  3. In the filter field, type AmazonSSMFullAccess.

  4. Choose the AmazonSSMFullAccess policy. The system displays the Policy Document for the policy.

  5. Copy the contents of the policy document.

    Note

    You can't alter the content of the policy document in the IAM console because it is a managed policy, but you can copy it.

  6. In the navigation pane, choose Policies.

  7. Choose Create Policy.

  8. Beside Create Your Own Policy, choose Select.

  9. Type a policy name (for example, SystemsManagerUserFull) and description, and then paste the policy you copied earlier into the Policy Document field

  10. Change the policy as you want.

  11. Choose Validate Policy. Verify that the policy is valid. If you receive an error, verify that you included the opening and closing brackets { }. After the policy is validated, choose Create Policy.

Create a Restrictive IAM User Policy

Create restrictive IAM user policies to further delegate access to Systems Manager. The following example IAM policy allows a user to do the following.

  • List Systems Manager documents and document versions.

  • View details about documents.

  • Send a command using the document specified in the policy.

    The name of the document is determined by this entry:

    arn:aws:ssm:us-east-1:*:document/name_of_restrictive_document
  • Send a command to three instances.

    The instances are determined by the following entries in the second Resource section:

    "arn:aws:ec2:us-east-1:*:instance/i-1234567890abcdef0",
    "arn:aws:ec2:us-east-1:*:instance/i-0598c7d356eba48d7",
    "arn:aws:ec2:us-east-1:*:instance/i-345678abcdef12345",
  • View details about a command after it has been sent.

  • Start and stop Automation executions.

  • Get information about Automation executions.

If you want to give a user permission to use this document to send commands on any instance for which the user currently has access (as determined by their AWS user account), you could specify the following entry in the Resource section and remove the other instance entries.

"arn:aws:ec2:us-east-1:*:instance/*"

Note that the Resource section includes an Amazon S3 ARN entry:

arn:aws:s3:::bucket_name

You can also format this entry as follows:

arn:aws:s3:::bucket_name/*

-or-

arn:aws:s3:::bucket_name/key_prefix_name
Copy
{ "Version":"2012-10-17", "Statement":[ { "Action":[ "ssm:ListDocuments", "ssm:ListDocumentsVersions", "ssm:DescribeDocument", "ssm:GetDocument", "ssm:DescribeInstanceInformation", "ssm:DescribeDocumentParameters", "ssm:DescribeInstanceProperties" ], "Effect":"Allow", "Resource":"*" }, { "Action":"ssm:SendCommand", "Effect":"Allow", "Resource": [ "arn:aws:ec2:us-east-1:*:instance/i-1234567890abcdef0", "arn:aws:ec2:us-east-1:*:instance/i-0598c7d356eba48d7", "arn:aws:ec2:us-east-1:*:instance/i-345678abcdef12345", "arn:aws:s3:::bucket_name", "arn:aws:ssm:us-east-1:*:document/name_of_restrictive_document" ] }, { "Action":[ "ssm:CancelCommand", "ssm:ListCommands", "ssm:ListCommandInvocations" ], "Effect":"Allow", "Resource":"*" }, { "Action":"ec2:DescribeInstanceStatus", "Effect":"Allow", "Resource":"*" }, { "Action":"ssm:StartAutomationExecution", "Effect":"Allow", "Resource":[ "arn:aws:ssm:::automation-definition/" ] }, { "Action":"ssm:DescribeAutomationExecutions ", "Effect":"Allow", "Resource":[ "*" ] }, { "Action":[ "ssm:StopAutomationExecution", "ssm:GetAutomationExecution" ], "Effect":"Allow", "Resource":[ "arn:aws:ssm:::automation-execution/" ] } ] }

For more information about creating IAM user policies, see Managed Policies and Inline Policies.

Task 3: Create a Role for Systems Manager Managed Instances

The instance role enables the instance to communicate with the Systems Manager API. The role uses the instance policy you created earlier.

To create a role for Systems Manager managed instances

  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. On the Select role type page, under AWS Service Role, choose Select in the Amazon EC2 section.

  4. On the Attach Policy page, use the filter box to search for the policy you created in the previous procedure. Choose the policy, and then choose Next Step.

  5. On the Set role name and review page, type a name in the Role name box, and then type a description.

    Note

    Make a note of the role name. You will specify this role name when you create new instances that you want to manage using Systems Manager.

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

Task 4: Verify the Trust Policy

Use the following procedure to verify that the IAM policy for your instance profile role includes ssm.amazonaws.com as a trusted entity.

To verify the trust policy

  1. In the navigation pane of the IAM console, choose Roles, and then choose the server role you just created.

  2. Choose Trust Relationships.

  3. Under Trusted Entities, choose Edit Trust Relationship.

  4. Copy and paste the following policy into the Policy Document field and create the policy:

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

Task 5: Create the User Account

The user account enables a user to call the Systems Manager API on an instance. This account uses the IAM user policy you created earlier.

To create a user account for Systems Manager

  1. From the Users page on the IAM console, choose Add User.

  2. In the Set user details section, specify a user name (for example, SystemsManagerUserFullAccess).

  3. In the Select AWS access type section, choose one or both access options. If you choose AWS Management Console access, you must also choose passwords options.

  4. Choose Next:Permissions.

  5. In the Set permissions for section, choose Attach existing policies directly.

  6. In the filter field, type the name of the user policy you created earlier.

  7. Choose the checkbox beside the policy, and then choose Next:Review.

  8. Verify the details, and then choose Create.

Create an Amazon EC2 instance that uses the custom instance role you created. For more information, see Task 3: Create an Amazon EC2 Instance that Uses the Systems Manager Role.