本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 关于 Amazon Cognito 用户 IdPs 池中 SAML 的注意事项
需知信息

实施 SAML 2.0 IdP 有一些要求和限制。实施 IdP 时，请参阅此部分。您还将找到一些有用的信息，可用于排查对用户池进行 SAML 联合身份验证期间的错误。

**Amazon Cognito 会为您处理 SAML 断言**  
Amazon Cognito 用户池支持 SAML 2.0 与 POST 绑定端点联合身份验证。这使您的应用程序不必检索或分析 SAML 断言响应，因为用户池直接通过用户代理从 IdP 接收 SAML 响应。您的用户池代表您的应用程序充当服务提供商（SP）。Amazon Cognito 支持 SP 发起和 IdP 发起的单点登录（SSO），如 [SAML V2.0 技术概览](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0-cd-02.html)的第 5.1.2 节和第 5.1.4 节中所述。

**提供有效的 IdP 签名证书**  
在用户池中配置 SAML IdP 时，SAML 提供者元数据中的签名证书不得过期。

**用户池支持多个签名证书**  
如果在 SAML 元数据中，您的 SAML IdP 包含多个签名证书，则在登录时，只要与 SAML 元数据中的任何证书匹配，您的用户池就会确定 SAML 断言有效。每份签名证书的长度不得超过 4096 个字符。

**维护中继状态参数**  
Amazon Cognito 和您的 SAML IdP 使用 `relayState` 参数维护会话信息。  

1. Amazon Cognito 支持大于 80 个字节的 `relayState` 值。虽然 SAML 规范规定 `relayState` 值“长度不得超过 80 个字节”，但目前的行业惯例往往偏离这种行为。因此，拒绝超过 80 个字节的 `relayState` 值将破坏许多标准 SAML 提供商集成。

1. `relayState` 令牌是对 Amazon Cognito 维护的状态信息的不透明引用。Amazon Cognito 不保证 `relayState` 参数的内容。不要解析其内容，以免您的应用程序依赖解析结果。有关更多信息，请参阅 [SAML 2.0 规范](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html)。

**识别 ACS 端点**  
您的 SAML 身份提供者要求您设置断言使用者端点。您的 IdP 使用 SAML 断言将您的用户重定向到此端点。在用户群体域中为您的 SAML 身份提供者中的 SAML 2.0 POST 绑定配置以下端点。  

```
https://Your user pool domain/saml2/idpresponse
With an Amazon Cognito domain:
https://mydomain.auth.us-east-1.amazoncognito.com/saml2/idpresponse
With a custom domain:
https://auth.example.com/saml2/idpresponse
```
有关用户池域的更多信息，请参阅 [配置用户池域](cognito-user-pools-assign-domain.md)。

**没有重播的断言**  
您无法向您的 Amazon Cognito `saml2/idpresponse` 端点重复或*重放* SAML 断言。重放的 SAML 断言的断言 ID 与早期 IdP 响应的 ID 重复。

**用户池 ID 是 SP 实体 ID**  
您必须向 IdP 提供服务提供商（SP）`urn` 中的用户池 ID，也称为*受众 URI* 或 *SP 实体 ID*。用户池的受众 URI 采用以下格式。  

