Enforce a session document permission check for the AWS CLI

When you configure Session Manager for your account, the system creates a Session type document SSM-SessionManagerRunShell. This document stores your session preferences, such as whether session data is saved in an Amazon Simple Storage Service (Amazon S3) bucket or Amazon CloudWatch Logs log group, whether session data is encrypted using AWS Key Management Service (AWS KMS), and whether Run As support is allowed for your sessions. The following is an example.

{
  "schemaVersion": "1.0",
  "description": "Document to hold regional settings for Session Manager",
  "sessionType": "Standard_Stream",
  "inputs": {
    "s3BucketName": "doc-example-bucket",
    "s3KeyPrefix": "BucketPrefix",
    "s3EncryptionEnabled": true,
    "cloudWatchLogGroupName": "LogGroupName",
    "cloudWatchEncryptionEnabled": true,
    "kmsKeyId": "kms-key",
    "runAsEnabled": true,
    "runAsDefaultUser": "RunAsUser"
  }
}

By default, when a user in your account has been granted permission to start sessions by their AWS Identity and Access Management (IAM) policy, they are also granted access to the SSM-SessionManagerRunShell SSM document. This means that when they use the AWS CLI to run the start-session command, and they don't specify a document in the --document-name option, the system uses SSM-SessionManagerRunShell and launches the session. The session starts even if the user’s IAM policy doesn’t grant explicit permission to access the SSM-SessionManagerRunShell document.

For example, the following command doesn’t specify a Session document.

aws ssm start-session \
    --target i-02573cafcfEXAMPLE

The following example specifies the default Session Manager Session document.

aws ssm start-session \
    --document-name SSM-SessionManagerRunShell \
    --target i-02573cafcfEXAMPLE

To restrict access to the default or any Session document, you can add a condition element to the user's IAM policy that validates whether the user has explicit access to a Session document. When this condition is applied, the user must specify a value for the --document-name option of the start-session AWS CLI command. This value is either the default Session Manager Session document or a custom Session document you created. The following condition element, when added to the ssm:StartSession action in the IAM policy, performs a session document access check.

"Condition": {
    "BoolIfExists": {
        "ssm:SessionDocumentAccessCheck": "true"
    }
}

With this condition element set to true, explicit access to a Session document must be granted in the IAM policy for the user to start a session. To ensure the condition element is enforced, it must be included in all policy statements which allow the ssm:StartSession action. The following is an example.

{
    "Effect": "Allow",
    "Action": [
        "ssm:StartSession"
    ],
    "Resource": [
        "arn:aws:ec2:us-west-2:123456789012:instance/i-02573cafcfEXAMPLE",
        "arn:aws:ssm:us-west-2:123456789012:document/SSM-SessionManagerRunShell"
    ] 
}

If the SessionDocumentAccessCheck condition element is set to false, it will not affect the evaluation of the IAM policy. That means if the SessionDocumentAccessCheck condition element is set to true, and you specify a document name in the Resource, you must provide the specified document name when starting a session. If you provide a different document name when starting a session, the request fails.

If the SessionDocumentAccessCheck condition element is set to false, and a document name is not specified in the Resource, you do not need to provide a document name when you start a session. By default, the SSM-SessionManagerRunShell document is used in the request.

For an example of specifying a Session Manager Session document in an IAM policy, see Quickstart end user policies for Session Manager.

Other scenarios

Using the default SSM-SessionManagerRunShell session document is the only case when a document name can be omitted from the start-session CLI command. In other cases, the user must specify a value for the --document-name option of the start-session AWS CLI command. The system checks whether the user has explicit access to the Session document they specify.

For example, if a user specifies the name of a custom Session document you created, the user’s IAM policy must grant them permission to access that document.

If a user runs a command to start a session using SSH, the user’s policy must grant them access to the AWS-StartSSHSession session document.

Note

To start a session using SSH, configuration steps must be completed on both the target managed node and the user's local machine. For information, see (Optional) Enable and control permissions for SSH connections through Session Manager.