12.2. 创建 SAML 客户端

PDF

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

流程

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

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

12.2.1. 设置标签页

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

客户端设置

client settings saml

12.2.1.1. 常规设置

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

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

12.2.1.2. 访问设置

根 URL

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

主页 URL

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

有效的 Redirect URI

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

IDP-Initiated SSO URL 名称

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

IDP Initiated SSO Relay State

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

Master SAML 处理 URL

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

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

12.2.1.3. SAML 功能

名称 ID 格式

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

强制名称 ID 格式

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

强制 POST 绑定

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

强制工件绑定

如果启用，响应消息将通过 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 时才相关。

12.2.1.4. 签名和加密

签署文档

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

sign Assertions

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

签名算法

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

SAML 签名密钥名称

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

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

规范方法

XML 签名的规范方法。

12.2.1.5. 登录设置

登录主题

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

需要同意

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

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

在屏幕上显示客户端

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

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

客户端同意屏幕文本

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

12.2.1.6. 注销设置

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

12.2.2. keys 标签页

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

12.2.3. 高级标签页

这个标签对于特定情况有很多字段。其他主题中将涵盖一些字段。有关其他字段的详情，点问号图标。

12.2.3.1. 精细 Grain SAML 端点配置

徽标 URL: 引用客户端应用程序徽标的 URL。
策略 URL: Relying party Client 提供的 URL 提供给 End-User，以阅读有关如何使用配置集数据的 URL。
服务 URL 条款: 过期客户端向最终用户提供 URL，以阅读有关重新处理服务条款的 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 Binding URL。
Logout Service Redirect Binding URL: 重定向 Logout 服务的绑定 URL。
注销 Service Artifact Binding URL: Logout Service 的工件绑定 URL。当与 Force Artifact Binding 选项一起设置时，Artifact 绑定会被强制用于登录和注销流程。除非设置了此属性，否则工件 绑定不会用于注销。
注销 Service SOAP Binding URL: 重定向 Logout 服务的绑定 URL。仅在使用 back channel logout 时才适用。
工件绑定 URL: 将 HTTP 工件消息发送到的 URL。
工件解析服务: 将 ArtifactResolve 消息发送到的客户端 SOAP 端点的 URL。

12.2.4. IDP 启动登录

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

IDP 启动登录实施首选 POST over REDIRECT 绑定（查看 saml 绑定以获取更多信息）。因此，最终绑定和 SP URL 被选择如下：

如果定义了特定的 Assertion Consumer Service POST Binding URL （客户端设置 中的 SAML Endpoint Configuration 部分） POST 绑定通过该 URL 使用。
如果指定了常规 Master 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 查询参数中指定中继状态，即 root/realms/{realm}/protocol/saml/clients/{url-name}?RelayState=thestate。

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

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

请注意，您可以将来自代理 IDP 的基本客户端设置导入到外部 IDP 的客户端设置 - 仅使用代理 IDP 中的身份供应商的 SP Descriptor，并将 客户端/客户端-id 添加到端点 URL。

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

您可以使用标准的 SAML Entity Descriptor XML 文件导入客户端，而不是手动注册 SAML 2.0 客户端。

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

添加客户端

Import SAML client

流程

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

有些 SAML 客户端适配器（如 mod-auth-mellon ）需要 IDP 的 XML Entity Descriptor。您可以通过进入这个 URL 来查找此描述符：

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

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