服务器管理指南

以下部分包含关于如何配置 Keycloak 电子邮件设置以将 XOAUTH2 身份验证与一些已知的第三方软件 SMTP 服务器一起使用的提示。

语言环境选择器提供程序根据可用信息建议最佳语言环境。但是，通常不知道用户是谁。因此，先前经过身份验证的用户的语言环境会保存在持久性 Cookie 中。

选择语言环境的逻辑使用以下可用的第一个选项

当用户通过身份验证时，会触发一个操作来更新前面提到的持久 cookie 中的语言环境。如果用户在登录页面上通过语言环境选择器主动切换了语言环境，则用户的语言环境也会在此处更新。

如果您想更改选择语言环境的逻辑，您可以选择创建自定义的 LocaleSelectorProvider。有关详细信息，请参阅 服务器开发指南。

如果您启用 忘记密码，用户可以在忘记密码或丢失 OTP 生成器时重置其登录凭据。

电子邮件中发送的文本是可配置的。有关更多信息，请参阅 服务器开发指南。

当用户点击电子邮件链接时，Keycloak 会要求他们更新密码；如果他们设置了 OTP 生成器，Keycloak 会要求他们重新配置 OTP 生成器。出于安全原因，该流程强制联合用户在重置凭据后重新登录，如果使用相同的身份验证会话（同一浏览器），则内部数据库用户保持登录状态。根据您组织的安全要求，您可以更改默认行为。

要更改此行为，请执行以下步骤

已登录用户关闭浏览器会销毁他们的会话，该用户必须重新登录。您可以设置 Keycloak 以保持用户的登录会话打开，如果该用户在登录时点击了记住我复选框。此操作将登录 cookie 从仅会话 cookie 转换为持久 cookie。

在 realm 的常规设置中，您可以定义哪个 身份验证上下文类引用 (ACR) 值映射到哪个 身份验证级别 (LoA)。ACR 可以是任何值，而 LoA 必须是数字。acr 声明可以在 OIDC 请求中发送的 claims 或 acr_values 参数中请求，并且它也包含在访问令牌和 ID 令牌中。映射的数字用于身份验证流程条件中。

如果特定客户端需要使用与 realm 不同的值，则也可以在客户端级别指定映射。但是，最佳实践是坚持 realm 映射。

有关更多详细信息，请参阅 逐步验证 和 官方 OIDC 规范。

使用此工作流程，用户将必须使用 UPDATE_EMAIL 操作来更改自己的电子邮件地址。

此操作与单个电子邮件输入表单关联。如果 realm 禁用了电子邮件验证，则此操作将允许在不进行验证的情况下更新电子邮件。如果 realm 启用了电子邮件验证，则此操作将向新电子邮件地址发送电子邮件更新操作令牌，而无需更改帐户电子邮件。只有操作令牌触发才会完成电子邮件更新。

应用程序可以通过利用 UPDATE_EMAIL 作为 AIA（应用程序启动的操作） 将其用户发送到电子邮件更新表单。

我们建议您定期轮换密钥。首先创建优先级高于现有活动密钥的新密钥。您可以改为创建优先级相同的新密钥，并将之前的密钥设为被动密钥。

一旦新密钥可用，所有新令牌和 cookie 都将使用新密钥签名。当用户向应用程序进行身份验证时，SSO cookie 将使用新签名进行更新。当 OpenID Connect 令牌刷新时，新令牌将使用新密钥签名。最终，所有 cookie 和令牌都使用新密钥，一段时间后可以删除旧密钥。

删除旧密钥的频率是在安全性和确保所有 cookie 和令牌都更新之间进行权衡。考虑每三到六个月创建新密钥，并在创建新密钥后一到两个月删除旧密钥。如果用户在新密钥添加和旧密钥删除之间的时间段内处于非活动状态，则该用户将必须重新进行身份验证。

轮换密钥也适用于离线令牌。为了确保它们被更新，应用程序需要在旧密钥被删除之前刷新令牌。

使用此过程生成密钥对，包括自签名证书。

更改提供程序的优先级不会导致密钥重新生成，但如果您想更改密钥大小，您可以编辑提供程序，然后将生成新密钥。

您可以通过从 RSA 生成的密钥对中提取证书，并在新的密钥库中使用该证书来轮换密钥。

