12.2. 创建 SAML 客户端

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

流程

点菜单中的 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 启动的 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 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 策略，忽略它并使用 Name ID Format 下的 Admin Console 中配置的值。

强制 POST 绑定

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

强制工件绑定

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

包括 AuthnStatement

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

include OneTimeUse Condition

如果启用，则登录响应中包含 oneTimeUse Condition。

优化 REDIRECT 签名密钥查找

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

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

当红帽构建 Keycloak 服务器和适配器提供 IDP 和 SP 时，会使用这个选项。这个选项仅在将 Sign 文档 设置为 ON 时相关。

12.2.1.4. 签名和加密

签署文档

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

签署断言

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

签名算法

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

SAML 签名密钥名称

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

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

规范化方法

XML 签名的规范方法。

12.2.1.5. 登录设置

登录主题

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

需要同意

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

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

在屏幕上显示客户端

如果 Consent Required 为 Off，则适用此交换机。

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

客户端同意屏幕文本

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

12.2.1.6. 注销设置

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

12.2.2. Key 标签页

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

12.2.3. 高级标签页

这个选项卡对于特定情况有很多字段。一些字段将在其他主题中介绍。有关其他字段的详情，请点击问号图标。

12.2.3.1. 精细 SAML 端点配置

徽标 URL: 引用客户端应用程序徽标的 URL。
策略 URL: Relying Party Client 向最终用户提供的 URL，以读取如何使用配置集数据。
服务 URL 术语: Relying Party 客户端向最终用户提供的 URL，以读取 Relying Party 的服务条款。
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 Service 的 POST 绑定 URL。
Logout Service Redirect Binding URL: 重定向 Logout 服务的绑定 URL。
注销 Service Artifact Binding URL: Logout 服务的工件绑定 URL。当与 Force Artifact Binding 选项一起设置时，对于登录和注销流，会强制使用 Artifact 绑定。除非设置了此属性，否则工件 绑定不会用于退出。
注销 Service SOAP Binding URL: 重定向 Logout 服务的绑定 URL。仅在使用 后频道退出时 才适用。
工件绑定 URL: 将 HTTP 工件消息发送到的 URL。
工件解析服务: 将 ArtifactResolve 消息发送到的客户端 SOAP 端点的 URL。

12.2.4. IDP 启动登录

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

IDP 启动登录实施首选通过 REDIRECT 绑定 POST （检查 saml 绑定以了解更多信息）。因此，最终绑定和 SP URL 使用以下方法被选择：

如果定义了特定的 Assertion Consumer Service POST Binding URL （在客户端设置的 Fine Grain SAML Endpoint Configuration 部分） POST 绑定通过该 URL 使用。
如果指定了常规 Master SAML 处理 URL，则 POST 绑定将在整个常规 URL 中再次使用。
作为最后的粒度，如果配置了 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 启动登录端点。这意味着，在外部 IDP 的客户端设置中：

IDP Initiated SSO URL Name 设置为将作为 IDP Initiated Login point 发布的名称。
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 的代理中的域名
- IdP-name 是代理的外部 IDP 的名称
- client-id 是代理上定义的 SAML 客户端的 IDP Initiated SSO URL Name 属性的值。这是此客户端，将可从外部 IDP 开始登录。

请注意，您可以将基本的客户端设置从代理 IDP 导入到外部 IDP 的客户端设置中 - 仅使用代理 IDP 中的身份提供程序设置中的 SP 描述符，并将 客户端/客户端ID 添加到端点 URL 中。

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

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

Client 页面包含一个 Import 客户端 选项。

添加客户端

Import SAML client

流程

点 Browse。
加载包含 XML 实体描述符信息的文件。
查看信息以确保正确设置所有内容。

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

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

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