# 为身份验证响应配置SAML断言
在验证组织用户身份后，外部身份提供商会向华为云登录端点发送身份验证响应，该响应通过HTTP POST方式传输并遵循SAML 2.0的HTTP POST绑定规范，其中包含一个SAML断言（Assertion）。该断言由外部身份提供商生成，包含用户相关的属性（Attributes）及身份标识信息（如Subject和NameID），这些内容需要在外部身份提供商中进行配置，具体方式取决于所使用的外部身份提供商。当华为云接收到该断言后，会将其中部分属性映射为条件键，您可以在IAM身份策略的Condition中使用这些条件键，以实现基于属性的精细化访问控制。
#### Subject和NameID
身份验证响应必须且仅包含一个SubjectConfirmation元素，该元素中必须包含SubjectConfirmationData子元素，并同时包含NotOnOrAfter和Recipient属性。其中，Recipient属性的值必须与华为云登录端点URL完全匹配。不同的外部身份提供商实现不同，可能使用Recipient、ACS或Target等术语来表示该属性。IAM提供了两个登录URL，分别是：
- https://auth.huaweicloud.com/authui/v5/saml
- https://auth.huaweicloud.com/authui/v5/saml/acs/{provider_id}
 
如果启用了SAML加密，则登录URL必须包含华为云为该SAML身份提供商分配的ID，该标识符可在身份提供商的详情页面中获取。
NameID 元素通过 Format 属性指定其标识类型，单点登录（SSO）交互支持以下类型的标识符：
- urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
- urn:oasis:names:tc:SAML:2.0:nameid-format:transient
- urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
- urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
- urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName
- urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName
- urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos
- urn:oasis:names:tc:SAML:2.0:nameid-format:entity
 
Format属性的典型示例是 persistent（持久）、transient（临时）或由身份提供商自定义的完整URL，IAM会将其映射为saml:sub_type条件键的值。
在实际的策略评估中，IAM会对saml:sub_type条件键进行处理：
- 如果该Format属性包含前缀urn:oasis:names:tc:SAML:2.0:nameid-format，那么IAM会将该前缀移除后作为saml:sub_type条件键的值。例如，对于urn:oasis:names:tc:SAML:2.0:nameid-format:transient，saml:sub_type条件键的值为transient。
- 如果该Format属性包含任何其他前缀，那么IAM会直接使用完整的Format属性值作为saml:sub_type条件键的值。
 
