传递会话标签

会话标签

目前您只能在STS的AssumeAgency API、AssumeAgencyWithSAML API和AssumeAgencyWithOIDC API传递会话标签，在IAM控制台切换信任委托时不支持传递会话标签。

您还可以通过设置transitive_tag_keys将会话标签设置为可传递（transitive）。同样，根据您所调用的华为云安全令牌服务（STS）API的不同，其传递方式也有所不同：在调用AssumeAgency API时，会话标签通过切换IAM信任委托时的transitive_tag_keys参数进行传递；在调用AssumeAgencyWithSAML API时，会话标签通过SAML断言中指定的属性进行传递；在调用AssumeAgencyWithOIDC API时，会话标签通过OIDC令牌中的指定字段进行传递。具体传递方式参见后续段落。

在transitive_tag_keys中指定的会话标签将在委托链中持续存在。详细信息可以参考获取临时安全凭证，如果满足以下条件，则传递会话标签的STS API调用会失败：

• 您传递的会话标签tags数量超过20个。
• 会话标签tags中键的纯文本超过128个字符。
• 会话标签tags中值的纯文本超过255个字符。
• 传递会话标签transitive_tag_keys数量超过20个。

会话标签注意事项

使用会话标签所需要的权限

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"
			]
		}
	}]
}

使用AssumeAgency API传递会话标签

AssumeAgency API会返回一组临时安全凭证，您可以使用这些凭证来访问华为云资源。你可以使用IAM用户或委托凭证来调用 AssumeAgencyAPI。若要在切换委托时传递会话标签，请指定AssumeAgencyAPI 请求体中的tags参数。若要将标签设置为可传递（transitive），请指定AssumeAgencyAPI 请求体中的transitive_tag_keys参数，可传递标签会在委托链中持续保留。

使用AssumeAgencyWithSAML API传递会话标签

使用AssumeAgencyWithOIDC API传递会话标签

AssumeAgencyWithOIDC API通过OIDC协议进行身份验证，该操作会返回一组临时凭证，可用于访问华为云资源。若要从OIDC传递会话标签，您必须在提交请求时，将标签包含在OIDC令牌中。华为云在OIDC令牌的认证中支持两种会话标签的声明格式：嵌套式声明格式和扁平化声明格式。扁平化声明格式虽然在结构上与嵌套声明格式不同，但其实现的功能完全一致。它的存在主要是为了兼容那些不支持在OIDC令牌声明中嵌套JSON对象的身份提供商，例如Microsoft Entra ID。扁平化声明格式与嵌套声明格式不可同时使用。

• 嵌套声明格式 (Nested Claim Format)
  这种格式在OIDC令牌中使用 https://www.huaweicloud.com/tags 声明下的结构化对象组成。

  • 主体标签：使用principal_tags键下的嵌套对象表示。
  • 可传递的标签键列表：使用transitive_tag_keys键下的数组表示。
  • 两者都嵌套在华为云命名空间下。

  {
      "sub": "johndoe",
      "iss": "https://xyz.com",
      "https://www.huaweicloud.com/tags": {
          "principal_tags": {
              "Project": "Automation",
              "CostCenter": "987654",
              "Department": "Engineering"
          },
          "transitive_tag_keys": [
              "Project",
              "CostCenter"
          ]
      }
  }

• 扁平化声明格式
  此格式适用于不支持在OIDC令牌声明中使用嵌套对象的身份提供商（例如 Microsoft Entra ID）。

  • 主体标签：使用带有前缀 https://www.huaweicloud.com/tags/principal_tags/ 的独立声明表示。
  • 可传递的标签键列表：使用带有前缀 https://www.huaweicloud.com/tags/transitive_tag_keys 的单个声明表示，其值为字符串数组。

  {
      "sub": "johndoe",
      "iss": "https://xyz.com",
      "https://www.huaweicloud.com/tags/principal_tags/Project": "Automation",
      "https://www.huaweicloud.com/tags/principal_tags/CostCenter": "987654",
      "https://www.huaweicloud.com/tags/principal_tags/Department": "Engineering",
      "https://www.huaweicloud.com/tags/transitive_tag_keys": [
          "Project",
          "CostCenter"
      ]
  }

委托链中的会话标签

您可以先切换到一个信任委托，然后使用获取的临时凭证切换到另外一个信任委托，这一过程称为委托链（Agency Chaining）。在您设置会话标签时，您可以将标签键设置为可传递，以确保这些会话标签能传递至委托链中的后续会话。请注意：信任委托身上的标签无法设为可传递，若要将这些标签传递至后续会话，必须将其明确指定为会话标签。

以下示例演示了STS如何在委托链中将会话标签、委托标签传递至后续会话。在此委托链场景中，您通过AssumeAgency API使用IAM用户访问密钥切换到TrustAgency1的信任委托，随后利用生成的会话临时安全凭证切换到第二个信任委托TrustAgency2，最后使用第二次会话的临时安全凭证切换到第三个信任委托TrustAgency3。这些请求作为三个独立操作执行，且每个信任委托已预先在IAM中打上了标签，每次请求时您可以使用AssumeAgency API中的tags和transitive_tag_keys参数确保会话标签从早期会话传递到后续会话。

假设切换TrustAgency1时在AssumeAgency API中设置了会话标签Team=1，且将Team设置为了可传递。此时，在TrustAgency1身上打了标签EmployeeID=1，如果您想要将委托标签EmployeeID=1也传递至后续会话，那么您必须手动在AssumeAgency API中也将其作为会话标签并设置为可传递。最后，生成的会话主体（Session Principal）中将同时包含Team=1和EmployeeID=1这两个标签，这样您便可以使用g:PrincipalTag/Team、g:PrincipalTag/EmployeeID条件键进行访问控制。

现在您使用会话1的临时安全凭证去切换TrustAgency2，Team=1和EmployeeID=1将从会话1继承到会话2。此时，在TrustAgency2身上打了标签JobRole=2，但是您没有将其作为会话标签并设置为可传递。最后，虽然生成的会话主体中将同时包含Team=1、EmployeeID=1和JobRole=2这三个标签，但是JobRole=2将不会往后续的会话中进行传递，只在本次会话2中有效。

最后您使用会话2的临时安全凭证去切换TrustAgency3，Team=1和EmployeeID=1将从会话2继续继承到会话3。实际上，会话3的主体标签（Principal Tag）将由新增的会话标签、新增的可传递标签、信任委托本身的委托标签构成。此时，在TrustAgency3身上打了标签Team=3，继承的标签Team=1和信任委托本身的标签Team=3在标签键上是相同的，由于继承的标签优先级要高于信任委托本身的标签，因此Team=1将覆盖Team=3。最后，生成的会话主体中将同时包含Team=1、EmployeeID=1这两个标签。

将会话标签用于访问控制

{
	"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"
	}]
}