Step 5: (Optional) Restrict access to commands in a session - Amazon Systems Manager
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

Step 5: (Optional) Restrict access to commands in a session

You can restrict the commands a user can run in a Amazon Systems Manager Session Manager session by creating a custom Session type Amazon Systems Manager (SSM) document. In the document content, you define which command is run when the user starts a session and what parameters they can provide to the command. These are also referred to as interactive commands. The Session document schemaVersion must be 1.0, and the sessionType of the document must be InteractiveCommands. You can then create Amazon Identity and Access Management (IAM) policies that allow users to access only the Session documents you define. For more information about using IAM policies to restrict access to commands in a session, see IAM policy examples for interactive commands.

Custom Session type SSM documents can only be used when starting sessions from the Amazon Command Line Interface (Amazon CLI). The user specifies the allowed document in the --document-name option for the start-session command and provides any necessary parameter values for the command in the --parameters option. For more information about running interactive commands, see Starting a session (interactive and noninteractive commands).

The following procedure describes how to create a custom Session type SSM document that defines the command a user is allowed to run.

Restrict access to commands in a session (console)

To restrict the commands a user can run in a Session Manager session (console)

  1. Open the Amazon Systems Manager console at https://console.amazonaws.cn/systems-manager/.

  2. In the navigation pane, choose Documents.

  3. Choose Create command or session.

  4. For Name, enter a descriptive name for the document.

  5. For Document type, choose Session document.

  6. Enter your document content that defines the command a user can run in a Session Manager session using JSON or YAML, as shown in the following example.

    YAML
    --- schemaVersion: '1.0' description: Document to view a log file on a Linux instance sessionType: InteractiveCommands parameters: logpath: type: String description: The log file path to read. default: "/var/log/amazon/ssm/amazon-ssm-agent.log" allowedPattern: "^[a-zA-Z0-9-_/]+(.log)$" properties: linux: commands: "tail -f {{ logpath }}" runAsElevated: true
    JSON
    { "schemaVersion": "1.0", "description": "Document to view a log file on a Linux instance", "sessionType": "InteractiveCommands", "parameters": { "logpath": { "type": "String", "description": "The log file path to read.", "default": "/var/log/amazon/ssm/amazon-ssm-agent.log", "allowedPattern": "^[a-zA-Z0-9-_/]+(.log)$" } }, "properties": { "linux": { "commands": "tail -f {{ logpath }}", "runAsElevated": true } } }
  7. Choose Create document.

Restrict access to commands in a session (command line)

Before you begin

If you haven't already, install and configure the Amazon Command Line Interface (Amazon CLI) or the Amazon Tools for PowerShell. For information, see Install or upgrade Amazon command line tools.

