Passing Session Tags

Session Tagging

Things to Know About Session Tags

Permissions Required for Using Session Tags

sts::tagSession

{
	"Version": "5.0",
	"Statement": [{
		"Effect": "Allow",
		"Action": [
			"sts:agencies:assume",
			"sts::tagSession"
		]
	}]
}

{
	"Version": "5.0",
	"Statement": [{
		"Action": [
			"sts:agencies:assume",
			"sts::tagSession"
		],
		"Effect": "Allow",
		"Principal": {
			"IAM": [
				"Account A ID"
			]
		}
	}]
}

Now, IAM user A can pass session tags when calling the AssumeAgency API. For details, see tags in Obtaining Temporary Security Credentials Through an Agency or Trust Agency.

Chaining roles with session tags

You can assume a trust agency, and then use the obtained temporary security credentials to assume another trust agency. This process is called agency chaining. You can set session tag keys as transitive to pass these session tags to subsequent sessions in the agency chain. Trust agency tags cannot be set as transitive. To pass these tags, you must explicitly specify them as session tags.

The following example shows how STS passes session tags and agency tags to subsequent sessions in an agency chain. In this example agency chaining scenario, you use the AssumeAgency API and the access key of an IAM user to assume TrustAgency1. Then, you use the temporary security credentials generated from the first session to switch to TrustAgency2. Finally, you use the second temporary security credentials to switch to TrustAgency3. These requests occur as three separate operations. Each agency is already tagged in IAM. You can use the tags and the transitive_tag_keys parameter in the AssumeAgency API to ensure that tags from an earlier session persist to the later sessions.

For example, you set the session tag "Team=1" as transitive and tag TrustAgency1 with "EmployeeID=1" when you call the AssumeAgency API to assume TrustAgency1. To keep the trust agency tag "EmployeeID=1" persist in the agent chain, you must pass it as a session tag and set it as transitive. The session principal will then contain both "Team=1" and "EmployeeID=1" tags, allowing you to use the g:PrincipalTag/Team and g:PrincipalTag/EmployeeID condition keys for access control.

Now, use the temporary security credentials of session 1 to assume TrustAgency2. The "Team=1" and "EmployeeID=1" tags are inherited from session 1 to session 2. The tag "JobRole=2" is added to TrustAgency2, but you do not add it as a session tag or set it as transitive. As a result, although the session principal has the "Team=1", "EmployeeID=1", and "JobRole=2" tags, the "JobRole=2" tag does not persist to the subsequent session and is valid only in session 2.

Now, use the temporary security credentials of session 2 to assume TrustAgency3. The "Team=1" and "EmployeeID=1" tags are inherited from session 2 to session 3. The principal tags of session 3 consist of the new session tag, new transitive tag, and trust agency tag. The tag "Team=3" is added to TrustAgency3. The inherited tag "Team=1" and the trust agency tag "Team=3" have the same tag key. As the inherited tag takes precedence over the trust agency tag, "Team=1" overwrites "Team=3". As a result, the generated session principal contains both "Team=1" and "EmployeeID=1".

Using Session Tags for Access Control

{
	"Version": "5.0",
	"Statement": [{
		"Effect": "Allow",
		"Action": [
			"iam:*:*"
		],
		"Condition": {
			"StringEquals": {
				"g:PrincipalTag/Team": [
					"1"
				]
			}
		}
	}]
}

{
	"agency_urn": "iam::account_id:agency:agency_name",
	"agency_session_name": "session_name",
	"tags": [{
		"key": "Team",
		"value": "1"
	}]
}