向用户池添加 SAML 身份提供商

用户池 SAML 值快速参考

SP 实体 ID

urn:amazon:cognito:sp:us-east-1_EXAMPLE

ACS 网址

https://Your user pool domain/saml2/idpresponse

Amazon Cognito 会为您处理 SAML 断言

Amazon Cognito 用户群体支持 SAML 2.0 与 POST 绑定端点联合身份验证。这使您的应用程序不必检索或分析 SAML 断言响应，因为用户池直接通过用户代理从 IdP 接收 SAML 响应。您的用户池代表您的应用程序充当服务提供商（SP）。Amazon Cognito 支持 SAM 启动和 IDP 启动的单点登录 (SSO)，如 SAML V2.0 技术概述第 5.1.2 和 5.1.4 节中所述。

提供有效的 IdP 签名证书

在用户池中配置 SAML IdP 或用户使用 SAML 2.0 进行身份验证时，SAML 提供商元数据中的签名证书不得过期。

用户池支持多个签名证书

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

维护继电器状态参数

Amazon Cognito 和您的 SAML IdP 使用 relayState 参数维护会话信息。

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

2. 该relayState令牌不透明地引用了由 Amazon Cognito 维护的状态信息。Amazon Cognito 不保证 relayState 参数的内容。不要解析其内容，以免您的应用程序依赖解析结果。有关更多信息，请参阅 SAML 2.0 规范。

识别 ACS 端点

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

https://Your user pool domain/saml2/idpresponse
With an Amazon Cognito domain:
https://mydomain.us-east-1.amazoncognito.com/saml2/idpresponse
With a custom domain:
https://auth.example.com/saml2/idpresponse

有关用户群体域的更多信息，请参阅 配置用户池域。

没有重播的断言

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

用户池 ID 是 SP 实体 ID

您必须向 IdP 提供您在服务提供商 (SP) 中的用户池 IDurn，也称为受众 URI 或 SP 实体 ID。用户群体的受众 URI 采用以下格式。

urn:amazon:cognito:sp:us-east-1_EXAMPLE

您可以在 Amazon Cognito 控制台的用户池概述下找到您的用户池 ID。

映射所有必需的属性

配置 SAML IdP，为用户群体中根据需要设置的任何属性提供值。例如，email 是用户群体的通用必需属性。在您的用户可以登录之前，SAML IdP 断言必须包含映射到用户群体属性 email 的声明。有关属性映射的更多信息，请参阅指定适用于用户池的身份提供商属性映射。

断言格式有特定的要求

您的 SAML IdP 必须在 SAML 断言中包含以下声明。

1. 一项NameID索赔。Amazon Cognito 通过将 SAML 断言与目标用户关联起来。NameID如果NameID发生变化，Amazon Cognito 会认为该声明是针对新用户的。您在 IdP 配置NameID中设置的属性必须具有永久值。

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

2. 一项 AudienceRestriction 声明，所具有的 Audience 值将您的用户群体 SP 实体 ID 设置为响应的目标。

   <saml:AudienceRestriction>
     <saml:Audience> urn:amazon:cognito:sp:us-east-1_EXAMPLE
   </saml:AudienceRestriction>

3. 对于 SP 发起的单点登录，其InResponseTo值为原始 SAML 请求 ID 的Response元素。

   <saml2p:Response Destination="https://mydomain.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

4. 一个SubjectConfirmationData元素，其Recipient值为您的用户池saml2/idpresponse终端节点，对于由 SP 发起的 SAML，其InResponseTo值与原始 SAML 请求 ID 相匹配。

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

SP 发起的登录请求

当 对端点授权 将用户定向到您的 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 请求的完整性。

2. 您的 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（例如，“Error retrieving metadata from <metadata endpoint> (从 <元数据终端节点> 检索元数据时出错)”），请确保元数据终端节点已正确设置 SSL，并且存在与之关联的有效 SSL 证书。有关验证证书的更多信息，请参阅什么是 SSL/TLS 证书？ 。

使用 IDP 启动的 SAML 的应用程序客户端只能使用 SAML 登录

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