To restrict the commands a user can run in a Session Manager session (command line)

  1. Create a JSON or YAML file for your document content that defines the command a user can run in a Session Manager session, as shown in the following example.

    YAML
    --- schemaVersion: '1.0' description: Document to view a log file on a Linux instance sessionType: InteractiveCommands parameters: logpath: type: String description: The log file path to read. default: "/var/log/amazon/ssm/amazon-ssm-agent.log" allowedPattern: "^[a-zA-Z0-9-_/]+(.log)$" properties: linux: commands: "tail -f {{ logpath }}" runAsElevated: true
    JSON
    { "schemaVersion": "1.0", "description": "Document to view a log file on a Linux instance", "sessionType": "InteractiveCommands", "parameters": { "logpath": { "type": "String", "description": "The log file path to read.", "default": "/var/log/amazon/ssm/amazon-ssm-agent.log", "allowedPattern": "^[a-zA-Z0-9-_/]+(.log)$" } }, "properties": { "linux": { "commands": "tail -f {{ logpath }}", "runAsElevated": true } } }
  2. Run the following commands to create an SSM document using your content that defines the command a user can run in a Session Manager session.

    Linux & macOS
    aws ssm create-document \ --content file://path/to/file/documentContent.json \ --name "exampleAllowedSessionDocument" \ --document-type "Session"
    Windows
    aws ssm create-document ^ --content file://C:\path\to\file\documentContent.json ^ --name "exampleAllowedSessionDocument" ^ --document-type "Session"
    PowerShell
    $json = Get-Content -Path "C:\path\to\file\documentContent.json" | Out-String New-SSMDocument ` -Content $json ` -Name "exampleAllowedSessionDocument" ` -DocumentType "Session"

Interactive command parameters and the Amazon CLI

There are a variety of ways you can provide interactive command parameters when using the Amazon CLI. Depending on the operating system (OS) of your client machine that you use to connect to managed nodes with the Amazon CLI, the syntax you provide for commands that contain special or escape characters might differ. The following examples show some of the different ways you can provide command parameters when using the Amazon CLI, and how to handle special or escape characters.

Parameters stored in Parameter Store can be referenced in the Amazon CLI for your command parameters as shown in the following example.

Linux & macOS
aws ssm start-session \ --target instance-id \ --document-name MyInteractiveCommandDocument \ --parameters '{"command":["{{ssm:mycommand}}"]}'
Windows
aws ssm start-session ^ --target instance-id ^ --document-name MyInteractiveCommandDocument ^ --parameters '{"command":["{{ssm:mycommand}}"]}'

The following example shows how you can use a shorthand syntax with the Amazon CLI to pass parameters.

Linux & macOS
aws ssm start-session \ --target instance-id \ --document-name MyInteractiveCommandDocument \ --parameters command="ifconfig"
Windows
aws ssm start-session ^ --target instance-id ^ --document-name MyInteractiveCommandDocument ^ --parameters command="ipconfig"

You can also provide parameters in JSON as shown in the following example.

Linux & macOS
aws ssm start-session \ --target instance-id \ --document-name MyInteractiveCommandDocument \ --parameters '{"command":["ifconfig"]}'
Windows
aws ssm start-session ^ --target instance-id ^ --document-name MyInteractiveCommandDocument ^ --parameters '{"command":["ipconfig"]}'

Parameters can also be stored in a JSON file and provided to the Amazon CLI as shown in the following example. For more information about using Amazon CLI parameters from a file, see Loading Amazon CLI parameters from a file in the Amazon Command Line Interface User Guide.

{ "command": [ "my command" ] }
Linux & macOS
aws ssm start-session \ --target instance-id \ --document-name MyInteractiveCommandDocument \ --parameters file://complete/path/to/file/parameters.json
Windows
aws ssm start-session ^ --target instance-id ^ --document-name MyInteractiveCommandDocument ^ --parameters file://complete/path/to/file/parameters.json

You can also generate an Amazon CLI skeleton from a JSON input file as shown in the following example. For more information about generating Amazon CLI skeletons from JSON input files, see Generating Amazon CLI skeleton and input parameters from a JSON or YAML input file in the Amazon Command Line Interface User Guide.

{ "Target": "instance-id", "DocumentName": "MyInteractiveCommandDocument", "Parameters": { "command": [ "my command" ] } }
Linux & macOS
aws ssm start-session \ --cli-input-json file://complete/path/to/file/parameters.json
Windows
aws ssm start-session ^ --cli-input-json file://complete/path/to/file/parameters.json

To escape characters inside quotation marks, you must add additional backslashes to the escape characters as shown in the following example.

Linux & macOS
aws ssm start-session \ --target instance-id \ --document-name MyInteractiveCommandDocument \ --parameters '{"command":["printf \"abc\\\\tdef\""]}'
Windows
aws ssm start-session ^ --target instance-id ^ --document-name MyInteractiveCommandDocument ^ --parameters '{"command":["printf \"abc\\\\tdef\""]}'

For information about using quotation marks with command parameters in the Amazon CLI, see Using quotation marks with strings in the Amazon CLI in the Amazon Command Line Interface User Guide.

IAM policy examples for interactive commands

You can create IAM policies that allow users to access only the Session documents you define. This restricts the commands a user can run in a Session Manager session to only the commands defined in your custom Session type SSM documents.

Allow a user to run an interactive command on a single managed node
{ "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":"ssm:StartSession", "Resource":[ "arn:aws-cn:ec2:region:987654321098:instance/i-02573cafcfEXAMPLE", "arn:aws-cn:ssm:region:987654321098:document/exampleAllowedSessionDocument" ], "Condition":{ "BoolIfExists":{ "ssm:SessionDocumentAccessCheck":"true" } } } ] }
Allow a user to run an interactive command on all managed nodes
{ "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":"ssm:StartSession", "Resource":[ "arn:aws-cn:ec2:us-west-2:987654321098:instance/*", "arn:aws-cn:ssm:us-west-2:987654321098:document/exampleAllowedSessionDocument" ], "Condition":{ "BoolIfExists":{ "ssm:SessionDocumentAccessCheck":"true" } } } ] }
Allow a user to run multiple interactive commands on all managed nodes
{ "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":"ssm:StartSession", "Resource":[ "arn:aws-cn:ec2:us-west-2:987654321098:instance/*", "arn:aws-cn:ssm:us-west-2:987654321098:document/exampleAllowedSessionDocument", "arn:aws-cn:ssm:us-west-2:987654321098:document/exampleAllowedSessionDocument2" ], "Condition":{ "BoolIfExists":{ "ssm:SessionDocumentAccessCheck":"true" } } } ] }