要添加从其他地方获得的密钥对和证书，请选择 提供程序 并从下拉列表中选择 rsa。您可以更改优先级以确保新密钥对成为活动密钥对。

要添加存储在主机上的 Java 密钥库文件中的密钥对和证书，请选择 提供程序 并从下拉列表中选择 java-keystore。您可以更改优先级以确保新密钥对成为活动密钥对。

为了加载关联的证书链，必须使用用于加载密钥对的相同 密钥别名 将其导入到 Java 密钥库文件中。

Keycloak 将签名密钥仅本地存储，并且永远不会与客户端应用程序、用户或其他实体共享。但是，如果您认为您的 realm 签名密钥已泄露，您应首先生成新的密钥对（如上所述），然后立即删除泄露的密钥对。

或者，您可以从 Providers 表中删除提供程序。

推送 not-before 策略可确保客户端应用程序不接受由泄露的密钥签名的现有令牌。客户端应用程序也被迫从 Keycloak 下载新的密钥对，因此由泄露的密钥签名的令牌将无效。

Keycloak 将用户从 LDAP 导入到本地 Keycloak 用户数据库。用户数据库的此副本按需或通过定期后台任务同步。密码同步存在例外。Keycloak 永远不会导入密码。密码验证始终在 LDAP 服务器上进行。

同步的优势在于，所有 Keycloak 功能都可以高效工作，因为任何所需的额外每用户数据都本地存储。缺点是每次 Keycloak 首次查询特定用户时，Keycloak 都会执行相应的数据库插入。此外，当导入的用户作为搜索操作的一部分返回时，将为每个用户执行相应的 LDAP 搜索，以检查用户是否仍然存在于 LDAP 中并进行一些基本验证。

您可以将导入与 LDAP 服务器同步。当 LDAP 映射器始终从 LDAP 而不是数据库读取特定属性时，导入同步是不必要的。

您可以将 LDAP 与 Keycloak 一起使用，而无需将用户导入到 Keycloak 用户数据库中。LDAP 服务器备份 Keycloak 运行时使用的通用用户模型。如果 LDAP 不支持 Keycloak 功能所需的数据，则该功能将无法工作。这种方法的优点是您没有导入和同步 LDAP 用户副本到 Keycloak 用户数据库的资源消耗。

LDAP 配置页面上的 Import Users（导入用户）开关控制此存储模式。要导入用户，请将此开关切换为 ON（开启）。

用户和管理员可以修改用户元数据，用户通过帐户控制台，管理员通过管理控制台。LDAP 配置页面上的 Edit Mode（编辑模式）配置定义了用户的 LDAP 更新权限。

组和角色映射器中也提供了类似的属性，允许将组和角色添加到用于搜索组/角色的基本 DN 的子 DN 中。

当您为 LDAP 存储配置安全连接 URL（例如，ldaps://myhost.com:636）时，Keycloak 使用 SSL 与 LDAP 服务器通信。在 Keycloak 服务器端配置信任存储，以便 Keycloak 可以信任与 LDAP 的 SSL 连接 - 请参阅配置信任存储指南。

Use Truststore SPI 配置属性已弃用。通常应将其保留为 Always（始终）。

如果您设置 Import Users（导入用户）选项，LDAP 提供程序将处理将 LDAP 用户导入到 Keycloak 本地数据库中。当用户首次登录或作为用户查询的一部分返回时（例如，使用管理控制台中的搜索字段），LDAP 提供程序会将 LDAP 用户导入到 Keycloak 数据库中。在身份验证期间，将验证 LDAP 密码。

如果您想将所有 LDAP 用户同步到 Keycloak 数据库中，请在 LDAP 提供程序配置页面上配置并启用 Sync Settings（同步设置）。

存在两种类型的同步

最佳同步方式是在首次创建 LDAP 提供程序时单击同步所有用户，然后设置定期同步更改的用户。

LDAP 映射器是由 LDAP 提供程序触发的 listeners（监听器）。它们为 LDAP 集成提供了另一个扩展点。LDAP 映射器在以下情况下被触发：

当您创建 LDAP 联合提供程序时，Keycloak 会自动为此提供程序提供一组 mappers（映射器）。用户可以更改此集合，用户还可以开发映射器或更新/删除现有映射器。

