8.7. W3C Web 身份验证(WebAuthn)


Red Hat build of Keycloak 支持 W3C Web Authentication (WebAuthn)。红帽 Keycloak 的构建作为 WebAuthn 的 Relying Party (RP) 工作。

注意

Webauthn 的操作成功取决于用户的 WebAuthn 支持验证器、浏览器和平台。确保您的验证器、浏览器和平台支持 WebAuthn 规格。

注意

webauthn 的规格使用 user.id 将公钥凭证映射到 Relying Party 中的特定用户帐户。此用户 ID 句柄是不透明字节序列,最大大小为 64 字节。红帽构建的 Keycloak 将内部数据库 ID 传递给注册,在常见用户中是 36 个字符的 UUID。但是,如果用户来自外部用户联邦供应商,则红帽 Keycloak ID 的内部红帽构建是 存储 ID,格式为 f:<provider-id>:<user-id&gt;,它可能会超过 64 字节限制。在合并存储 SPI 和 WebAuthn 时,请考虑到这一点,并将短 ID 用于联邦供应商组件,以及来自该供应商的用户。

8.7.1. 设置

对 2FA 的 WebAuthn 支持的设置过程如下:

8.7.1.1. 启用 WebAuthn authenticator 注册

  1. 点菜单中的 Authentication
  2. Required Actions 选项卡。
  3. Webauthn Register 开关切换为 ON

如果您希望所有新用户都要注册其 WebAuthn 凭据,请将 Default Action 开关切换为 ON

8.7.2. 将 WebAuthn 身份验证添加到浏览器流中

  1. 点菜单中的 Authentication
  2. 单击 浏览器 流。
  3. 从 "Action 列表中选择 Duplicate,以制作内置 浏览器 流的副本。
  4. 输入 "WebAuthn Browser" 作为副本的名称。
  5. Duplicate
  6. 点名称进入详情
  7. 单击"WebAuthn Browser Browser - Conditional OTP"的垃圾箱图标 均图标",然后单击" 删除 "。

如果您需要所有用户的 WebAuthn:

  1. 单击 WebAuthn Browser Forms+ 菜单。
  2. 单击添加步骤
  3. 单击 WebAuthn Authenticator
  4. 点击 Add
  5. WebAuthn Authenticator 身份验证类型选择 Required,以将其要求设置为 required。

    Webauthn browser flow required

  6. 单击屏幕顶部的 Action 菜单。
  7. 从下拉列表中选择 Bind flow
  8. 从下拉列表中选择 Browser
  9. 点击 Save
注意

如果用户没有 WebAuthn 凭据,用户必须注册 WebAuthn 凭据。

如果用户只注册了 WebAuthn 凭据,用户可以使用 WebAuthn 登录。因此,除了添加 WebAuthn Authenticator 执行外,您可以:

流程

  1. 单击 WebAuthn Browser Forms 行的 + 菜单。
  2. 单击 Add sub-flow
  3. name 字段中输入 "Conditional 2FA"。
  4. Conditional 2FA 选择 Conditional 以将其要求设置为 conditional。
  5. Conditional 2FA 行中,点加号 + 并选择 Add condition
  6. 单击 Add condition
  7. 选择 Condition - User Configured
  8. 点击 Add
  9. Condition - User Configured 选择 Required 来将其要求设置为 required。
  10. WebAuthn Authenticator 拖放到 Conditional 2FA
  11. WebAuthn Authenticator 选择 alternatives,以将其要求设置为替代方法。

    Webauthn browser flow conditional

用户可以选择使用 WebAuthn 和 OTP 作为第二个因素:

流程

  1. Conditional 2FA 行中,单击加号 +,然后选择 Add step
  2. 从列表中选择 OTP Form
  3. 点击 Add
  4. OTP Form 选择 alternatives 以将其要求设置为替代。

    WebAuthn browser flow conditional with OTP

8.7.3. 使用 WebAuthn authenticator 进行身份验证

注册 WebAuthn 验证器后,用户执行以下操作:

  • 打开登录表单。用户必须使用用户名和密码进行身份验证。
  • 用户的浏览器使用其 WebAuthn 验证器要求用户进行身份验证。

