Pass session tags in AWS STS

Session tags are key-value pair attributes that you pass when you assume an IAM role or federate a user in AWS STS. You do this by making an AWS CLI or AWS API request through AWS STS or through your identity provider (IdP). When you use AWS STS to request temporary security credentials, you generate a session. Sessions expire and have credentials, such as an access key pair and a session token. When you use the session credentials to make a subsequent request, the request context includes the aws:PrincipalTag context key. You can use the aws:PrincipalTag key in the Condition element of your policies to allow or deny access based on those tags.

When you use temporary credentials to make a request, your principal might include a set of tags. These tags come from the following sources:

Session tagging operations

You can pass session tags using the following AWS CLI or AWS API operations in AWS STS. The AWS Management Console Switch Role feature does not allow you to pass session tags.

You can also set the session tags as transitive. Transitive tags persist during role chaining. For more information, see Chaining roles with session tags.

The following table compares methods for passing session tags.

Operations that support session tagging can fail under the following conditions:

Things to know about session tags

Before you use session tags, review the following details about sessions and tags.

Permissions required to add session tags

In addition to the action that matches the API operation, you must have the following permissions-only action in your policy:

sts:TagSession

You can use the sts:TagSession action with the following condition keys.

For example, the following role trust policy allows the test-session-tags user to assume the role with the attached policy. When that user assumes the role, they must use the AWS CLI or AWS API to pass the three required session tags and the required external ID. Additionally, the user can choose to set the Project and Department tags as transitive.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowIamUserAssumeRole",
            "Effect": "Allow",
            "Action": "sts:AssumeRole",
            "Principal": {"AWS": "arn:aws:iam::123456789012:user/test-session-tags"},
            "Condition": {
              "StringLike": {
                    "aws:RequestTag/Project": "*",
                    "aws:RequestTag/CostCenter": "*",
                    "aws:RequestTag/Department": "*"
                },
                "StringEquals": {"sts:ExternalId": "Example987"}
            }
        },
        {
            "Sid": "AllowPassSessionTagsAndTransitive",
            "Effect": "Allow",
            "Action": "sts:TagSession",
            "Principal": {"AWS": "arn:aws:iam::123456789012:user/test-session-tags"},
            "Condition": {
                "StringLike": {
                    "aws:RequestTag/Project": "*",
                    "aws:RequestTag/CostCenter": "*"
                },
                "StringEquals": {
                    "aws:RequestTag/Department": [
                        "Engineering",
                        "Marketing"
                    ]
                },
                "ForAllValues:StringEquals": {
                    "sts:TransitiveTagKeys": [
                        "Project",
                        "Department"
                    ]
                }
            }
        }
    ]
}

What does this policy do?

Passing session tags using AssumeRole

The AssumeRole operation returns a set of temporary credentials you can use to access AWS resources. You can use IAM user or role credentials to call AssumeRole. To pass session tags while assuming a role, use the --tags AWS CLI option or the Tags AWS API parameter.

To set tags as transitive, use the --transitive-tag-keys AWS CLI option or the TransitiveTagKeys AWS API parameter. Transitive tags persist during role chaining. For more information, see Chaining roles with session tags.

The following example shows a sample request that uses AssumeRole. In this example, when you assume the my-role-example role, you create a session named my-session. You add the session tag key-value pairs Project = Automation, CostCenter = 12345, and Department = Engineering. You also set the Project and Department tags as transitive by specifying their keys. You must pass a single value for each session tag. AWS STS does not support multi-valued session tags.

aws sts assume-role \
--role-arn arn:aws:iam::123456789012:role/my-role-example \
--role-session-name my-session \
--tags Key=Project,Value=Automation Key=CostCenter,Value=12345 Key=Department,Value=Engineering \
--transitive-tag-keys Project Department \
--external-id Example987

Passing session tags using AssumeRoleWithSAML

The AssumeRoleWithSAML operation authenticates with SAML-based federation. This operation returns a set of temporary credentials you can use to access AWS resources. For more information about using SAML-based federation for AWS Management Console access, see Enabling SAML 2.0 federated users to access the AWS Management Console. For details about AWS CLI or AWS API access, see SAML 2.0 federation. For a tutorial on configuring SAML federation for your Active Directory users, see AWS Federated Authentication with Active Directory Federation Services (ADFS) in the AWS Security Blog.

As an administrator, you can allow members of your company directory to federate into AWS using the AWS STS AssumeRoleWithSAML operation. To do this, you must complete the following tasks:

AWS includes identity providers with certified end-to-end experience for session tags with their identity solutions. To learn how to use these identity providers to configure session tags, see Integrate third-party SAML solution providers with AWS.

