Menu
Sign In to the Console
Amazon Elastic Compute Cloud
User Guide for Linux Instances

Delegating Access to SSM Run Command

You can limit access to SSM Run Command by using custom SSM documents and IAM policies. The commands or scripts specified in SSM documents run with administrative privilege on your instances because the Amazon SSM agent runs as root. A user who has permission to execute any of the predefined SSM documents (any document that begins with AWS-*) also has administrator access to the instance.

You should delegate access to SSM and Run Command judiciously. This becomes extremely important if you create your own SSM documents. AWS does not provide guidance about how to create secure SSM documents. You create SSM documents and delegate access to Run Command actions at your own risk. As a security best practice, we recommend that you assign access to "AWS-*" documents, especially the AWS-RunShellScript document, to trusted administrators only. You can create SSM documents for specific tasks and delegate access to non-administrators.

This topic includes the following:

Create a Restrictive IAM User Policy

The IAM user policy determines which SSM documents a user can see in the Command document list. Users can see this list in either the Amazon EC2 console or by calling ListDocuments using the AWS CLI.

The policy also limits the actions the user can perform with an SSM document. The following example IAM policy allows a user to list SSM documents and view details about those documents, send a command using the document, and cancel or view details about the command after it has been sent. The user has permission to execute the document on three instances, as determined by the "arn:aws:ec2:us-east-1:*:instance/i-xxxxxxxxxxxxxxxxx" items in the second Resource section. If you want to give the user access to run the command on any instance for which the user currently has access (as determined by the AWS user account), you could specify "arn:aws:ec2:us-east-1:*:instance/*" in the Resource section and remove the other instance resources.

Note

The Resource section in the following JSON example includes an S3 ARN entry:

arn:aws:s3:::bucket_name

You can also format this entry as follows:

arn:aws:s3:::bucket_name/*

arn:aws:s3:::bucket_name/key_prefix_name

{
     "Version": "2012-10-17",
     "Statement": [
           {
                "Action": [
                     "ssm:ListDocuments",
                     "ssm:DescribeDocument",
                     "ssm:GetDocument",
                     "ssm:DescribeInstanceInformation"
                ],
                "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/RestartLinuxService"
                ]
           },
           {
                "Action": [
                	 "ssm:CancelCommand",
                     "ssm:ListCommands",
                     "ssm:ListCommandInvocations"
                ],
                "Effect": "Allow",
                "Resource": "*"
           },
           {
                "Action": "ec2:DescribeInstanceStatus",
                "Effect": "Allow",
                "Resource": "*"
           }
     ]
}

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

After creating the IAM policy and assigning it to the user's account, the user can issue commands using the RestartLinuxService document from the Commands page in the Amazon EC2 console or using the AWS CLI. For example, the following CLI command runs the RestartLinuxService document:

aws ssm send-command --instance-ids "instance-ID" --document-name "RestartLinuxService" --parameter  serviceName="Service name to restart"

If the user attempts to run any other SSM document, the user would receive an authorization error.

Create a Restrictive SSM Document

When giving a user access to Run Command it's best to start with a policy of least privilege. Create different SSM documents that allow the user to do a minimum number of tasks. For example, you could specify the name of a specific service on an instance so that a Run Command user could only restart that service.

To create a restrictive SSM document

  1. Copy and paste the following JSON example into a text file and save it with a .json file extension.

    {
  "schemaVersion": "1.2",
  "description": "Restart Linux Service",
  "parameters": {
    "serviceName": {
      "type": "String",
      "description": "(Required) Specify the name of the service to restart",
      "maxChars": 256
    }
  },
  "runtimeConfig": {
    "aws:runShellScript": {
      "properties": [
        {
          "runCommand": ["service {{ serviceName }} restart"]
        }
      ]
    }
  }
}

  2. Execute the following command in the AWS CLI. 

    aws ssm create-document --content file:///tmp/RestartLinuxService.json --name "RestartLinuxService"

For more information about creating SSM documents, see SSM Documents in the Amazon EC2 Simple Systems Manager API Reference.