Configuring AWS Systems Manager Session Manager run as support for federated users using session tags

In this blog post, we share a procedure for configuring AWS Systems Manager Session Manager run as support for Active Directory (AD) federated users using AWS Security Token Service (AWS STS) session tags. We show you how to start a Session Manager session using the AD user name of the federated user on an AD-joined Linux instance.

Background

Session Manager is an AWS Systems Manager capability that lets you manage your Amazon Elastic Compute Cloud (Amazon EC2) instances, on-premises instances, and virtual machines (VMs) through an interactive one-click browser-based shell or through the AWS CLI. Session Manager provides secure instance management without the need to open inbound ports, maintain bastion hosts, or manage SSH keys.

By default, sessions are launched using the credentials of a system-generated ssm-user account that is created on a managed instance. On instances running Linux, you can optionally launch sessions using the credentials of an operating system account. You can configure run as support for Linux instances in the Session Manager preferences. Session Manager provides two methods for specifying the operating system account to use.

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

Using this method, all sessions are run by the same OS user for all the AWS Identity and Access Management (IAM) users in your account who connect to the instance using Session Manager.

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

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

This works perfectly for individual IAM users and roles. When it comes to the case of federated users, multiple users could assume the same role. You cannot tag the role with multiple values for SSMSessionRunAs tag. In this case, you can apply SSMSessionRunAs tag as a Principal tag to the STS session when your users federate into AWS, using standards-based SAML. You can configure your identity provider (IdP) to pass the user attribute during federation and the session will be tagged using the attribute value. For more information about pass-in attributes for federated users, see the New for Identity Federation – Use Employee Attributes for Access Control in AWS blog post.

In this post, we will walk you through the steps to pass the AD username attribute to the SAML assertion and use it to apply the SSMSessionRunAs tag to the STS Session using Active Directory Federation Services (ADFS). We also show you how you can use the SSMSessionRunAs tag to enable run as support for Session Manager sessions started by federated users.

Solution overview

Here is a diagram of the solution architecture.

                                               Figure 1: Solution architecture diagram

The workflow includes the following steps:

1. Corporate user browses to the ADFS portal sign-in page and provides Active Directory authentication credentials.
2. The IdP authenticates the user and returns a SAML assertion that includes the PrincipalTag:SSMSessionRunAs=username.
3. Client posts the assertion to the AWS SAML endpoint.
4. The endpoint validates the assertion with an AWS STS endpoint and requests temporary security credentials on behalf of the user.
5. Temporary credentials are returned using AWS STS AssumeRoleWithSAML. The session will be tagged with PrincipalTag:SSMSessionRunAs
6. The endpoint sends the sign-in URL back to the client as a redirect.
7. The client browser is redirected to AWS Management Console.
8. The client accesses the AWS Systems Manager console and starts the Session Manager session for a Linux instance.
9. Session Manager starts the session using the user name specified for the SSMSessionRunAs tag for the federated session.
10. Session starts in the given AD user context and a browser-based shell opens in a new tab.

Prerequisites

To complete this walkthrough, you need the following:

• An AWS account.
• IAM permissions to create and update IAM resources and to use AWS Systems Manager. For information, see AWS managed policies for AWS Systems Manager.
• AD to store the identities and ADFS for AWS federation. For this blog post, the IdP is configured as described in the Active Directory Federation Services and Active Directory Domain Services on a EC2 Windows Instance blog post. You can also use your on-premises Active Directory and ADFS farm. For more information, see the Enabling Federation to AWS Using Windows Active Directory, ADFS, and SAML 2.0 blog post.
• An Amazon Linux EC2 instance. For information, see Setting up AWS Systems Manager.

You must also complete the following tasks:

• Create two AD users, Bob and Alice, in your domain.
• Add the users to AD groups for ADFS federation.
• Enable run as support for Linux instances in Session Manager preferences.
• Join the EC2 Linux instance to your Active Directory. For information, see Manually Join a Linux Instance.
• (Optional) If you want to test the sudo access delegation based on AD groups, create two groups: NetworkAdmins and SysAdmins. Add user Bob to NetworkAdmins and Alice to SysAdmins.

Modify IAM role for SAML-based federation

Step 1: Edit the trust policy for the ADFS role

Your IdP needs permissions to add tags to the STS sessions it creates. Add the sts:TagSession action to the trust policy (also known as the assume role policy) document associated with each of the IAM roles that you have configured ADFS to use.

The following is the sample trust policy. Replace account-id with your account values.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::account-id:saml-provider/ADFS"
      },
      "Action": [
        "sts:AssumeRoleWithSAML",
        "sts:TagSession"
      ],
      "Condition": {
        "StringEquals": {
          "SAML:aud": "https://signin.aws.amazon.com/saml"
        },
        "StringLike": {
          "aws:RequestTag/SSMSessionRunAs": "*"
        }
      }
    }
  ]
}

Step 2: Create an IAM customer managed policy that allows federated users to start and terminate Session Manager sessions

Create an IAM policy named EC2SSMPermissions with following policy statement. Ensure that this policy is attached only to the role that is used for federated users. (You can make further restrictions to the resources, if you like.)

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ec2:DescribeInstances",
                "ssm:DescribeSessions",
                "ssm:DescribeInstanceProperties",
                "ssm:GetConnectionStatus"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": "ssm:StartSession",
            "Resource": [
                "arn:aws:ec2:*:*:instance/*"            
             ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "ssm:TerminateSession"
            ],
            "Resource": "*",
            "Condition": {
                "StringLike": {
                    "ssm:resourceTag/aws:ssmmessages:session-id": [
                        "${aws:userid}"
                    ]
                }
            }
        }
    ]
}