To pass SAML attributes as session tags, include the Attribute element with the Name attribute set to https://aws.amazon.com/SAML/Attributes/PrincipalTag:{TagKey}. Use the AttributeValue element to specify the value of the tag. Include a separate Attribute element for each session tag.

For example, assume that you want to pass the following identity attributes as session tags:

To pass these attributes, include the following elements in your SAML assertion.

<Attribute Name="https://aws.amazon.com/SAML/Attributes/PrincipalTag:Project">
  <AttributeValue>Automation</AttributeValue>
</Attribute>
<Attribute Name="https://aws.amazon.com/SAML/Attributes/PrincipalTag:CostCenter">
  <AttributeValue>12345</AttributeValue>
</Attribute>
<Attribute Name="https://aws.amazon.com/SAML/Attributes/PrincipalTag:Department">
  <AttributeValue>Engineering</AttributeValue>
</Attribute>

To set the preceding tags as transitive, include another Attribute element with the Name attribute set to https://aws.amazon.com/SAML/Attributes/TransitiveTagKeys. Transitive tags persist during role chaining. For more information, see Chaining roles with session tags.

To set the Project and Department tags as transitive, use the following multi-valued attribute:

<Attribute Name="https://aws.amazon.com/SAML/Attributes/TransitiveTagKeys">
  <AttributeValue>Project</AttributeValue>
  <AttributeValue>Department</AttributeValue>
</Attribute>

Passing session tags using AssumeRoleWithWebIdentity

Use OpenID Connect (OIDC)-compliant federation to authenticate the AssumeRoleWithWebIdentity operation. This operation returns a set of temporary credentials you can use to access AWS resources. For more information about using web identity federation for AWS Management Console access, see OIDC federation.

To pass session tags from OpenID Connect (OIDC), you must include the session tags in the JSON Web Token (JWT) when you submit the AssumeRoleWithWebIdentity request. To learn more about OIDC tokens and claims, see Using Tokens with User Pools in the Amazon Cognito Developer Guide.

AWS supports two claim formats for including session tags in the JWT:

Nested claim format

The nested claim format uses a structure within the https://aws.amazon.com/tags namespace in the JWT. In this format:

The following example demonstrates a decoded JWT using the nested object format:

{
    "sub": "johndoe",
    "aud": "ac_oic_client",
    "jti": "ZYUCeRMQVtqHypVPWAN3VB",
    "iss": "https://xyz.com",
    "iat": 1566583294,
    "exp": 1566583354,
    "auth_time": 1566583292,
    "https://aws.amazon.com/tags": {
        "principal_tags": {
            "Project": ["Automation"],
            "CostCenter": ["987654"],
            "Department": ["Engineering"]
        },
        "transitive_tag_keys": [
            "Project",
            "CostCenter"
        ]
    }
}

Flattened claim format

The flattened claim format is compatible with identity providers that don't support nested objects in JWT claims, such as Microsoft Entra ID. In this format:

Now, let's look at how the same information is represented using the flattened claim format:

{
    "sub": "johndoe",
    "aud": "ac_oic_client",
    "jti": "ZYUCeRMQVtqHypVPWAN3VB",
    "iss": "https://xyz.com",
    "iat": 1566583294,
    "exp": 1566583354,
    "auth_time": 1566583292,
    "https://aws.amazon.com/tags/principal_tags/Project": "Automation",
    "https://aws.amazon.com/tags/principal_tags/CostCenter": "987654",
    "https://aws.amazon.com/tags/principal_tags/Department": "Engineering",
    "https://aws.amazon.com/tags/transitive_tag_keys": [
        "Project",
        "CostCenter"
    ]
}

Both decoded JWT examples show a call to AssumeRoleWithWebIdentity with the Project, CostCenter, and Department session tags. Both tokens set the Project and CostCenter tags as transitive. Transitive tags persist during role chaining. For more information, see Chaining roles with session tags.

The flattened claim format achieves the same result as the nested claim format but uses a flattened structure for tags. It allows you to include session tags in environments where nested JSON objects are not supported in JWT claims. When using either format, ensure that your identity provider is configured to issue tokens with the appropriate claim structures. AWS supports both claim formats, so you can choose the one that best fits your identity provider's specific requirements.

Passing session tags using GetFederationToken

The GetFederationToken allows you to federate your user. This operation returns a set of temporary credentials you can use to access AWS resources. To add tags to your federated user session, use the --tags AWS CLI option or the Tags AWS API parameter. You can't set session tags as transitive when you use GetFederationToken, because you can't use the temporary credentials to assume a role. You cannot use role chaining in this case.

The following example shows a sample request using GetFederationToken. In this example, when you request the token, you create a session named my-fed-user. You add the session tag key-value pairs Project = Automation and Department = Engineering.

aws sts get-federation-token \
--name my-fed-user \
--tags key=Project,value=Automation key=Department,value=Engineering