```
urn:amazon:cognito:sp:us-east-1_EXAMPLE
```
您可以在 [Amazon Cognito 控制台](https://console.amazonaws.cn/cognito/home)的**用户池概览**下找到用户池 ID。

**映射所有必需属性**  
配置 SAML IdP，为用户池中根据需要设置的任何属性提供值。例如，`email` 是用户池的通用必需属性。在您的用户可以登录之前，SAML IdP 断言必须包含映射到**用户池属性** `email` 的声明。有关属性映射的更多信息，请参阅[将 IdP 属性映射到配置文件和令牌](cognito-user-pools-specifying-attribute-mapping.md)。

**断言格式有特定的要求**  
SAML IdP 必须在 SAML 断言中包括以下声明。  
+ `NameID` 声明。Amazon Cognito 通过 `NameID` 将 SAML 断言与目标用户关联起来。如果 `NameID` 发生变化，Amazon Cognito 会认为这是针对新用户的断言。您在 IdP 配置中设置为 `NameID` 的属性必须具有永久值。要将 SAML 用户分配给用户池中一致的用户配置文件，请根据一个值不变的属性分配您的 `NameID` 声明。

  ```
  <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:persistent">
    carlos
  </saml2:NameID>
  ```

  `urn:oasis:names:tc:SAML:1.1:nameid-format:persistent` 的 IdP `NameID` 声明中的 `Format` 表示您的 IdP 正在传递一个不变的值。Amazon Cognito 不需要这种格式声明，如果您的 IdP 没有指定 `NameID` 声明的格式，则会分配 `urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified` 格式。此行为符合 [SAML 2.0 规范的*复杂类型名称IDType*第 2.2.](https://groups.oasis-open.org/higherlogic/ws/public/download/35711/sstc-saml-core-errata-2.0-wd-06-diff.pdf/latest) 2 节。
+ 一项 `AudienceRestriction` 声明，所具有的 `Audience` 值将您的用户池 SP 实体 ID 设置为响应的目标。

  ```
  <saml:AudienceRestriction>
    <saml:Audience> urn:amazon:cognito:sp:us-east-1_EXAMPLE
  </saml:AudienceRestriction>
  ```
+ 对于 SP 发起的单点登录，`Response` 元素具有原始 SAML 请求 ID 的 `InResponseTo` 值。

  ```
  <saml2p:Response Destination="https://mydomain.auth.us-east-1.amazoncognito.com/saml2/idpresponse" ID="id123" InResponseTo="_dd0a3436-bc64-4679-a0c2-cb4454f04184" IssueInstant="Date-time stamp" Version="2.0" xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  ```
**注意**  
IdP 发起的 SAML 断言*不得*包含 `InResponseTo` 值。
+ 一个 `SubjectConfirmationData` 元素，具有用户池 `saml2/idpresponse` 端点的 `Recipient` 值，而对于 SP 发起的 SAML，具有与原始 SAML 请求 ID 匹配的 `InResponseTo` 值。

  ```
  <saml2:SubjectConfirmationData InResponseTo="_dd0a3436-bc64-4679-a0c2-cb4454f04184" NotOnOrAfter="Date-time stamp" Recipient="https://mydomain.auth.us-east-1.amazoncognito.com/saml2/idpresponse"/>
  ```

**SP 发起的登录请求**  
当 [对端点授权](authorization-endpoint.md) 将用户定向到您的 IdP 登录页面时，Amazon Cognito 会在 `HTTP GET` 请求的 URL 参数中包括 *SAML 请求*。SAML 请求包含有关用户池（包括 ACS 端点）的信息。您可以选择对这些请求应用加密签名。

**签署请求和加密响应**  
每个使用 SAML 提供者的用户池都会生成一个非对称密钥对和*签名证书*，以便让 Amazon Cognito 将数字签名分配给 SAML 请求。您配置为支持加密 SAML 响应的每个外部 SAML IdP 都会导致 Amazon Cognito 为该提供者生成新的密钥对和*加密证书*。要查看和下载带有公钥的证书，请在 Amazon Cognito 控制台的**社交和外部提供商**菜单中选择您的 IdP。  
要与来自用户池的 SAML 请求建立信任，可以向 IdP 提供用户池 SAML 2.0 签名证书的副本。如果您未将 IdP 配置为接受已签名的请求，则您的 IdP 可能会忽略您的用户池签署的 SAML 请求。  

1. Amazon Cognito 将数字签名应用于用户传递给 IdP 的 SAML 请求。您的用户池签署所有单点注销（SLO）请求，您可以将用户池配置为签署任何 SAML 外部 IdP 的单点登录（SSO）请求。当您提供证书副本时，您的 IdP 会验证用户的 SAML 请求的完整性。

1. 您的 SAML IdP 可以使用加密证书来加密 SAML 响应。当您配置采用 SAML 加密的 IdP 时，您的 IdP 只能发送加密的响应。

**对非字母数字字符进行编码**  
Amazon Cognito 不接受您的 IdP 作为属性值传递的 4 字节 UTF-8 字符（例如 😐 或 𠮷）。您可以将字符编码为 Base64，将其作为文本传递，然后在应用程序中对其进行解码。  
在以下示例中，将不接受属性声明：  

```
<saml2:Attribute Name="Name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
  <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">😐</saml2:AttributeValue>
</saml2:Attribute>
```
与上述示例不同，将接受以下属性声明：  

```
<saml2:Attribute Name="Name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
  <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">8J+YkA==</saml2:AttributeValue>
</saml2:Attribute>
```

**元数据端点必须具有有效的传送层安全性**  
如果您在使用 HTTPS 元数据终端节点 URL 创建 SAML IdP `InvalidParameterException` 时看到，例如 “*<metadata endpoint>*从中检索元数据时出错”，请确保元数据端点已正确设置了 SSL，并且存在与之关联的有效的 SSL 证书。有关验证证书的更多信息，请参阅[什么是 SSL/TLS 证书](https://www.amazonaws.cn/what-is/ssl-certificate/)？ 。

**对于 HTTP 或 HTTPS，元数据端点必须位于标准 TCP 端口上**  
Amazon Cognito 仅接受 HTTP URLs 的标准 TCP 端口 80 和 HTTPS 的 443 上的 SAML 提供商的元数据。作为安全最佳实践，请将 SAML 元数据托管在带有 `https://` 前缀的 TLS 加密 URL 处。以*`http://www.example.com/saml2/metadata.xml`*或 URLs 的格式输入元数据*`https://www.example.com/saml2/metadata.xml`*。Amazon Cognito 控制台 URLs 仅接受带有前`https://`缀的元数据。您也可以使用和配置 IdP 元数据。[CreateIdentityProvider[UpdateIdentityProvider](https://docs.amazonaws.cn/cognito-user-identity-pools/latest/APIReference/API_UpdateIdentityProvider.html)](https://docs.amazonaws.cn/cognito-user-identity-pools/latest/APIReference/API_CreateIdentityProvider.html)

**使用 IdP 发起的 SAML 的应用程序客户端只能使用 SAML 登录**  
当您激活对支持 IdP 启动登录应用程序客户端的 SAML 2.0 IdP 的支持时，您只能向该应用程序客户端添加其他 SAML IdPs 2.0。您无法将用户池中的用户目录*以及*所有非 SAML 外部身份提供者添加到以这种方式配置的应用程序客户端。

**注销响应必须使用 POST 绑定**  
`/saml2/logout` 端点接受 `LogoutResponse` 作为 `HTTP POST` 请求。用户池不接受带有 `HTTP GET` 绑定的注销响应。

**元数据签名证书轮换**  
如果您通过 URL 提供元数据，Amazon Cognito 会将 SAML 元数据缓存长达六个小时。执行任何元数据签名证书轮换时，请将元数据源配置为*同时*发布原始证书和新证书至少六个小时。当 Amazon Cognito 从元数据 URL 刷新缓存时，它会将每个证书视为有效，并且您的 SAML IdP 可以开始使用新证书签名 SAML 断言。在此时间后，您可以从发布的元数据中移除原始证书。