The first statement block in this policy lets federated users navigate to the AWS Systems Manager console, list the EC2 instances available to connect, and view Session Manager sessions.

The second statement allows the user to start a session on a given instance using the default SSM-SessionManagerRunShell session document. You can also allow the users to start sessions based on the tags applied to the target instances. For more sample policies, see Control user session access to instances section in the AWS Systems Manager User Guide.

The last statement allows federated users to terminate their own sessions only and prevents them from terminating other user sessions. When a federated user starts a session, Session Manager applies the resource tag, aws:ssmmessages:session-id, with a value in the format of role-id:caller-specified-role-name. For federated users, we can use the {aws:userid} variable in the IAM policy to match this value.

Step 3: Attach the policy to the IAM role for SAML-based federation

Attach the EC2SSMPermissions IAM policy created in the previous step to the role for SAML-based federation.

ADFS session tagging setup

After you’ve set up ADFS federation to AWS, you can enable the sending of other attributes in the SAML token.

Follow these steps to send the Active Directory login name attribute to AWS in the SAML token as PrincipalTag:SSMSessionRunAs.

1. In the ADFS server, open Server Manager, choose Tools, then choose AD FS Management.
2. Under Relying Party Trusts, choose the trust for AWS. Right-click and choose Edit Claim Issuance Policy.

                                                                           Figure 2: Relying Party Trusts

3. Under Issuance Transform Rules, choose Add Rule.

             Figure 3: Edit Claim Issuance Policy for AWS dialog box

4. For Claim rule template, choose Send LDAP Attributes as Claims, and then choose Next.

                                                                        Figure 4: Select Rule Template

5. In the Configure Claim Rule section, add the following values, and then choose Finish.

• • Claim rule name: SSMSessionRunAs
  • Attribute Store: Active Directory
  • LDAP Attribute: User-Principal-Name
  • Outgoing Claim Type:
    https://aws.amazon.com/SAML/Attributes/PrincipalTag:SSMSessionRunAs

                                                                         Figure 5: Configure Rule

6. Select SSMSessionRunAs in the list and choose Apply.

                Figure 6: SSMSessionRunAs in the list of transform rules

(Optional) AD group based sudo access configuration

It is a common requirement to control the sudo access for users in a Linux instance. Now that the Linux instance is joined to the AD domain and federated users can start a session using their own AD user name, it is possible to control the sudo access based on the user’s AD groups. To configure this, you must have added the users to the required AD groups as mentioned in the prerequisites.

Follow these steps to configure the sudo access based on AD groups. For this walkthrough, we have created two AD groups: NetworkAdmins and SysAdmins. User Bob has been added to NetworkAdmins and Alice to SysAdmins.

1. Use SSH to connect to the Linux instance as an admin user.
2. Use the following command to create the suoders file for AD users.

# sudo visudo -f /etc/sudoers.d/domain-user

3. Add the following to the suoders file and then save it.

## Network Commands

Cmnd_Alias NW_CMDS = /usr/sbin/ip, /usr/sbin/route, /usr/bin/netstat, /usr/sbin/ifconfig

## Add the "SysAdmins" group from example.com domain

%SysAdmins@example.com ALL=(ALL:ALL) ALL

## Add the "NetworkAdmins" group from example.com domain

%NetworkAdmins@example.com ALL=(ALL) NOPASSWD: NW_CMDS

With this sudo configuration, Alice will be able to execute all commands as a root user after she enters her AD password. Bob will be able to execute networking-related commands as a root user without entering a password. This example is provided for illustrative purposes only. In a real- world scenario, you can prevent users from executing commands without a password, if required.

Test the solution

To test the solution, sign in to the AWS Management Console through ADFS federation and start a Session Manager session.

1. Open a web browser and navigate to the ADFS sign-in page for your domain.

     https://your-domain-name/adfs/ls/IdpInitiatedSignOn.aspx

2. Sign in as user bob@your_domain and use the AD password to authenticate.

3. Select the ADFS role with Session Manager permissions.

4. Choose Sign In.

5. In the AWS Management Console, navigate to the AWS Systems Manager

                                                             Figure 7: AWS Management Console

6. In the AWS Systems Manager console, under Instances & Nodes,choose Session Manager.

                                                              Figure 8: AWS Systems Manager console

7. Choose Start session.

                                                  Figure 9: Sessions page in the Systems Manager console

8. From the managed instances in the list, choose your AD-joined Linux instance, and then choose Start Session.

                                                 Figure 10: Start a session page in the console

Session Manager will start a new session. You will be redirected to a tab that opens a web-based shell access session to your Linux instance. This session will be started using the AD user name of your federated user instead of the default ssm-user.

                                                     Figure 11: Sample session for user Bob

Now, sign in as another AD user (for example, Alice) and start a Session Manager session on the same instance.

                                                   Figure 12: Starting session as user Alice

This time, the session will be started using the AD user name of user Alice.

                                                    Figure 13: Sample session for user Alice

Conclusion

In this post, we showed you how to configure Session Manager run as support for Active Directory federated users using AWS STS session tags. By adopting this solution, your Active Directory users can start sessions using their AD user name in managed Linux instances that are joined to AD.

About the Authors

 
Renjith is a Cloud Support Engineer at AWS Premium Support. He is an AWS certified Solution Architect Professional who specializes in AWS Systems Manager and Amazon EC2 Linux. In his role, he enjoys helping customers solve the toughest challenges in their cloud journey. In his free time, he enjoys spending time with friends and family and watching movies.

 
Shreejesh is a Cloud Architect with AWS Professional Services. Learning is his passion. He holds various AWS certifications and a Master of Business Administration degree. He provides customers with technical guidance for implementing networking and security best practices. Outside of work, Shreejesh loves to play badminton and spend time with his family.