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. 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 AWS Identity and Access Management (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:
-
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 =
, continue to step 2.os-user-account-name
-
If the IAM user's account or role hasn't been tagged with
SSMSessionRunAs =
, has an OS user name been specified in the AWS account's Session Manager preferences?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.
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 anssm-user
account on an instance.
To enable Run As support for Linux and macOS instances
-
Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/
. -
In the navigation pane, choose Session Manager.
-
Choose the Preferences tab, and then choose Edit.
-
Select the check box next to Enable Run As support for Linux instances.
-
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.
-
-
Choose Save.