13.2. 创建 SAML 客户端

红帽构建的 Keycloak 支持 SAML 2.0 进行注册的应用程序。支持 POST 和 Redirect 绑定。您可以选择需要客户端签名验证。您还可以让服务器签名和/或加密响应。

流程

点菜单中的 Clients。
点 Create client 进入 Create client 页面。
将 Client 类型设置为 SAML。
创建客户端
输入客户端的客户端 ID。这通常是 URL，是应用程序发送的 SAML 请求中的预期的 签发者 值。
点击 Save。此操作会创建客户端，并将您带到 Settings 选项卡。

以下小节描述了此选项卡上的每个设置。

13.2.1. 设置标签页

Settings 选项卡包含用于配置此客户端的许多选项。

客户端设置

client settings saml

13.2.1.1. 常规设置

客户端 ID: OIDC 请求中使用的字母数字 ID 字符串，以及红帽构建的 Keycloak 数据库来识别客户端。这个值必须与使用 AuthNRequests 发送的 issuer 值匹配。Red Hat build of Keycloak 从 Authn SAML 请求拉取签发者，并根据这个值将其与客户端匹配。
Name: 红帽构建的 Keycloak UI 屏幕中的客户端名称。要本地化名称，请设置替换字符串值。例如，字符串值，如 ${myapp}。如需更多信息，请参阅服务器开发人员指南。
描述: 客户端的描述。此设置也可以本地化。

始终在控制台中显示: 即使此用户没有活动的会话，也始终在帐户控制台中列出此客户端。

13.2.1.2. 访问设置

根 URL

当红帽构建的 Keycloak 使用配置的相对 URL 时，这个值会添加到 URL 中。

主页 URL

如果红帽构建的 Keycloak 需要链接到客户端，则会使用这个 URL。

有效的 Redirect URI

输入 URL 模式，然后点要添加的 + 符号。点要删除的 - 符号。单击 Save 以保存这些更改。仅允许在 URL 的末尾允许使用通配符值。例如： http://host.com/*$$。当确切的 SAML 端点没有注册，且红帽构建的 Keycloak 从请求中拉取 Assertion Consumer URL 时，会使用此字段。

IDP-Initiated SSO URL 名称

要在您要进行 IDP Initiated SSO 时引用客户端的 URL 片段名称。将此留空将禁用 IDP 启动的 SSO。您将从浏览器中引用的 URL 为： server-root/realms/{realm}/protocol/saml/clients/{client-url-name}

IDP 启动的 SSO 转发状态

当您想进行 IDP Initiated SSO 时，您要使用 SAML 请求发送的中继状态。

Master SAML 处理 URL

此 URL 用于所有 SAML 请求，响应则定向到 SP。它被用作 Assertion Consumer Service URL 和 Single Logout 服务 URL。

如果登录请求包含 Assertion Consumer Service URL，则这些登录请求将优先使用。此 URL 必须通过注册 Valid Redirect URI 模式进行验证。

13.2.1.3. SAML 功能

名称 ID 格式

主题的名称 ID 格式。如果没有在请求中指定名称 ID 策略，或者 Force Name ID Format 属性设置为 ON，则使用此格式。

强制名称 ID 格式

如果请求具有名称 ID 策略，忽略它并使用 Name ID Format 下的 Admin Console 中配置的值。

强制 POST 绑定

默认情况下，红帽构建的 Keycloak 使用原始请求的初始 SAML 绑定进行响应。通过启用 强制 POST Binding，红帽使用 SAML POST 绑定进行 Keycloak 响应，即使原始请求使用了重定向绑定。

强制工件绑定

如果启用，响应消息将通过 SAML ARTIFACT 绑定系统返回到客户端。

包括 AuthnStatement

SAML 登录响应可能会指定使用的身份验证方法，如密码，以及登录和会话过期的时间戳。默认启用 AuthnStatement，以便 AuthnStatement 元素将包含在登录响应中。把它设置为 OFF 会阻止客户端确定最大会话长度，这可以创建不过期的客户端会话。

include OneTimeUse Condition

如果启用，登录响应中包含一个 OneTimeUse Condition。

