在 Amazon STS 中传递会话标签
会话标签是您在代入 IAM 角色或联合 Amazon STS 用户身份时传递的键/值对属性。您可以通过 Amazon STS 或您的身份提供程序 (IdP) 发出 Amazon CLI 或 Amazon API 请求来完成此操作。当您使用 Amazon STS 请求临时安全凭证时,会生成会话。会话过期并具有凭证,例如访问密钥对和会话令牌。当您使用会话凭证发出后续请求时,请求上下文包含 aws:PrincipalTag
上下文密钥。您可以使用策略的 Condition
元素中的 aws:PrincipalTag
键,基于这些标签来允许或拒绝访问。
当您使用临时凭证发出请求时,您的主体可能会包含一组标签。这些标签来自以下来源:
-
会话标签 - 这些标签在您使用 Amazon CLI 或 Amazon API 代入角色或联合身份用户身份时传递。有关这些操作的更多信息,请参阅 会话标记操作。
-
传入的可传递会话标签 - 这些标签继承自角色链中的上一个会话。有关更多信息,请参阅本主题后面的 使用会话标签链接角色。
-
IAM 标签 — 附加到您的 IAM 所担任角色的标签。
主题
会话标记操作
您可以在 Amazon STS 中使用以下 Amazon CLI 或 Amazon API 操作来传递会话标签。Amazon Web Services Management Console 切换角色 功能不支持传递会话标签。
您还可以将会话标签设置为可传递。在角色链的串联过程中,可传递标签持续存在。有关更多信息,请参阅使用会话标签链接角色。
传递会话标签的方法对比 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
运算 | 谁可以担任角色 | 传递标签的方法 | 设置可传递标签的方法 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
assume-role CLI 或 AssumeRole API 操作 |
IAM 用户或会话 | Tags API 参数或 --tags CLI 选项 |
TransitiveTagKeys API 参数或 --transitive-tag-keys CLI 选项 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
assume-role-with-saml CLI 或 AssumeRoleWithSAML API 操作 |
使用 SAML 身份提供程序验证身份的任何用户 | PrincipalTag SAML 属性 |
TransitiveTagKeys SAML 属性 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
assume-role-with-web-identity CLI 或 AssumeRoleWithWebIdentity API 操作 |
使用 Web 身份提供程序验证的任何用户 | PrincipalTag Web 身份令牌 |
TransitiveTagKeys Web 身份令牌 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
get-federation-token CLI 或 GetFederationToken API 操作 |
IAM 用户或根用户 | Tags API 参数或 --tags CLI 选项 |
不支持 |
如果满足以下条件,则支持会话标记的操作会失败:
-
您传递的会话标签数超过 50。
-
会话标签键的纯文本超过 128 个字符。
-
会话标签值的纯文本超过 256 个字符。
-
会话策略纯文本的总大小超过 2048 个字符。
-
会话策略和会话标签的组合包总大小太大。如果操作失败,则错误消息以百分比形式指示策略和标签的组合接近大小上限的程度。
关于会话标签的需知信息
在您使用会话标签之前,请查看以下有关会话和标签的详细信息。
-
使用会话标签时,连接到传递标签的身份提供程序 (IdP) 的所有角色的信任策略都必须具有 sts:TagSession 权限。对于信任策略中没有此权限的角色,
AssumeRole
操作会失败。 -
请求会话时,可以将主体标记指定为会话标记。标签适用于您使用会话凭证发出的请求。
-
会话标签使用键/值对。例如,要向会话添加联系信息,您可以添加会话标签键
email
和标签值johndoe@example.com
。 -
会话标签必须遵循在 IAM 和 Amazon STS 中命名标签的规则。本主题包括有关适用于会话标签的区分大小写和受限制前缀的信息。
-
新的会话标签覆盖具有相同标签键的现有已代入角色或联合身份用户身份标签,无论大小写如何。
-
您无法使用 Amazon Web Services Management Console传递会话标签。
-
会话标签仅对当前会话有效。
-
会话标签支持角色链。默认情况下,Amazon STS 不传递到后续角色会话。不过,您可以将会话标签设置为可传递。在角色链期间,可传递标签持续存在,在角色信任策略评估期间,将替换匹配
ResourceTag
的值。有关更多信息,请参阅使用会话标签链接角色。 -
您可以使用会话标签来控制对资源的访问,或者控制哪些标签可以传递到后续会话。有关更多信息,请参阅IAM 教程:将 SAML 会话标签用于 ABAC。
-
您可以在 Amazon CloudTrail 日志中查看会话的主体标签,包括其会话标签。有关更多信息,请参阅在 CloudTrail 中查看会话标签。
-
您必须为每个会话标签传递一个值。Amazon STS 不支持多值会话标签。
-
您最多可以传递 50 个会话标签。Amazon 账户中 IAM 资源的数量和大小是有限的。有关更多信息,请参阅IAM 和 Amazon STS 配额。
-
Amazon 转换会将传递的会话策略和会话标签合并压缩为具有单独限制的打包二进制格式。如果超过此限制,Amazon CLI 或 Amazon API 错误消息以百分比形式指示策略和标签的组合接近大小上限的程度。
添加会话标签所需的权限
除了与 API 操作匹配的操作之外,您的策略中还必须具有以下仅限授权执行的操作:
sts:TagSession
重要
使用会话标签时,连接到身份提供程序 (IdP) 的所有角色的角色信任策略都必须具有 sts:TagSession
权限。对于连接到 IdP 的任何角色,如果在没有此权限的情况下传递会话标签,AssumeRole
操作将失败。如果您不想更新每个角色的角色信任策略,则可以使用单独的 IdP 实例传递会话标签。然后仅将 sts:TagSession
权限添加到连接至单独 IdP 的角色。
您可以将 sts:TagSession
操作与以下条件键搭配使用。
-
aws:PrincipalTag
– 使用此键可将附加到发出请求的主体的标签与您在策略中指定的标签进行比较。例如,您可以仅在发出请求的主体具有指定的标签时,才允许主体传递会话标签。 -
aws:RequestTag
– 使用此键可将请求中传递的标签键/值对与您在策略中指定的标签对进行比较。例如,您可以允许主体传递指定的会话标签,但只能使用指定的值。 -
aws:ResourceTag
- 使用此键可将您在策略中指定的标签键/值对与附加到资源的键/值对进行比较。例如,您可以仅在当主体代入的角色包含指定标签时,才允许主体传递会话标签。 -
aws:TagKeys
– 将请求中的标签键与您在策略中指定的键进行比较。例如,您可以只允许主体传递具有指定标签键的会话标签。此条件键限制可传递的最大一组会话标签。 -
sts:TransitiveTagKeys
- 将请求中的可传递会话标签键与在策略中指定的键进行比较。例如,您可以编写一个策略,仅允许主体将特定标签设置为可传递标签。在角色链的串联过程中,可传递标签持续存在。有关更多信息,请参阅使用会话标签链接角色。
例如,以下角色信任策略允许 test-session-tags
用户代入策略附加到的角色。用户在代入该角色时,必须使用 Amazon CLI 或 Amazon API 传递三个所需的会话标签和所需的外部 ID。此外,用户可以选择将 Project
和 Department
标签设置为可传递。
例 会话标签的角色信任策略示例
{ "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
" ] } } } ] }
此策略有何作用?
-
AllowIamUserAssumeRole
语句允许test-session-tags
用户代入策略所附加到的角色。用户在代入该角色时,必须传递所需的会话标签和外部 ID。-
此语句的第一个条件块要求用户传递
Project
、CostCenter
和Department
会话标签。标签值在此语句中无关紧要,因此我们为标签值使用通配符 (*)。此块确保用户至少传递这三个会话标签。否则,该操作将失败。用户可以传递其他标签。 -
第二个条件块要求用户传递值为
Example987
的外部 ID。
-
-
该
AllowPassSessionTagsAndTransitive
语句允许sts:TagSession
仅限授权执行的操作。必须允许此操作,然后用户才能传递会话标签。如果您的策略包含第一个语句而没有第二个语句,则用户无法代入角色。-
此语句的第一个条件块允许用户为
CostCenter
和Project
会话标签传递任何值。您可以通过在策略中为标签值使用通配符 (*) 来执行此操作,这需要使用 StringLike 条件运算符。 -
第二个条件块仅允许用户为
Department
会话标签传递Engineering
或Marketing
值。 -
第三个条件块列出可以设置为可传递的最大一组标签。用户可以选择将一部分标签设置为可传递,也可以不将任何标签设置为可传递。他们不能将其他标签设置为可传递。您可以通过添加包含
"Null":{"sts:TransitiveTagKeys":"false"}
的其他条件块,将至少一个标签设置为可传递。
-
使用 AssumeRole 传递会话标签
AssumeRole
操作返回一组可用于访问 Amazon 资源的临时凭证。您可以使用 IAM 用户或角色凭证来调用 AssumeRole
。要在代入角色时传递会话标签,请使用 --tags
Amazon CLI 选项或 Tags
Amazon API 参数。
要将标签设置为可传递,请使用 --transitive-tag-keys
Amazon CLI 选项或 TransitiveTagKeys
Amazon API 参数。在角色链的串联过程中,可传递标签持续存在。有关更多信息,请参阅使用会话标签链接角色。
以下示例显示使用 AssumeRole
的示例请求。在此示例中,在代入 my-role-example
角色时,您将创建一个名为 my-session
的会话。添加会话标签键/值对 Project
= Automation
、CostCenter
= 12345
和 Department
= Engineering
。您还可以通过指定 Project
和 Department
标签的键,将其设置为可传递标签。
例 示例 AssumeRole CLI 请求
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
使用 AssumeRoleWithSAML 传递会话标签
AssumeRoleWithSAML
操作使用基于 SAML 的联合身份进行身份验证。此操作返回一组可用于访问 Amazon 资源的临时凭证。有关将基于 SAML 的联合身份用于 Amazon Web Services Management Console访问的更多信息,请参阅使 SAML 2.0 联合身份用户能够访问 Amazon Web Services Management Console。有关 Amazon CLI 或 Amazon API 访问的详细信息,请参阅关于基于 SAML 2.0 的联合身份验证。有关为 Active Directory 用户设置 SAML 联合身份的教程,请参阅 Amazon 安全博客 中的使用 Active Directory 联合身份验证服务 (ADFS)
作为管理员,您可以使用 Amazon STS AssumeRoleWithSAML
操作,允许公司目录的成员联合身份到 Amazon 中。要执行此操作,您必须完成以下任务:
Amazon 包括身份提供程序,通过其身份解决方案提供经认证的端到端会话标签体验。要了解如何使用这些身份提供程序配置会话标签,请参阅将第三方 SAML 解决方案提供商与 Amazon 集成。
要将 SAML 属性作为会话标签传递,请包含 Attribute
元素并将 Name
属性设置为 https://aws.amazon.com/SAML/Attributes/PrincipalTag:
。使用 {TagKey}
AttributeValue
元素指定标签的值。为每个会话标签包含一个单独的 Attribute
元素。
例如,假设您要将以下身份属性作为会话标记传递:
-
Project:Automation
-
CostCenter:12345
-
Department:Engineering
要传递这些属性,请在 SAML 断言中包含以下元素。
例 SAML 断言的示例片段
<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>
要将上述标签设置为可传递,请包含另一个 Attribute
元素并将 Name
属性设置为 https://aws.amazon.com/SAML/Attributes/TransitiveTagKeys
。在角色链的串联过程中,可传递标签持续存在。有关更多信息,请参阅使用会话标签链接角色。
要将 Project
和 Department
标签设置为可传递,请使用以下多值属性。
例 SAML 断言的示例片段
<Attribute Name="https://aws.amazon.com/SAML/Attributes/TransitiveTagKeys"> <AttributeValue>Project</AttributeValue> <AttributeValue>Department</AttributeValue> </Attribute>
使用 AssumeRoleWithWebIdentity 传递会话标签
使用 OpenID Connect (OIDC) 的 Web 联合身份进行 AssumeRoleWithWebIdentity
操作的身份验证。此操作返回一组可用于访问 Amazon 资源的临时凭证。有关将基于 Web 联合身份用于 Amazon Web Services Management Console访问的更多信息,请参阅关于 Web 联合身份验证。
要从 OpenID Connect (OIDC) 传递会话标签,您必须在 JSON Web 令牌 (JWT) 中包含会话标签。当您提交 AssumeRoleWithWebIdentity
请求时,请在令牌的 http://www.amazonaws.cn/
命名空间中包含会话标签。要了解有关 OIDC 令牌和声明的更多信息,请参阅《Amazon Cognito 开发人员指南》中的将令牌与用户群体结合使用。
例如,以下解码的 JWT 是一个令牌,用于通过 Project
、CostCenter
和 Department
会话标签调用 AssumeRoleWithWebIdentity
。该令牌还将 Project
和 CostCenter
标签设置为可传递。在角色链的串联过程中,可传递标签持续存在。有关更多信息,请参阅使用会话标签链接角色。
例 解码的 JSON Web 令牌示例
{ "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" ] } }
使用 GetFederationToken 传递会话标签
GetFederationToken
允许您对用户进行联合身份验证。此操作返回一组可用于访问 Amazon 资源的临时凭证。要将标签添加到联合身份用户会话,请使用 --tags
Amazon CLI 选项或 Tags
Amazon API 参数。在使用 GetFederationToken
时,您不能将会话标签设置为可传递,因为您无法使用临时凭证担任角色。在这种情况下,您不能使用角色链。
下面的示例演示使用 GetFederationToken
的示例请求。在此示例中,在请求令牌时,您创建一个名为 my-fed-user
的会话。添加会话标签键/值对 Project
= Automation
和 Department
= Engineering
。
例 GetFederationToken CLI 请求示例
aws sts get-federation-token \ --name my-fed-user \ --tags key=Project,value=Automation key=Department,value=Engineering
当您使用 GetFederationToken
操作返回的临时凭证时,会话的主体标签包括用户的标签以及传递的会话标签。
使用会话标签链接角色
您可以代入一个角色,然后使用临时凭证代入另一个角色。您可以从一个会话继续到另一个会话来使用角色。这就是所说的角色链。当您在代入某个角色的同时传递会话标签,您可以将键设置为可传递。这可确保将这些会话标签传递到角色链中的后续会话。您无法将角色标签设置为可传递。要将这些标签传递给后续会话,请将其指定为会话标签。
以下示例帮助您了解 Amazon STS 如何在角色链中,将会话标签、可传递标签和角色标签传递到后续会话。
在以下示例角色链场景中,您在 Amazon CLI 中使用 IAM 用户的访问密钥代入名为 Role1
的角色。然后,您可以使用生成的会话凭证代入名为 Role2
的第二个角色。接下来,您可以使用第二个会话凭证代入名为 Role3
的第三个角色。这些请求作为三个单独的操作发生。每个角色均已在 IAM 中标记。在每个请求过程中,您都会传递额外的会话标签。

