向用户池添加 SAML 身份提供商 - Amazon Cognito
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

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

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

你可以选择让你的网络和移动应用程序用户通过 SAML 身份提供商 (IdP) 登录,例如微软 Active Directory 联合身份验证服务 (ADFS) 或 Shibboleth。您必须选择支持 SAML 2.0 标准的 SAML IdP。

借助托管的用户界面和联合终端节点,Amazon Cognito 可以对本地和第三方 IdP 用户进行身份验证,并发放 JSON 网络令牌 (JWT)。使用 Amazon Cognito 发行的令牌,您可以将多个身份源整合为适用于所有应用程序的通用 OpenID Connect (OIDC) 标准。Amazon Cognito 可以将您的第三方提供商的 SAML 声明处理为该 SSO 标准。您可以在、通过 Amazon CLI或使用 Amazon Cognito 用户池 API 创建和管理 SAML IdP。 Amazon Web Services Management Console要在中创建您的第一个 SAML IdP Amazon Web Services Management Console,请参阅。在用户池中添加和管理 SAML 身份提供商

使用 SAML 登录进行身份验证概述
注意

通过第三方 IdP 登录进行联合是 Amazon Cognito 用户池的一项功能。Amazon Cognito 身份池(有时也称为 Amazon Cognito 联合身份)是一种联合身份的实现,您必须在每个身份池中单独设置该联合身份。用户池可以是身份池的第三方 IdP。有关更多信息,请参阅Amazon Cognito 身份池

IdP 配置的快速参考

您必须将 SAML IdP 配置为接受请求并将响应发送到您的用户池。您的 SAML IdP 文档将包含有关如何将您的用户池添加为 SAML 2.0 IdP 的依赖方或应用程序的信息。以下文档提供了必须为 SP 实体 ID 和断言使用者服务 (ACS) URL 提供的值。

用户池 SAML 值快速参考
SP 实体 ID
urn:amazon:cognito:sp:us-east-1_EXAMPLE
ACS 网址
https://Your user pool domain/saml2/idpresponse

您必须配置您的用户池以支持您的身份提供商。添加外部 SAML IdP 的高级步骤如下。

  1. 从您的 IdP 下载 SAML 元数据,或检索元数据终端节点的网址。请参阅 配置您的第三方 SAML 身份提供商

  2. 向您的用户池中添加新的 IdP。上传 SAML 元数据或提供元数据网址。请参阅 在用户池中添加和管理 SAML 身份提供商

  3. 将 IdP 分配给您的应用程序客户端。请参阅 用户池应用程序客户端

关于 Amazon Cognito 用户 IdPs 池中的 SAML 须知事项

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,也称为受众 URISP 实体 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 外部身份提供商添加到以这种方式配置的应用程序客户端。

SAML 用户名区分大小写

当联合用户尝试登录时,SAML 身份提供商 (IdP) 会在用户的 SAML 断言中向 Amazon Cognito 传递一个NameId唯一的。Amazon Cognito 通过其 NameId 声明识别 SAML 联合身份用户。无论您的用户池的区分大小写设置如何,Amazon Cognito 在通过唯一且区分大小写的声明时,Amazon Cognito 都会识别从 SAML IdP 返回的联合用户。NameId如果您将 email 等属性映射到 NameId,并且您的用户更改其电子邮件地址,他们将无法登录您的应用程序。

从具有不会改变的值的 IdP 属性映射 SAML 断言中的 NameId

例如,Carlos 在您的不区分大小写的用户池中具有来自 Active Directory 联合身份验证服务 (ADFS) SAML 断言的用户配置文件,该断言传递了Carlos@example.comNameId 值。下次 Carlos 尝试登录时,您的 ADFS IdP 会传递carlos@example.comNameId 值。由于 NameId 的大小写必须完全匹配,登录不成功。

如果您的用户在其 NameID 更改后无法登录,请从您的用户池中删除他们的用户配置文件。Amazon Cognito 将在用户下次登录时创建新的用户配置文件。