优化 REDIRECT 签名密钥查找

当设置为 ON 时，SAML 协议信息包括红帽构建的 Keycloak 原生扩展。此扩展包含一个带有签名密钥 ID 的提示。SP 使用扩展来签名验证，而不是尝试使用密钥验证签名。

这个选项适用于在查询参数中传输签名的 REDIRECT 绑定，在签名信息中没有找到这些信息。这与 POST 绑定消息不同，其中密钥 ID 始终包含在文档签名中。

当红帽构建的 Keycloak 服务器和适配器提供 IDP 和 SP 时，会使用这个选项。只有在 Sign Documents 设为 ON 时，这个选项才相关。

13.2.1.4. 签名和加密

签署文档

当设置为 ON 时，红帽构建的 Keycloak 使用域私钥对文档进行签名。

sign Assertions

断言已签名并嵌入 SAML XML Auth 响应中。

签名算法

签名 SAML 文档的算法。请注意，基于 SHA1 的算法已弃用，并可能在以后的版本中删除。我们建议使用一些更安全的算法，而不是 *_SHA1。另外，对于 *_SHA1 算法，如果 SAML 客户端在 Java 17 或更高版本上运行，验证签名无法正常工作。

SAML 签名密钥名称

使用 POST 绑定发送的签名 SAML 文档包含 KeyName 元素中的签名密钥的标识。此操作可以通过 SAML 签名密钥名称 选项控制。此选项控制 Keyname 的内容。

KEY_ID The KeyName 包含密钥 ID。这个选项是默认选项。
CERT_SUBJECT The KeyName 包含与 realm 密钥对应的证书中的主题。Microsoft Active Directory Federation Services 期望这个选项。
NONE KeyName hint 在 SAML 信息中完全省略。

规范方法

XML 签名的规范方法。

13.2.1.5. 登录设置

登录主题

用于 login、OTP、授予注册和忘记密码页面的主题。

需要同意

如果启用，用户必须同意客户端访问。

用于执行浏览器登录的客户端。由于无法确保 secret 可以与客户端安全保存，因此务必要通过配置正确的重定向 URI 来限制访问。

在屏幕上显示客户端

如果 Consent Required 为 Off，则应用此开关。

关
同意屏幕将仅包含与配置的客户端范围对应的同意。
On
此客户端本身的同意屏幕上也会有一个项。

客户端同意屏幕文本

如果启用了 屏幕上的 Consent required 和 Display client。包含有关此客户端权限的同意屏幕上的文本。

13.2.1.6. 退出设置

前端频道退出: 如果启用了 Front Channel Logout，应用程序需要一个浏览器重定向才能执行注销。例如，应用可能需要 Cookie 才能重置，这只能通过重定向来完成。如果禁用了 Front Channel Logout，红帽构建的 Keycloak 调用后台 SAML 请求，以从应用程序注销。

13.2.2. keys 标签页

加密断言: 使用域私钥加密 SAML 文档中的断言。AES 算法使用密钥大小为 128 位。
需要客户端签名: 如果启用了 客户端签名所需的，则来自客户端的文档将被签名。红帽构建的 Keycloak 将使用客户端公钥或证书在 Keys 选项卡中设置来验证此签名。
允许 ECP 流: 如果为 true，则允许此应用程序使用 SAML ECP 配置集进行身份验证。

13.2.3. 高级标签页

对于特定情况，此选项卡有许多字段。其他主题中涵盖了一些字段。有关其他字段的详情，点问号图标。

13.2.3.1. 精细的 SAML 端点配置