用户属性映射器将基本的 Keycloak 用户属性（例如用户名、名字、姓氏和电子邮件）映射到相应的 LDAP 属性。您可以扩展这些映射器并提供您自己的其他属性映射。管理员控制台提供工具提示以帮助配置相应的映射器。

当 Keycloak 更新密码时，Keycloak 以纯文本格式发送密码。此操作与在内置 Keycloak 数据库中更新密码不同，在内置 Keycloak 数据库中，Keycloak 会在将密码发送到数据库之前对其进行哈希和加盐处理。对于 LDAP，Keycloak 依赖 LDAP 服务器来哈希和加盐密码。

默认情况下，MSAD、RHDS 或 FreeIPA 等 LDAP 服务器会哈希和加盐密码。OpenLDAP 或 ApacheDS 等其他 LDAP 服务器以纯文本形式存储密码，除非您使用 RFC3062 中描述的LDAPv3 密码修改扩展操作。在 LDAP 配置页面中启用 LDAPv3 密码修改扩展操作。有关更多详细信息，请参阅您的 LDAP 服务器的文档。

为了在管理 LDAP 连接时提高效率，并在处理多个连接时提高性能，您可以启用连接池。通过这样做，当连接关闭时，它将被返回到池中以供将来使用，从而减少始终创建新连接的成本。

LDAP 连接池配置使用以下系统属性进行配置

默认情况下，为 plain 和 ssl 协议都启用了连接池。

有关更多详细信息，请参阅 Java LDAP 连接池配置 文档。

要设置任何这些属性，您可以设置 JAVA_OPTS_APPEND 环境变量

对于类别 org.keycloak.storage.ldap，将日志记录级别提高到 TRACE 非常有用。通过此设置，许多日志消息将以 TRACE 级别发送到服务器日志，包括发送到 LDAP 服务器的所有查询以及用于发送查询的参数的日志记录。当您在用户论坛或 JIRA 上创建任何 LDAP 问题时，请考虑附加启用 TRACE 日志记录的服务器日志。如果日志太大，一个好的替代方法是仅包含来自服务器日志的代码片段，其中包含在导致您出现问题的操作期间添加到日志的消息。

它显示了您的 LDAP 提供程序的配置。在您提出问题或报告错误之前，最好包含此消息以显示您的 LDAP 配置。最终可以随意替换您不想包含的某些配置更改为某些占位符值。一个示例是 bindDn=some-placeholder 。对于 connectionUrl，也可以随意替换它，但通常最好至少包含使用的协议（ldap 与 ldaps）。同样，包含您的 LDAP 映射器配置的详细信息也很有用，这些详细信息在 DEBUG 级别以如下消息显示

请注意，这些消息仅在启用 DEBUG 日志记录时显示。

即使在服务器重新启动后，如果仍然没有出现有关连接池的消息，则可能表明连接池不适用于您的 LDAP 服务器。

FreeIPA 容器镜像 在 Quay.io 上可用。要设置 FreeIPA 服务器，请参阅 FreeIPA 文档。

联合提供程序使用 D-BUS 从 SSSD 获取数据。它使用 PAM 验证数据。

Keycloak 使用 DBus-Java 项目与 D-Bus 进行低级别通信，并使用 JNA 通过操作系统可插拔身份验证模块 (PAM) 进行身份验证。

尽管现在 Keycloak 包含运行 SSSD 提供程序所需的所有库，但仍需要 JDK 版本 21。因此，只有在主机配置正确且使用 JDK 21 运行 Keycloak 时，才会显示 SSSD 提供程序。

安装完成后，配置联合 SSSD 存储。

现在您可以使用 FreeIPA/IdM 用户和凭据对 Keycloak 进行身份验证。

默认情况下，Keycloak 提供了一个基本的用户配置文件配置，涵盖了一些最常见的用户属性

在 Keycloak 中，“用户名”和“电子邮件”属性都经过特殊处理，因为它们通常用于识别、验证和链接用户帐户。 对于这些属性，您只能更改其设置，而不能删除它们。

正如您将在以下章节中看到的那样，您可以自由更改默认配置，方法是引入您自己的属性或更改任何可用属性的设置，以更好地满足您的需求。

在 Keycloak 中，用户通过不同的上下文进行管理

除了“管理”上下文之外，所有其他上下文都被视为最终用户上下文，因为它们与用户自助服务流程相关。