When you use the temporary credentials returned by the GetFederationToken operation, the session principal tags include the user tags and the passed session tags.

Chaining roles with session tags

You can assume one role and then use the temporary credentials to assume another role. You can continue from session to session. This is called role chaining. When you pass session tags while assuming a role, you can set the keys as transitive. This ensures that those session tags pass to subsequent sessions in a role chain. You cannot set role tags as transitive. To pass these tags to subsequent sessions, specify them as session tags.

The following example shows how AWS STS passes session tags, transitive tags, and role tags into subsequent sessions in a role chain.

In this example role chaining scenario, you use an IAM user access key in the AWS CLI to assume a role named Role1. You then use the resulting session credentials to assume a second role named Role2. You can then use the second session credentials to assume a third role named Role3. These requests occur as three separate operations. Each role is already tagged in IAM. And during each request, you pass additional session tags.

When you chain roles, you can ensure that tags from an earlier session persist to the later sessions. To do this using the assume-role CLI command, you must pass the tag as a session tag and set the tag as transitive. You pass the tag Star = 1 as a session tag. The command also attaches the tag Heart = 1 to the role and applies as a principal tag when you use the session. However, you also want the Heart = 1 tag to automatically pass to the second or third session. To do that, you manually include it as a session tag. The resulting session principal tags include both of these tags, and sets them as transitive.

You perform this request using the following AWS CLI command:

aws sts assume-role \
--role-arn arn:aws:iam::123456789012:role/Role1 \
--role-session-name Session1 \
--tags Key=Star,Value=1 Key=Heart,Value=1 \
--transitive-tag-keys Star Heart

You then use the credentials for that session to assume Role2. The command attaches the tag Sun = 2 to the second role and applies as a principal tag when you use the second session. The Heart and Star tags inherits the transitive session tags in the first session. The second session resulting principal tags are Heart = 1, Star = 1, and Sun = 2. Heart and Star continue to be transitive. The Sun tag attached to Role2 is not marked as transitive because it is not a session tag. Future sessions do not inherit this tag.

You perform this second request using the following AWS CLI command:

aws sts assume-role \
--role-arn arn:aws:iam::123456789012:role/Role2 \
--role-session-name Session2

You then use the second session credentials to assume Role3. The principal tags for the third session come from any new session tags, the inherited transitive session tags, and the role tags. The Heart = 1 and Star = 1 tags on the second session are inherited from the transitive session tag in the first session. If you try to pass the Sun = 2 session tag, the operation fails. The inherited Star = 1 session tag overrides the role Star = 3 tag. In role chaining, the value of a transitive tag overrides the role matching the ResourceTag value after the evaluation of the role trust policy. In this example, if Role3 uses Star as a ResourceTag in the role trust policy, and sets ResourceTag value to the transitive tag value from the calling role session. The role Lightning tag also applies to the third session, and not set as transitive.

You perform the third request using the following AWS CLI command:

aws sts assume-role \
--role-arn arn:aws:iam::123456789012:role/Role3 \
--role-session-name Session3

Using session tags for ABAC

Attribute-based access control (ABAC) uses an authorization strategy that defines permissions based on tag attributes.

If your company uses an OIDC or SAML-based identity provider (IdP) to manage user identities, you can configure your assertion to pass session tags to AWS. For example, with corporate user identities, when your employees federate into AWS, AWS applies their attributes to their resulting principal. You can then use ABAC to allow or deny permissions based on those attributes. For details, see IAM tutorial: Use SAML session tags for ABAC.

For more information about using IAM Identity Center with ABAC, see Attributes for access control in the AWS IAM Identity Center User Guide.

Viewing session tags in CloudTrail

You can use AWS CloudTrail to view the requests used to assume roles or federate users. The CloudTrail log file includes information about the principal tags for the assumed-role or federated user session. For more information, see Logging IAM and AWS STS API calls with AWS CloudTrail.

For example, assume that you make an AWS STS AssumeRoleWithSAML request, pass session tags, and set those tags as transitive. You can find the following information in your CloudTrail log.

    "requestParameters": {
        "sAMLAssertionID": "_c0046cEXAMPLEb9d4b8eEXAMPLE2619aEXAMPLE",
        "roleSessionName": "MyRoleSessionName",
        "principalTags": {
            "CostCenter": "987654",
            "Project": "Unicorn"
        },
        "transitiveTagKeys": [
            "CostCenter",
            "Project"
        ],
        "durationSeconds": 3600,
        "roleArn": "arn:aws:iam::123456789012:role/SAMLTestRoleShibboleth",
        "principalArn": "arn:aws:iam::123456789012:saml-provider/Shibboleth"
    },

You can view the following example CloudTrail logs to view events that use session tags.