Configure Session Manager access for federated users using SAML session tags

In this blog post, we show you how to configure Attribute-Based Access Control (ABAC) permissions to federate users into AWS Systems Manager Session Manager. We demonstrate how you can use attributes defined in external identity systems as part of the ABAC decisions within AWS, with SAML session tags. For example, you can grant access to specific managed instances based on the department that your AWS Identity and Access Management (IAM) user belongs to. For more information about pass-in attributes for federated users, see New for identity federation – use employee attributes for access control in AWS.

Session Manager allows you to manage your Amazon EC2 instances and your hybrid environments, including on-premises servers and virtual machines (VMs) and VMs hosted in other cloud environments, through an interactive one-click browser-based shell or AWS CLI. This is done in a secure and auditable way without having to open inbound ports, maintain bastion hosts, or manage SSH keys. Access permissions to Session Manager can be managed through IAM policies to control who can access or interact with what resources.

This post walks you through the steps to configure access permissions using SAML session tags and external identity attributes in order to restrict the AWS Systems Manager feature access.

Solution overview

The following architecture diagram presents an overview of the solution:

Figure 1: Solution architecture diagram

Let’s follow this example where Alice and Bob federate into AWS Management Console using their external Identity Provider (IdP). Both federated users MUST access specific EC2 instances using Session Manager based on their “department” membership, Amber and Blue respectively.

In this example we show IAM federation using Okta, but you can deploy this solution with any external Identity Providers who have worked to make sure that the attributes defined in their systems are correctly propagated to AWS sessions.

Prerequisites

To perform the steps to use SAML session tags for ABAC, you must already have deployed IAM federation with the external identity provider. For more information, check enabling SAML 2.0 federated users to access the AWS Management Console in the IAM user guide and how to configure SAML 2.0 for AWS on the Okta website.

You must have also configured your EC2 instances and Session Manager to create a console session to the instance via Session Manager. For more information, check getting started with Session Manager.

Implement the solution

To implement the solution, follow these steps:

1. Create the ABAC IAM policy.
2. Modify the IAM role for SAML-based federation.
3. Configure the Okta dynamic SAML attribute.
4. Modify the Okta users attribute.
5. Create EC2 tags for the managed instances.

Step 1 – Create the ABAC IAM policy

Create the following policy named CustomSessionManagerPolicy, based on the principle of least privilege (you will add this policy to the role in the following step):

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ec2:describeInstances",
                "ssm:DescribeSessions",
                "ssm:DescribeInstanceProperties",
                "ssm:GetConnectionStatus"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "ssm:StartSession"
            ],
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "ssm:resourceTag/department": "${aws:PrincipalTag/department}"
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": [
                "ssm:TerminateSession"
            ],
            "Resource": [
                "arn:aws:ssm:::session/${aws:PrincipalTag/login}-*"
            ]
        }
    ]
}

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

The second statement makes the Session Manager StartSession available to all resources only when this condition is matched: the value of the resources department tag matches the value of the principal department tag.

The third statement restricts Session Manager TerminateSession to session resources created by the same federated user. Session Manager constructs the resource session ARN using the principal who initiates the session, and the policy uses the principal tag login as the variable ${aws:PrincipalTag/login} to match the ARN.

Step 2 – Modify IAM role for SAML-based federation

Step 2A – Modify trust policy

Modify the role trust policy to add the AWS STS TagSession action required to allow passing session tags. Optionally add a second condition with StringLike to enforce specified session tags:

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

This statement allows federated users to assume the role and pass session tags when they federate into AWS from the Okta identity provider. The identity’s attributes can have any value for the login and department tags. For more information, check using SAML session tags for ABAC in the IAM user guide.

Step 2B – Add ABAC IAM policy

Attach the CustomSessionManagerPolicy permissions policy created in the previous step to the role for SAML-based federation. This is the role you created when you initially set up Okta federation via SAML (see Prerequisites above).

Step 3 – Configure the Okta dynamic SAML attribute

Important: To enable this feature, you may need to contact Okta customer support to ask for the feature flag OIN_SAML2_DYNAMIC_ATTRIBUTES  to be enabled.