了解这些上下文对于理解在管理用户时用户配置文件配置将在何处生效非常重要。 无论用户在哪个上下文中被管理，都将使用相同的用户配置文件配置来呈现 UI 并验证属性值。

正如您将在以下章节中看到的那样，您可能会限制某些属性仅在管理上下文中可用，并为最终用户完全禁用它们。 反之亦然，如果您不希望管理员访问某些用户属性，而只允许最终用户访问。

默认情况下，Keycloak 只会识别在您的用户配置文件配置中定义的属性。 服务器会忽略任何其他未在此处明确定义的属性。

通过严格控制可以为用户设置哪些用户属性以及如何验证其值，Keycloak 可以为您的 realm 添加另一道防御屏障，并帮助您防止与用户关联的意外属性和值。

也就是说，用户属性可以按如下方式分类

虽然默认情况下禁用非托管属性，但您可以使用不同的策略配置您的 realm，以定义服务器如何处理它们。 为此，请点击左侧菜单中的Realm 设置，点击常规选项卡，然后从非托管属性设置中选择以下任何选项

这些策略使您可以精细地控制服务器将如何处理非托管属性。 您可以选择完全禁用，或者仅在通过管理上下文管理用户时支持非托管属性。

当启用非托管属性（即使是部分启用）时，您可以从管理控制台中的“用户详细信息”UI 的“属性”选项卡管理它们。 如果策略设置为“已禁用”，则此选项卡不可用。

作为安全建议，请尽量遵守最严格的策略（例如：“已禁用”或“管理员可以编辑”），以防止当用户通过最终用户上下文管理其个人资料时，为您的用户设置意外属性（和值）。 避免设置“已启用”策略，并优先在您的用户配置文件配置中定义最终用户可以管理的所有属性，并在您的控制之下。

正如您将在以下章节中看到的那样，您还可以通过选择属性是否应用户和/或管理员可见或可写来限制属性的受众。

对于非托管属性，最大长度为 2048 个字符。 要指定不同的最小或最大长度，请将非托管属性更改为托管属性并添加长度验证器。

用户配置文件配置是在每个 realm 的基础上进行管理的。 为此，请点击左侧菜单中的Realm 设置链接，然后点击用户配置文件选项卡。

在属性子选项卡中，您可以看到所有托管属性的列表。

在属性组子选项卡中，您可以管理属性组。 属性组允许您关联属性，以便在呈现面向用户的表单时将它们一起显示。

在JSON 编辑器子选项卡中，您可以查看和编辑 JSON 配置。 您可以使用此选项卡来获取当前配置或手动管理它。 您在此选项卡上所做的任何更改都会反映在其他选项卡中，反之亦然。

在下一节中，您将学习如何管理属性。

在属性子选项卡中，您可以创建、编辑和删除托管属性。

要定义新属性并将其与用户配置文件关联，请点击属性列表顶部的创建属性按钮。

配置属性时，您可以定义以下设置

当您创建属性时，该属性仅在管理上下文中可用，以避免意外地向最终用户公开属性。实际上，当最终用户通过最终用户上下文管理他们的个人资料时，该属性将无法被最终用户访问。您可以随时根据您的需要更改 Permissions 设置。

您可以启用对受管理属性的验证，以确保属性值符合特定规则。为此，您可以在管理属性时从 Validations 设置中添加或删除验证器。

验证发生在任何写入属性的时候，并且它们可能会抛出错误，当值未能通过验证时，这些错误将显示在 UI 中。

出于安全原因，每个可由用户编辑的属性都应该进行验证，以限制用户输入的值的大小。如果未指定 length 验证器，Keycloak 默认最大长度为 2048 个字符。

为了将额外的信息传递给前端，可以使用注解来装饰属性，以指示如何渲染属性。当扩展 Keycloak 主题以基于与属性关联的注解动态渲染页面时，此功能主要有用。

注解用于例如 更改属性的 HTML type 和 更改属性的 DOM 表示形式，正如您将在以下部分中看到的那样。

注解是与 UI 共享的键/值对，以便它们可以更改与属性对应的 HTML 元素的渲染方式。您可以为属性设置任何您想要的注解，只要注解受您的领域正在使用的主题支持。

在 属性组 子选项卡中，您可以创建、编辑和删除属性组。属性组允许您为相关的属性定义一个容器，以便它们在面向用户的表单中一起呈现。

