Start a session with a document by specifying the session documents in IAM policies

If you use the start-session AWS CLI command using the default session document, you can omit the document name. The system automatically calls the SSM-SessionManagerRunShell session document.

In all other cases, you must specify a value for the document-name parameter. When a user specifies the name of a session document in a command, the systems checks their IAM policy to verify they have permission to access the document. If they don't have permission, the connection request fails. The following examples includes the document-name parameter with the AWS-StartPortForwardingSession session document.

aws ssm start-session \
    --target i-02573cafcfEXAMPLE \
    --document-name AWS-StartPortForwardingSession \
    --parameters '{"portNumber":["80"], "localPortNumber":["56789"]}'

Enforce a session document permission check when starting a session

To restrict access to the AWS-StartPortForwardingSession 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 command. 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. Here is an example.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "EnableSSMSession",
            "Effect": "Allow",
            "Action": [
                "ssm:StartSession"
            ],
            "Resource": [
                "arn:aws:ec2:us-west-2:123456789012:instance/i-02573cafcfEXAMPLE",
                "arn:aws:ssm:us-west-2::document/AWS-StartPortForwardingSession"
            ],
            "Condition": {
                "BoolIfExists": {
                    "ssm:SessionDocumentAccessCheck": "true"
                }
            }
        }
    ]
}

With this IAM policy in place, if the SessionDocumentAccessCheck condition element is set to true, users must enter the document-name parameter in their command when starting a session using the AWS CLI. The value of document-name must be the document specified in the Resource section of the IAM policy. If the user enters a different document name or they don't specify the document-name parameter, the request fails.

If the SessionDocumentAccessCheck condition element is set to false, it doen't affect the evaluation of the IAM policy.

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

Other scenarios

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) Allow and control permissions for SSH connections through Session Manager.