链接角色时,您可以确保来自较早会话的标签保留到后续会话。要使用 assume-role
CLI 命令执行此操作,您必须将标签作为会话标签传递,并将标签设置为可传递。您传递标签 Star
= 1
作为会话标签。此命令还将标签 Heart
= 1
附加到角色,并在您使用会话时作为主体标签应用。但是,您还希望自动将 Heart
= 1
标签传递给第二个或第三个会话。为此,您可以手动将其包含为会话标签。生成的会话主体标记包括这两个标记,并将它们设置为可传递。

您可以使用以下 Amazon CLI 命令执行此请求:
例 示例 AssumeRole CLI 请求
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
然后,您可以使用该会话的凭证代入 Role2
。此命令将标签 Sun
= 2
附加到第二个角色,并在您使用第二个会话时作为主体标签应用。Heart
和 Star
标签继承第一个会话中的可传递会话标签。第二个会话产生的主体标签为 Heart
= 1
、Star
= 1
和 Sun
= 2
。Heart
和 Star
将继续为可传递标签。附加到 Role2
的 Sun
标签不会标记为可传递,因为它不是会话标签。以后的会话不继承此标签。

您可以使用以下 Amazon CLI 命令执行第二个请求:
例 示例 AssumeRole CLI 请求
aws sts assume-role \ --role-arn arn:aws:iam::123456789012:role/Role2 \ --role-session-name Session2
然后,您使用第二个会话凭证来代入 Role3
。第三个会话的主体标签来自任意新的会话标签、继承的可传递会话标签和角色标签。第二个会话上的 Heart
= 1
和 Star
= 1
标签继承自第一个会话中的可传递会话标签。如果您尝试传递 Sun
= 2
会话标记,操作会失败。继承的 Star
= 1 会话标签覆盖角色的 Star
= 3
标签。在角色链中,可传递标记的值将覆盖与 ResourceTag
值匹配的角色,然后再评估角色信任策略。在此示例中,如果 Role3
在角色信任策略中将 Star
用作 ResourceTag
,并将 ResourceTag
值设置为调用角色会话的可传递标签值。角色的 Lightning
标签也应用到第三个会话,并且不设置为可传递。