Configure attributes under the SAML 2.0 sign-on method section by adding name, name format, and values, as shown here:

Check the SAML attributes in the Okta console:

Figure 2: The required SAML attributes as displayed in the Okta console

Before saving these changes, you can preview the SAML option to confirm these new SAML attributes:

<saml2:Attribute Name="https://aws.amazon.com/SAML/Attributes/PrincipalTag:login" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
    <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.login</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="https://aws.amazon.com/SAML/Attributes/PrincipalTag:department" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
    <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.department</saml2:AttributeValue>
</saml2:Attribute>

Step 4 – Modify the Okta users attribute

Modify Alice and Bob’s user profiles attribute value for department key to Amber and Blue respectively. The attribute value for login is already set by default using the user’s email, for example alice@example.com and bob@example.com.

The user attributes in the Okta console should look like:

Figure 3: Alice’s user profile attributes in the Okta console.

Figure 4: Bob’s user profile attributes in the Okta console

Step 5 – Create EC2 tags for the managed instances

Tag the required EC2 instance to allow access based on this resource attribute. In the EC2 console, choose to Add/Edit Tags. Make sure you use specific key:values for each instance, for example department:amber for the EC2 instance named amber-instance as shown:

Figure 5: Instance tags in the EC2 console

Test the solution

Log in to Okta using Alice’s credentials to then federate into the AWS Management Console by choosing the Amazon Web Services application.

Figure 6: Okta login console

Figure 7: AWS application in the Okta console

In the AWS Management Console, search for AWS Systems Manager. Once you are in AWS Systems Manager console, navigate to Session Manager, and choose Start a Session. You find listed managed EC2 instances available to connect. Choose amber-instance and Start Session.

Figure 8: Session Manager console

Because you have federated in using Alice’s credentials, the principal tag department value matches the resource tag value allowing the action to start a session. You are redirected to a new tab confirming access to the EC2 instance tagged with the key department and the value Amber.

Figure 9: Example of a Session Manager active Session

If you try to Start session choosing the EC2 instance called blue-instance you will get an (expected) not authorized message:

User: arn:aws:sts::123456789012:assumed-role/OktaUsers/alice@example.com is not authorized to perform: ssm:StartSession on resource: arn:aws:ec2:eu-west-3:123456789012:instance/i-0b0444bb293823cd0

You can only terminate a session that you have started. In this case, the session ID contains Alice’s principal tag login value and matches the ABAC policy resource to allow this action.

If you try to terminate a session started by Bob, you get the following (expected) not authorized message:

User: arn:aws:sts::123456789012:assumed-role/OktaUsers/alice@exampe.com is not authorized to perform: ssm:TerminateSession on resource: arn:aws:ssm:eu-west-3:123456789012:session/bob@example.com-01020dff18f1670d3

Conclusion

In this blog post, we have shown you how to use SAML attributes to control access to Session Manager over specific managed instances.

We started by showing you how to create the IAM ABAC policy to restrict access based on the AWS session tag that matches the SAML attribute used, then how to modify the required IAM role trust policy assumed by the identity provider for the federation.

We showed you how to configure Okta’s dynamic SAML attributes to modify the sign-on SAML attributes and include the information required for the AWS session tag in the user profile.

We then tested the solution by confirming that each federated user was able to start a session on the instances tagged with the right attribute. They were also able to terminate the sessions created by themselves.

About the Authors

Iago Sánchez is a Cloud Support Engineer in AWS Premium Support. He specializes in AWS Systems Manager and Amazon EC2 Windows. Outside of work, he likes to spend time with friends and family, play videogames and pretend that he knows how to play the guitar.

Rodrigo Ferroni is a senior Security Specialist at AWS Enterprise Support. He is certified in CISSP, AWS Security Specialist, and AWS Solutions Architect Associate. He enjoys helping customers to continue adopting AWS security services to improve their security posture in the cloud. Outside of work, he loves to travel as much as he can. In every winter he enjoys snowboarding with his friends.