关于 Amazon Cognito 用户群体中的 SAML IdP 需要了解的事项 - Amazon Cognito

关于 Amazon Cognito 用户群体中的 SAML IdP 需要了解的事项

实施 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 技术概览的第 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 提供商集成。

  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）urn 中的用户池 ID，也称为受众 URI 或 SP 实体 ID。用户群体的受众 URI 采用以下格式。

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

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

映射所有必需属性

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

断言格式有特定的要求

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 规范第 2.2.2 节复杂类型 NameIDType。

  • 一项 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.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.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 登录

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

注销响应必须使用 POST 绑定

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