要创建新组，请单击属性组列表顶部的 创建属性组 按钮。

配置组时，您可以定义以下设置

用户配置文件配置使用明确定义的 JSON 模式存储。您可以选择通过单击 JSON 编辑器 子选项卡直接编辑用户配置文件配置。

JSON 模式定义如下

该模式支持您需要的任意数量的属性和组。

unmanagedAttributePolicy 属性通过设置以下值之一来定义非托管属性策略。有关更多详细信息，请查看 了解托管和非托管属性。

来自所有用户配置文件上下文（包括管理控制台）的 UI 都会根据您的用户配置文件配置动态呈现。

默认呈现机制提供以下功能

为了确保最终用户配置文件符合配置，管理员可以使用 VerifyProfile 必需操作，以最终强制用户在向 Keycloak 验证身份时更新其配置文件。

启用后，当用户进行身份验证时，VerifyProfile 操作将执行以下步骤

VerifyProfile 操作默认启用。要禁用它，请单击左侧菜单上的 身份验证 链接，然后单击 必需操作 选项卡。在此选项卡中，使用 VerifyProfile 操作的 已启用 开关来禁用它。

如果您想在配置属性、属性组和注解时使用国际化消息，您可以使用占位符设置它们的显示名称、描述和值，该占位符将转换为消息包中的消息。

为此，您可以使用占位符来解析消息键，例如 ${myAttributeName}，其中 myAttributeName 是消息包中消息的键。有关如何将消息包添加到自定义主题的更多详细信息，请参阅 服务器开发人员指南。

如果用户已经有密码，则可以在 重置密码 部分重置密码。

您还可以请求用户重置密码。

或者，您可以向用户发送电子邮件，请求用户重置 OTP 生成器。如果用户已经拥有 OTP 凭据，以下步骤也适用。

启用此设置后，注册 链接将显示在管理控制台的登录页面上。

您可以设置任何用户都需要的操作。

您可以指定所有新用户首次登录之前需要执行哪些操作。这些要求适用于通过 Users（用户） 页面上的 Add User（添加用户） 按钮或登录页面上的 Register（注册） 链接创建的用户。

您可以启用一个必需的操作，即新用户必须接受条款和条件才能首次登录 Keycloak。

如果用户由于活动的 SSO 会话而已通过身份验证，则该用户通常不需要主动重新身份验证。但是，如果该用户主动身份验证的时间超过五分钟前，则当请求某些 AIA 时，客户端仍然可以请求重新身份验证。以下是此指南的例外情况：

一些 AIA 可能需要与操作名称一起发送参数。例如，只有 AIA 才能触发 删除凭据 操作，并且它需要与操作名称一起发送参数，该参数指向要删除的凭据的 ID。因此，此示例的 URL 将是 kc_action=delete_credential:ce1008ac-f811-427f-825a-c0b878d1c24b。在这种情况下，冒号字符 (ce1008ac-f811-427f-825a-c0b878d1c24b) 后的部分包含要删除的特定用户的凭据 ID。删除凭据 操作会显示确认屏幕，用户可以在其中确认同意删除凭据。

要查看所有可用操作，请登录到管理控制台，然后转到右上角，单击 Realm info → Provider info 选项卡 → 找到提供程序 required-action。但请注意，根据在必需操作选项卡中为您的 realm 启用的操作，这可能会受到进一步限制。

您可以在 必需操作 选项卡上启用此功能。

您可以向特定用户授予允许帐户删除的角色。

一旦您拥有 delete-account 角色，您就可以删除自己的帐户。

您可以注销 realm 中的所有用户。从 Action（操作）列表中，选择 Sign out all active sessions（注销所有活动会话）。所有 SSO cookie 都将失效。Keycloak 通过使用 Keycloak OIDC 客户端适配器通知客户端注销事件。在活动浏览器会话中请求身份验证的客户端必须重新登录。SAML 等客户端类型不会收到后通道注销请求。

复合角色 与组类似，因为它们提供相同的功能。它们之间的区别在于概念。复合角色将权限模型应用于一组服务和应用程序。使用复合角色来管理应用程序和服务。

组侧重于用户集合及其在组织中的角色。使用组来管理用户。

此屏幕截图显示已存在一些默认组。