其中，persistent表示在所有会话中保持不变的稳定标识；transient表示仅在当前会话中有效的临时标识，每次认证都会生成新的值。
示例：
```
<Subject>
  <NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">_dead322d4643f41430fe25e3</NameID>
  <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
    <SubjectConfirmationData NotOnOrAfter="2013-11-05T02:06:42.876Z" Recipient="https://auth.huaweicloud.com/authui/v5/saml"/>
  </SubjectConfirmation>
</Subject>
```
![](https://support.huaweicloud.com/usermanual-iam5/public_sys-resources/note_3.0-zh-cn.png)
saml:aud条件键来自SAML recipient属性，它等价于OIDC令牌中的受众字段。
#### PrincipalTag SAML属性
（可选）您可使用将Name属性设置为https://www.huaweicloud.com/SAML/Attributes/PrincipalTag:{TagKey}的Attribute元素。此元素允许您将属性作为SAML断言中的会话标签传递。有关会话标签的更多信息，请参见[传递会话标签](https://support.huaweicloud.com/usermanual-iam5/iam_01_1264.html)。
要将属性作为会话标签传递，请包含指定标签值的AttributeValue 元素。例如，要传递标签键/值对Position=ProductManager和EmployeeID=0711，请使用以下属性。为每个标签包含一个单独的Attribute元素。
```
<Attribute Name="https://www.huaweicloud.com/SAML/Attributes/PrincipalTag:Position">
  <AttributeValue>ProductManager</AttributeValue>
</Attribute>
<Attribute Name="https://www.huaweicloud.com/SAML/Attributes/PrincipalTag:EmployeeID">
  <AttributeValue>0711</AttributeValue>
</Attribute>
```
要将上述标签设置为可传递，请包含另一个Attribute元素并将Name属性设置为https://www.huaweicloud.com/SAML/Attributes/TransitiveTagKeys。这是一个可选的多值属性，可将您的会话标签设置为可传递。当您使用SAML会话切换华为云中的另一个委托时，可传递标签将保留。例如，要将Position和EmployeeID标签均设置为可传递，请使用以下属性指定键。
```
<Attribute Name="https://www.huaweicloud.com/SAML/Attributes/TransitiveTagKeys">
  <AttributeValue>Position</AttributeValue>
  <AttributeValue>EmployeeID</AttributeValue>
</Attribute>
```
#### Agency SAML属性
您可以在SAML断言中使用一个Attribute元素，其Name属性设置为https://www.huaweicloud.com/SAML/Attributes/Agency。该元素包含一个或多个AttributeValue子元素，用于指定用户通过外部身份提供商映射到的IAM信任委托与SAML身份提供商组合。每个组合由一对URN构成，分别表示IAM信任委托URN和SAML身份提供商URN，并以逗号分隔，格式与调用AssumeAgencyWithSAML API时使用的agency_urn和provider_urn参数一致。该Attribute至少必须包含一个信任委托与SAML身份提供商的映射对，也可以包含多个映射对；如果包含多个对，则用户在通过外部身份提供商的门户登录华为云管理控制台时，需要从中选择一个信任委托进行会话切换。
![](https://support.huaweicloud.com/usermanual-iam5/public_sys-resources/note_3.0-zh-cn.png)
Name标签中Attribute属性的值区分大小写。必须将其一字不差地设置为https://www.huaweicloud.com/SAML/Attributes/Agency。
```
<Attribute Name="https://www.huaweicloud.com/SAML/Attributes/Agency">
    <AttributeValue>iam: :account-id:agency:agency-name1,iam: :account-id:samlProvider:provider-name</AttributeValue>
    <AttributeValue>iam: :account-id:agency:agency-name2,iam: :account-id:samlProvider:provider-name</AttributeValue>
    <AttributeValue>iam: :account-id:agency:agency-name3,iam: :account-id:samlProvider:provider-name</AttributeValue>
</Attribute>
```
#### AgencySessionName SAML属性
您可以在SAML断言中使用一个Attribute元素，其Name属性设置为https://www.huaweicloud.com/SAML/Attributes/AgencySessionName。该元素包含一个AttributeValue，用于为通过单点登录（SSO）获取的临时安全凭证提供委托会话标识符，从而将这些凭证与外部身份提供商的用户关联，并在华为云管理控制台中显示用户身份信息。该AttributeValue的长度必须为2到64个字符，仅允许使用字母、数字、下划线以及以下特殊字符：. , + = @ -（连字符），且不能包含空格。该值通常设置为用户ID（如john）或电子邮件地址（如johndoe@example.com），但不应使用包含空格的显示名称（如John Doe）。
```
<Attribute Name="https://www.huaweicloud.com/SAML/Attributes/AgencySessionName">
  <AttributeValue>user-id-name</AttributeValue>
</Attribute>
```
#### SessionDuration SAML属性
您可以在SAML断言中使用一个Attribute元素，其Name属性设置为https://www.huaweicloud.com/SAML/Attributes/SessionDuration。该元素包含一个AttributeValue，用于指定用户在必须重新获取临时安全凭证之前可访问华为云管理控制台的会话时长，该值为以秒为单位的整数，范围为900秒（15分钟）到43200秒（12小时）。如果未提供该属性，则默认会话时长为1小时，对应AssumeAgencyWithSAML API的默认duration_seconds参数值。
要使用该属性，必须配置SAML提供商以支持通过控制台登录Web终端节点（https://auth.huaweicloud.com/authui/v5/saml或 https://auth.huaweicloud.com/authui/v5/saml/acs/{provider_id}）实现单点登录。
此外，如果同时配置SessionNotOnOrAfter属性，则控制台会话的最大持续时间取SessionDuration与SessionNotOnOrAfter中较小的值。
![](https://support.huaweicloud.com/usermanual-iam5/public_sys-resources/warning_3.0-zh-cn.png)
延长控制台会话时间可能增加凭证泄露风险，请谨慎操作。
```
<Attribute Name="https://www.huaweicloud.com/SAML/Attributes/SessionDuration">
  <AttributeValue>1800</AttributeValue>
</Attribute>
```
#### SourceIdentity SAML属性
您可以在SAML断言中使用一个Attribute元素，其Name属性设置为https://www.huaweicloud.com/SAML/Attributes/SourceIdentity。该元素包含一个AttributeValue，用于标识使用IAM信任委托的实体。当用户通过SAML会话在华为云中切换其他委托时，该SourceIdentity值会在委托链过程中持续传递，并在整个会话期间保持不变，无法在会话中途修改。该值会随每一次基于该委托会话发起的API请求一同记录，便于后续审计。管理员可以通过华为云CTS日志追踪SourceIdentity，从而识别使用同一信任委托执行操作的具体实体。
AttributeValue的长度必须为2到64个字符，仅允许使用字母、数字、下划线以及以下字符：. , + = @ -（连字符），且不能包含空格。该值通常设置为用户标识（如Bob）或电子邮件地址（如Bob@example.com），但不应使用包含空格的显示名称（如Bob Green）。
```
<Attribute Name="https://www.huaweicloud.com/SAML/Attributes/SourceIdentity">
  <AttributeValue>Maria@example.com</AttributeValue>
</Attribute>
```