8.7.4. 以管理员身份管理 WebAuthn

8.7.4.1. 管理凭证

与来自用户凭证管理的其他凭证类似,Red Hat build of Keycloak 管理 WebAuthn 凭证

  • Red Hat build of Keycloak 为用户分配一个从 Reset Actions 列表中创建 WebAuthn 凭证所需的操作,然后选择 Webauthn Register
  • 管理员可以点删除来删除 WebAuthn 凭据。
  • 管理员可以通过选择 Show data…​ 来查看凭据的数据,如 AAGUID。
  • 管理员可以通过在 User Label 字段中设置值并保存数据来为凭证设置标签。

8.7.4.2. 管理策略

管理员可以将 WebAuthn 相关操作配置为每个域的 WebAuthn Policy

流程

  1. 点菜单中的 Authentication
  2. Policy 选项卡。
  3. 单击 WebAuthn Policy 选项卡。
  4. 在策略中配置项目(请参阅以下描述)。
  5. Save

可配置的项目及其描述如下:

Expand
Configuration描述

依赖实体名称

可读的服务器名称作为 WebAuthn Relying Party。此项目是强制的,适用于 WebAuthn authenticator 注册。默认设置为 "keycloak"。如需了解更多详细信息,请参阅 WebAuthn 规格

签名算法

算法告诉 WebAuthn 验证器用于 公钥 凭据的签名算法。Red Hat build of Keycloak 使用公钥凭据来签名和验证 身份验证断言。如果没有算法,则默认调整 ES256RS256。ES256 和 RS256 是应用到 WebAuthn 验证器注册的可选配置项。如需了解更多详细信息,请参阅 WebAuthn 规格

依赖 ID

WebAuthn Relying Party 的 ID,用于决定 公钥凭据 的范围。ID 必须是原始的有效域。此 ID 是应用于 WebAuthn authenticators 注册的可选配置项。如果此条目为空,红帽构建的 Keycloak 会调整红帽构建的 Keycloak 基本 URL 的主机部分。如需了解更多详细信息,请参阅 WebAuthn 规格

attestation Conveyance Preference

浏览器上的 WebAuthn API 实施(WebAuthn Client)是生成 Attestation 语句的首选方法。这个首选项是一个可选配置项,适用于 WebAuthn authenticator 注册。如果不存在选项,则其行为与选择"none"相同。如需了解更多详细信息,请参阅 WebAuthn 规格

验证器附加

WebAuthn 客户端的 WebAuthn 验证器可接受的附加模式。这个模式是一个可选配置项,适用于 WebAuthn authenticator 注册。如需了解更多详细信息,请参阅 WebAuthn 规格

需要可发现的凭证

要求 WebAuthn 验证器生成公钥凭据作为客户端 发现的凭据的选项。这个选项适用于 WebAuthn authenticator 注册。如果留空,则其行为与选择"No"相同。如需了解更多详细信息,请参阅 WebAuthn 规格

用户验证要求

要求 WebAuthn 验证器的选项确认用户的验证。这是一个可选配置项,适用于 WebAuthn authenticator 注册,以及 WebAuthn 验证器用户身份验证。如果不存在选项,其行为与选择"首选"相同。如需了解更多详细信息,请参阅 WebAuthn 规范(注册 WebAuthn authenticator )和 WebAuthn 规范(用于通过 WebAuthn authenticator 验证用户)。

Timeout(超时)

注册 WebAuthn 验证器的超时值(以秒为单位),并使用 WebAuthn 验证器验证用户。如果设置为零,则其行为取决于 WebAuthn 验证器的实现。默认值为 0。如需了解更多详细信息,请参阅 WebAuthn 规范(注册 WebAuthn authenticator )和 WebAuthn 规范(用于通过 WebAuthn authenticator 验证用户)。

避免同验证器注册

如果启用,红帽构建的 Keycloak 无法重新注册已注册的 WebAuthn 验证器。

可接受的 AAGUID

WebAuthn 验证器必须注册的 AAGUID 的白名单。

8.7.5. attestation 语句验证