Keycloak 中 OTP 生成器可用的算法是基于时间和基于计数器的。

使用基于时间的一次性密码 (TOTP)，令牌生成器将哈希当前时间和共享密钥。服务器通过比较时间窗口内的哈希值与提交的值来验证 OTP。TOTP 在短时间内有效。

使用基于计数器的一次性密码 (HOTP)，Keycloak 使用共享计数器而不是当前时间。Keycloak 服务器在每次成功的 OTP 登录时递增计数器。有效的 OTP 在成功登录后会更改。

TOTP 比 HOTP 更安全，因为可匹配的 OTP 在短时间内有效，而 HOTP 的 OTP 在不确定的时间内有效。HOTP 比 TOTP 更用户友好，因为输入 OTP 没有时间限制。

HOTP 每次服务器递增计数器时都需要数据库更新。在高负载期间，此更新会消耗身份验证服务器的性能。为了提高效率，TOTP 不会记住使用过的密码，因此无需执行数据库更新。缺点是在有效时间间隔内可以重用 TOTP。

Keycloak 有几个内置流程。您无法修改这些流程，但可以更改流程的需求以满足您的需要。

设计流程时，重要的功能和安全注意事项适用。

要创建流程，请执行以下操作

创建新流程时，您必须首先创建具有以下选项的顶层流程

当 Keycloak 创建流程后，Keycloak 会显示 添加步骤 和 添加子流程 按钮。

三个因素决定了流程和子流程的行为。

执行具有各种各样的操作，从发送重置电子邮件到验证 OTP。使用 添加步骤 按钮添加执行。

身份验证执行可以选择配置参考值。身份验证方法参考 (AMR) 协议映射器可以利用此值来填充 OIDC 访问令牌和 ID 令牌中的 amr 声明（有关 AMR 声明的更多信息，请参阅 RFC-8176）。当为客户端配置了身份验证方法参考 (AMR) 协议映射器时，它将使用用户在身份验证流程期间成功完成的任何身份验证器执行的参考值来填充 amr 声明。

存在两种类型的执行，自动执行 和 交互式执行。自动执行 类似于 Cookie 执行，并将自动在流程中执行其操作。交互式执行 会暂停流程以获取输入。成功执行的执行将其状态设置为成功。要使流程完成，它至少需要一个状态为成功的执行。

您可以使用 添加子流程 按钮将子流程添加到顶层流程。添加子流程 按钮显示 创建执行流程 页面。此页面类似于 创建顶层表单 页面。区别在于 流程类型 可以是 basic（默认）或 form。form 类型构建一个为用户生成表单的子流程，类似于内置的 Registration 流程。子流程的成功取决于其执行的评估结果，包括其包含的子流程。有关子流程如何工作的深入解释，请参阅 执行要求部分。

流程中的所有元素在元素旁边都有一个 删除 选项。某些执行具有 ⚙️ 菜单项（齿轮图标）来配置执行。也可以使用 添加步骤 和 添加子流程 链接将执行和子流程添加到子流程。

由于执行顺序很重要，您可以通过拖动其名称来上下移动执行和子流程。

为了说明流程的创建，本节描述了创建高级浏览器登录流程。此流程的目的是允许用户选择使用 WebAuthn 以无密码方式登录，或使用密码和 OTP 进行双因素身份验证。

在此阶段，表单需要用户名，但不需要密码。我们必须启用密码身份验证以避免安全风险。

最后，更改绑定。

输入用户名后，流程的工作方式如下

如果用户已记录 WebAuthn 无密码凭据，他们可以直接使用这些凭据登录。这是无密码登录。用户也可以选择 Password with OTP，因为 WebAuthn Passwordless 执行和 Password with OTP 流程都设置为 备选。如果它们设置为 必需，则用户必须输入 WebAuthn、密码和 OTP。

如果用户选择带有 WebAuthn passwordless 身份验证的 尝试其他方式 链接，则用户可以在 Password 和 Passkey (WebAuthn 无密码) 之间进行选择。选择密码时，用户需要继续并使用分配的 OTP 登录。如果用户没有 WebAuthn 凭据，则用户必须输入密码，然后输入 OTP。如果用户没有 OTP 凭据，系统将要求他们记录一个。

客户端策略 可用于根据特定条件（例如请求特定范围或使用 AuthenticationFlowSelectorExecutor 的 ACR（身份验证上下文类引用）与您偏好的条件相结合）动态选择身份验证流程。