徽标 URL: 引用客户端应用程序的徽标的 URL。
策略 URL: Relying Party Client 为 End-User 提供的 URL，用于读取配置集数据的使用方式。
服务 URL 术语: Relying Party Client 提供给最终用户以阅读有关 Relying Party 服务条款的 URL。
Assertion Consumer Service POST Binding URL: Assertion Consumer Service 的 POST Binding URL。
Assertion Consumer Service Redirect Binding URL: 重定向 Assertion Consumer Service 的绑定 URL。
退出服务 POST Binding URL: Logout 服务的 POST 绑定 URL。
Logout Service Redirect Binding URL: Logout 服务的重定向绑定 URL。
logout Service Artifact Binding URL: Logout 服务的工件绑定 URL。与 Force Artifact Binding 选项一起设置时，Artifact binding 会同时用于登录和注销流。除非设置了此属性，否则不会用于注销工件 绑定。
退出服务 SOAP 绑定 URL: Logout 服务的重定向绑定 URL。仅在使用 后端频道注销 时才适用。
工件绑定 URL: 将 HTTP 工件消息发送到的 URL。
工件解析服务: 将 ArtifactResolve 消息发送到的客户端 SOAP 端点的 URL。

13.2.4. IDP 启动登录

IDP Initiated Login 是一个功能，允许您在红帽构建的 Keycloak 服务器中设置端点，以登录到特定的应用程序/客户端。在客户端的 Settings 选项卡中，您需要指定 IDP Initiated SSO URL 名称。这是一个简单的字符串，其中没有空格。之后，您可以在以下 URL 中引用您的客户端： root/realms/{realm}/protocol/saml/clients/{url-name}

IDP 启动的登录实现优先于 REDIRECT 绑定（检查 saml 绑定以了解更多信息）。因此，最终绑定和 SP URL 使用以下方法被选择：

如果定义了特定的 Assertion Consumer Service POST Binding URL （客户端设置中的 Fine Grain SAML Endpoint Configuration 部分） POST 绑定通过该 URL 使用。
如果指定了常规 主 SAML Processing URL，则在这个通用 URL 中再次使用 POST 绑定。
作为最后的手段，如果配置了 Assertion Consumer Service Redirect Binding URL （在 Fine Grain SAML Endpoint Configuration中） REDIRECT 绑定用于此 URL。

如果您的客户端需要特殊的中继状态，您也可以在 IDP Initiated SSO Relay State 字段中的 Settings 选项卡中配置它。或者，浏览器可以在 RelayState 查询参数中指定 relay 状态，即 example.e. root/realms/{realm}/protocol/saml/clients/{url-name}?RelayState=thestate。

使用身份代理时，可以从外部 IDP 为客户端设置 IDP Initiated Login。实际客户端在代理 IDP 中为 IDP Initiated Login 设置，如上所述。外部 IDP 必须为应用程序 IDP Initiated Login 设置客户端，该登录将指向指向代理的特殊 URL，并在代理 IDP 为所选客户端代表 IDP Initiated Login 端点。这意味着在外部 IDP 中的客户端设置：

IDP 启动的 SSO URL 名称设置为将作为 IDP Initiated Login 初始点发布的名称，
Fine Grain SAML Endpoint Configuration 部分中的 assertion Consumer Service POST Binding URL 必须设置为以下 URL: broker-root/realms/{broker-realm}/broker/{idp-name}/endpoint/clients/{client-id}，其中：
- broker-root 是基本代理 URL
- broker-realm 是声明外部 IDP 的 broker 中的域名称
- IdP-name 是代理的外部 IDP 的名称
- client-id 是代理中定义的 SAML 客户端的 IDP Initiated SSO URL Name 属性的值。它是此客户端，可用于来自外部 IDP 的 IDP 启动登录。

请注意，您可以从代理 IDP 将基本客户端设置从代理 IDP 导入到客户端设置 - 只使用代理 IDP 中的身份提供程序设置中提供的 SP Descriptor，并将 client/client-id 添加到端点 URL。

13.2.5. 使用实体描述符创建客户端

您可以使用标准 SAML 实体描述符 XML 文件导入客户端，而不是手动注册 SAML 2.0 客户端。

Client 页面包含一个 Import client 选项。

添加客户端

Import SAML client

流程

单击 Browse。
加载包含 XML 实体描述符信息的文件。
检查信息以确保一切设置正确。

有些 SAML 客户端适配器（如 mod-auth-mellon ）需要 IDP 的 XML 实体描述符。您可以通过转至此 URL 来查找此描述符：

root/realms/{realm}/protocol/saml/descriptor

其中 realm 是您的客户端的域。