注册 WebAuthn 验证器时,红帽构建的 Keycloak 验证由 WebAuthn 验证器生成的 attestation 语句的可信度。红帽构建的 Keycloak 需要信任导入到 信任存储中 的证书。

要省略此验证,请禁用此信任存储,或者将 WebAuthn 策略的配置项 "Attestation Conveyance Preference" 设置为 "none"。

8.7.6. 以用户身份管理 WebAuthn 凭证

8.7.6.1. 注册 WebAuthn 验证器

注册 WebAuthn 验证器的适当方法取决于用户是否已在红帽构建的 Keycloak 上注册了帐户。

8.7.6.2. 新用户

如果 WebAuthn Register required 操作在域中是 Default Action,则新用户必须在首次登录后设置 Passkey。

流程

  1. 打开登录表单。
  2. Register
  3. 在表单上填写项目。
  4. Register

成功注册后,浏览器会要求用户输入其 WebAuthn 验证器标签的文本。

8.7.6.3. 现有用户

如果根据示例所示设置 WebAuthn Authenticator,那么当现有用户尝试登录时,需要他们自动注册其 WebAuthn 验证器:

流程

  1. 打开登录表单。
  2. 在表单中输入项目。
  3. Save
  4. 单击 登录

注册成功后,用户的浏览器会要求用户输入其 WebAuthn 验证器标签的文本。

8.7.7. 免密码 WebAuthn 和 Two-Factor

Red Hat build of Keycloak 使用 WebAuthn 进行双因素身份验证,但您可以使用 WebAuthn 作为第一因素身份验证。在这种情况下,带有 无密码 WebAuthn 凭证的用户可以向红帽构建的 Keycloak 进行身份验证,而无需密码。Red Hat build of Keycloak 可以使用 WebAuthn 作为域上下文和单一身份验证流中的无密码和双因素身份验证机制。

管理员通常需要用户为 WebAuthn 免密码身份验证注册的 Passkeys 满足不同的要求。例如,Passkeys 可能要求用户使用 PIN 向 Passkey 进行身份验证,或者使用更强大的证书颁发机构进行测试。

因此,红帽构建的 Keycloak 允许管理员配置单独的 WebAuthn Passwordless 策略。需要 Webauthn Register Passwordless 操作类型为 WebAuthn Passwordless Authenticator 的单独 验证器。

8.7.7.1. 设置

设置 WebAuthn 免密码支持,如下所示:

  1. (如果还没有)注册 WebAuthn 免密码支持新的所需操作。使用 Enable WebAuthn Authenticator 注册 中所述的步骤。注册 Webauthn Register Passwordless 操作。
  2. 配置策略。您可以使用管理策略 中描述的步骤和 配置选项。WebAuthn Passwordless Policy 选项卡的 Admin Console 中执行配置。Passkey 的要求通常比双因素策略更加强大。例如,在配置无密码策略时,您可以将 User Verification Requirement 设置为 Required
  3. 配置身份验证流。使用 WebAuthn Browser 流,如 Adding WebAuthn Authentication to a Browser Flow 所述。配置流,如下所示:

    • WebAuthn Browser Forms 子流包含 Username Form 作为第一个验证器。删除默认的 Username Password Form authenticator,并添加 Username Form authenticator。此操作要求用户提供用户名作为第一步。
    • 将有一个所需的子流,它可以被命名为 Passwordless Or Two-factor,例如:此子流表示用户可以使用 Passwordless WebAuthn 凭证或双因素身份验证进行身份验证。
    • 流包含 WebAuthn Passwordless Authenticator 作为第一个替代方法。
    • 第二个替代方案将是名为 Password 和 Two-factor Webauthn 的子流,例如:此子流包含 Password FormWebAuthn Authenticator

流的最终配置类似如下:

免密码流

PasswordLess flow

现在,您可以向用户添加 WebAuthn Register Passwordless 作为用户(由红帽构建的 Keycloak 已知的)来测试这一点。在第一个身份验证过程中,用户必须使用密码和 second-factor WebAuthn 凭据。如果使用 WebAuthn Passwordless 凭证,用户不需要提供密码和第二因素 WebAuthn 凭据。

8.7.8. LoginLess WebAuthn