AuthenticationFlowSelectorExecutor 允许您选择适当的身份验证流程，并设置选定流程完成后要应用的身份验证级别。

一种可能的配置涉及使用 ACRCondition 与 AuthenticationFlowSelectorExecutor 结合使用。此设置使您能够根据请求的 ACR 选择身份验证流程，并将 ACR 值包含在使用 ACR 到 LoA 映射 的令牌中。

有关更多详细信息，请参阅 客户端策略。

本节描述了如何使用逐步提升机制创建高级浏览器登录流程。逐步提升身份验证的目的是允许基于用户的特定身份验证级别访问客户端或资源。

现在，您配置第一个身份验证级别的流程。

现在，您配置第二个身份验证级别的流程。

最后，更改绑定。

要使用逐步提升机制，您需要在身份验证请求中指定请求的身份验证级别 (LoA)。claims 参数用于此目的

claims 参数以 JSON 表示形式指定

Keycloak javascript 适配器支持轻松构建此 JSON 并在登录请求中发送它。有关更多详细信息，请参阅 securing apps 部分中的 Keycloak JavaScript adapter。

您还可以使用更简单的参数 acr_values 而不是 claims 参数来请求特定级别作为非必要项。这在 OIDC 规范中有所提及。

您还可以为特定客户端配置默认级别，当参数 acr_values 或带有 acr 声明的 claims 参数不存在时，将使用该默认级别。有关更多详细信息，请参阅客户端 ACR 配置）。

有关更多详细信息，请参阅官方 OIDC 规范。

流程逻辑

先前配置的身份验证流程的逻辑如下
如果客户端请求高身份验证级别，即身份验证级别 2 (LoA 2)，则用户必须执行完整的双因素身份验证：用户名/密码 + OTP。但是，如果用户已经在 Keycloak 中拥有会话，并且已使用用户名和密码（LoA 1）登录，则用户仅需提供第二个身份验证因素 (OTP)。

条件中的 Max Age 选项确定后续身份验证级别的有效时长（多少秒）。此设置有助于确定是否在后续身份验证期间再次要求用户出示身份验证因素。如果特定级别 X 由 claims 或 acr_values 参数请求，并且用户已经通过级别 X 身份验证，但该级别已过期（例如，最大年龄配置为 300 秒，用户在 310 秒之前进行了身份验证），则将要求用户使用该特定级别重新进行身份验证。但是，如果该级别尚未过期，则用户将被自动视为已通过该级别的身份验证。

将 Max Age 值设置为 0 意味着特定级别仅对本次身份验证有效。因此，每次请求该级别的重新身份验证都需要使用该级别再次进行身份验证。这对于应用程序中需要更高安全性的操作（例如，发送付款）并且始终需要使用特定级别进行身份验证的情况非常有用。

如果参数未显式请求级别，则 Keycloak 将要求使用身份验证流程中找到的第一个 LoA 条件进行身份验证，例如前面示例中的用户名/密码。当用户已经通过该级别身份验证并且该级别已过期时，用户不需要重新进行身份验证，但令牌中的 acr 值将为 0。此结果被视为仅基于 long-lived browser cookie 的身份验证，如 OIDC Core 1.0 规范的第 2 节中所述。

示例场景

令牌中的 ACR 声明

ACR 声明由在 acr 客户端范围中定义的 acr loa level 协议映射器添加到令牌中。此客户端范围是 realm 默认客户端范围，因此将添加到 realm 中所有新创建的客户端。

如果您不希望令牌内部包含 acr 声明，或者您需要一些自定义逻辑来添加它，您可以从客户端中删除客户端范围。

请注意，当登录请求发起一个使用 claims 参数请求 acr 作为 essential 声明的请求时，Keycloak 将始终返回指定的级别之一。如果它无法返回指定的级别之一（例如，如果请求的级别未知或大于身份验证流程中配置的条件），则 Keycloak 将抛出错误。

通常，当用户从客户端应用程序重定向到 Keycloak 时，会触发 browser 流程。如果 realm 注册已启用并且用户在登录屏幕上单击 Register，则此流程可能允许用户注册。此外，如果为 realm 启用了忘记密码，则用户可以单击登录屏幕上的 Forget password，这将触发 Reset credentials 流程，用户可以在电子邮件地址确认后重置凭据。