您使用以下 Amazon CLI 命令执行第三个请求:
例 示例 AssumeRole CLI 请求
aws sts assume-role \ --role-arn arn:aws:iam::123456789012:role/Role3 \ --role-session-name Session3
将会话标签用于 ABAC
基于属性的访问控制 (ABAC) 是一种授权策略,该策略基于标签属性来定义权限。
如果您的公司使用 OIDC 基于 SAML 的身份提供程序 (IdP) 管理用户实体,则可以配置 SAML 断言,将会话标记传递给 Amazon。例如,对于公司用户身份,当您的员工联合到 Amazon,Amazon 会将其属性应用于其生成的主体。然后,您可以使用 ABAC 来允许或拒绝基于这些属性的权限。有关详细信息,请参阅 IAM 教程:将 SAML 会话标签用于 ABAC。
有关将 IAM Identity Center 与 ABAC 配合使用的更多信息,请参阅《Amazon IAM Identity Center 用户指南》中的访问控制的属性。
在 CloudTrail 中查看会话标签
您可以使用 Amazon CloudTrail 查看为代入角色或联合身份用户而发出的请求。CloudTrail 日志文件包括有关所代入角色或联合身份用户会话的主体标签的信息。有关更多信息,请参阅使用 Amazon CloudTrail 记录 IAM 和 Amazon STS API 调用。
例如,假定您发出 Amazon STS AssumeRoleWithSAML
请求,传递会话标签,然后将这些标签设置为可传递标签。您可以在 CloudTrail 日志中找到以下信息。
例 AssumeRoleWithSAML CloudTrail 日志示例
"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" },
您可以查看以下示例 CloudTrail 日志以查看使用会话标签的事件。