Enable run as support for Linux and macOS instances

By default, sessions are launched using the credentials of a system-generated ssm-user account that is created on a managed instance. (On Linux and macOS machines, this account is added to /etc/sudoers/.) You can instead launch sessions using the credentials of an operating system (OS) account. OS level and directory policies, like log in restrictions, might not apply to the OS account since sessions are authenticated by AWS Identity and Access Management (IAM) and run within the context of the OS account that you specify. Session Manager verifies the OS account that you specify exists before starting a session. If you specify an OS account that does not exist, the session fails to start. Session Manager provides two methods for specifying the operating system account to use.

Method 1: Tag an IAM user or role (recommended)

You can specify the operating system user account that is used to start sessions by tagging an IAM user or associated role with the AWS-provided key name SSMSessionRunAs, and specifying the OS user name as its value. For example, if the OS user account name is DevRoleLogin, the corresponding tag to use is SSMSessionRunAs = DevRoleLogin.

Using this method, you could specify a different OS account name for each IAM user or role you tag, or use the same OS user name for them all.

For more information about tagging IAM entities, see the following topics:

• Tagging IAM Entities in the IAM User Guide

• Add Tags to Manage Your AWS IAM Users and Roles on the AWS Security Blog

Method 2: Specify an OS user name in Session Manager preferences

When you configure Session Manager preferences in the console or by using the AWS Command Line Interface (AWS CLI), you can specify the operating system user name to start sessions with.

Using this method, all sessions are run by the same OS user for all the IAM users in your account who connect to the instance using Session Manager.

How it works

If you enable Run As support for sessions, the system checks for access permissions as follows:

1. For the user who is starting the session, has their IAM user account or role been tagged with SSMSessionRunAs = os-user-account-name?

   If Yes, does the user name exist on the instance? If it does, start the session. If it does not, do not allow a session to start.

   If the IAM user's account or role has not been tagged with SSMSessionRunAs = os-user-account-name, continue to step 2.

2. If the IAM user's account or role hasn't been tagged with SSMSessionRunAs = os-user-account-name, has an OS user name been specified in the AWS account's Session Manager preferences?

   If Yes, does the user name exist on the instance? If it does, start the session. If it does not, do not allow a session to start.

   At this point, Session Manager does not fall back on the default ssm-user account. In other words, enabling Run As support prevents sessions from being started using an ssm-user account on an instance.

To enable Run As support for Linux and macOS instances

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Session Manager.

3. Choose the Preferences tab, and then choose Edit.

4. Select the check box next to Enable Run As support for Linux instances.

5. Do one of the following:

   • Option 1: For (Optional) Enter an operating system user name for starting sessions, enter the name of the operating system user account on the target instance that you want to use to start sessions.

   • Option 2: Choose the IAM console link. In the navigation pane, choose either Users or Roles. Choose the entity (user or role) to add tags to, and then choose the Tags tab. Enter SSMSessionRunAs for the key name. Enter the name of a user account on your target instance for the key value. Choose Save changes.

     The following is an example.

     

6. Choose Save.