有时，客户端应用程序直接将用户重定向到 Registration 屏幕或 Reset credentials 流程可能很有用。结果操作将与用户在正常登录屏幕上单击 Register 或 Forget password 时的操作相匹配。可以按如下方式自动重定向到注册或重置凭据屏幕

设置 Kerberos 服务器的步骤取决于操作系统 (OS) 和 Kerberos 供应商。有关设置和配置 Kerberos 服务器的说明，请参阅 Windows Active Directory、MIT Kerberos 和您的操作系统文档。

在设置期间，执行以下步骤

然后，添加 HTTP 主体并使用如下命令将其密钥导出到 keytab 文件

确保 Keycloak 运行的主机可以访问 keytab 文件 /tmp/http.keytab。

在您的机器上安装 Kerberos 客户端。

客户端机器必须具有 Kerberos 客户端，并按照上述说明设置 krb5.conf。客户端机器还必须在其浏览器中启用 SPNEGO 登录支持。如果您正在使用 Firefox 浏览器，请参阅配置 Firefox 以使用 Kerberos。

.mydomain.org URI 必须在 network.negotiate-auth.trusted-uris 配置选项中。

在 Windows 域中，客户端无需调整其配置。Internet Explorer 和 Edge 已经可以参与 SPNEGO 身份验证。

Kerberos 支持凭据委派。应用程序可能需要访问 Kerberos 票证，以便它们可以重用它来与受 Kerberos 保护的其他服务进行交互。由于 Keycloak 服务器处理了 SPNEGO 协议，您必须在 OpenID Connect 令牌声明或 SAML 断言属性中将 GSS 凭据传播到您的应用程序。Keycloak 从 Keycloak 服务器将此传输到您的应用程序。要将此声明插入到令牌或断言中，每个应用程序都必须启用内置协议映射器 gss delegation credential。此映射器在应用程序客户端页面的映射器选项卡中可用。有关更多详细信息，请参阅协议映射器章节。

应用程序必须反序列化它从 Keycloak 接收的声明，然后才能使用它对其他服务进行 GSS 调用。当您从访问令牌反序列化凭据到 GSSCredential 对象时，请创建 GSSContext，并将此凭据传递给 GSSManager.createContext 方法。例如

在 Kerberos 协议中，realm 是一组 Kerberos 主体。这些主体的定义存在于 Kerberos 数据库中，该数据库通常是 LDAP 服务器。

Kerberos 协议允许跨 realm 信任。例如，如果存在 2 个 Kerberos realm A 和 B，则跨 realm 信任将允许 realm A 中的用户访问 realm B 的资源。Realm B 信任 realm A。

Keycloak 服务器支持跨 realm 信任。要实现此目的，请执行以下操作

查找用户基于 LDAP 存储提供程序选项 Kerberos principal attribute。例如，如果将其配置为 userPrincipalName 之类的值，则在用户 john@A 的 SPNEGO 身份验证之后，Keycloak 将尝试查找属性 userPrincipalName 等于 john@A 的 LDAP 用户。如果 Kerberos principal attribute 留空，则 Keycloak 将基于其 Kerberos 主体的前缀（省略 realm）查找 LDAP 用户。例如，Kerberos 主体用户 john@A 必须在 LDAP 中以用户名 john 可用，因此通常在 LDAP DN 下，例如 uid=john,ou=People,dc=example,dc=com。如果您希望 realm A 和 B 中的用户进行身份验证，请确保 LDAP 可以找到来自 realm A 和 B 的用户。

允许多个 Kerberos realm 中的用户进行身份验证，因为每个用户都将具有属性 KERBEROS_PRINCIPAL，该属性引用用于身份验证的 Kerberos 主体，并且这用于进一步查找此用户。为避免当 Kerberos realm A 和 B 中都有用户 john 时发生冲突，Keycloak 用户的用户名可能包含 Kerberos realm（小写）。例如，用户名将是 john@a。以防万一 realm 与配置的 Kerberos realm 匹配，realm 后缀可能会从生成的用户名中省略。例如，对于 Kerberos 主体 john@A，用户名将是 john，只要 Kerberos realm 在 Kerberos 提供程序上配置为 A 即可。

如果您遇到问题，请启用其他日志记录来调试问题