Red Hat build of Keycloak 使用 WebAuthn 进行双因素身份验证,但您可以使用 WebAuthn 作为第一因素身份验证。在这种情况下,具有 无密码 WebAuthn 凭证的用户可以在红帽构建的 Keycloak 中进行身份验证,而无需提交登录或密码。Red Hat build of Keycloak 可以在域上下文中同时使用 WebAuthn 作为无登录/密码和双因素验证机制。

管理员通常需要用户为 WebAuthn 登录免密码身份验证注册 Passkeys 满足不同的要求。无登录身份验证需要用户对 Passkey 进行身份验证(例如,使用 PIN 代码或指纹),并且与无登录凭证关联的加密密钥实际上存储在 Passkey 中。并非所有 Passkeys 均符合这些要求。如果您的设备支持"用户验证"和"可发现的凭证",请检查您的 Passkey 供应商。请参阅支持的 Passkeys

红帽构建的 Keycloak 允许管理员以无登录身份验证的方式配置 WebAuthn Passwordless Policy。请注意,无登录身份验证只能使用 WebAuthn Passwordless Policy 配置,并且具有 WebAuthn Passwordless 凭证。Webauthn loginless 身份验证和 WebAuthn 免密码身份验证可以在同一域中配置,但将共享相同的策略 WebAuthn Passwordless Policy

8.7.8.1. 设置

流程

设置 WebAuthn Loginless 支持,如下所示:

  1. (如果还没有)注册 WebAuthn 免密码支持新的所需操作。使用 Enable WebAuthn Authenticator 注册 中所述的步骤。注册 Webauthn Register Passwordless 操作。
  2. 配置 WebAuthn 无密码策略。在 Admin Console, Authentication 部分中执行配置,在 Policies WebAuthn Passwordless Policy 中。当您为无登录情况配置策略时,您必须将 User Verification Requirement 设置为 required,并将 Require Discoverable Credential 设置为 Yes。请注意,由于没有专用的登录策略,因此无法使用用户 verification=no/discoverable credential=no 和无登录场景(用户验证=是/发现的凭证=yes)混合身份验证场景。存储容量通常非常受 Passkeys 限制,这意味着您无法在 Passkey 上存储多个可发现的凭证。
  3. 配置身份验证流。创建新的身份验证流,添加 "WebAuthn Passwordless" 执行,并将执行的 Requirement 设置设置为 Required

流的最终配置类似如下:

LoginLess 流

LoginLess flow

现在,您可以在用户(Red Hat build of Keycloak)中添加所需的操作 WebAuthn Register Passwordless 来测试这一点。配置所需操作的用户将必须进行身份验证(例如,用户名/密码),然后提示您注册用于无登录身份验证的 Passkey。

8.7.8.2. 特定于供应商的标记

8.7.8.2.1. 兼容性检查列表

使用红帽构建的 Keycloak 登录身份验证需要 Passkey 来满足以下功能

  • FIDO2 合规性:不与 FIDO/U2F 混淆
  • 用户验证:通过 Passkey 验证用户的能力(导致某人发现您的 Passkey 能够无密码验证登录和无密码)
  • 可发现的凭证: Passkey 存储与客户端应用程序关联的登录和加密密钥的功能
8.7.8.2.2. Windows Hello

要使用基于 Windows Hello 的凭证与红帽构建的 Keycloak 进行身份验证,请配置 WebAuthn Passwordless PolicySignature Algorithms 设置,使其包含 RS256 值。请注意,有些浏览器不允许访问私有窗口中的平台密码密钥(如 Windows Hello)。

8.7.8.2.3. 支持的 Passkeys

以下 Passkeys 已被成功测试,以便使用红帽构建的 Keycloak 进行登录身份验证:

  • Windows Hello (Windows 10 21H1/21H2)
  • yubico Yubikey 5 NFC
  • Feitian ePass FIDO-NFC
返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务,以及可以信赖的内容,帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情,请参阅红帽博客.

關於紅帽

我们提供强化的解决方案,使企业能够更轻松地跨平台和环境(从核心数据中心到网络边缘)工作。

Theme

© 2025 Red Hat