8.3. 身份验证流
身份验证流程 是在登录、注册和其他红帽构建的 Keycloak 工作流期间验证、屏幕和操作的容器。
8.3.1. 内置流
红帽构建的 Keycloak 有几个内置流。您无法修改这些流，但您可以更改流的要求以满足您的需要。
流程
- 点菜单中的 Authentication。
- 单击列表中的 Browser 项，以查看详细信息。
浏览器流
8.3.1.1. Auth 类型
身份验证的名称或要执行的操作。如果身份验证缩进，则它在子流中。它可能或不执行，具体取决于其父级的行为。
cookie
当用户成功登录时，红帽构建的 Keycloak 会设置一个会话 Cookie。如果已经设置了 Cookie，这个验证类型会成功。由于 Cookie 供应商返回成功，并且在这个流程级别上执行每个执行都是，因此红帽构建的 Keycloak 不会执行任何其他执行。这会导致成功登录。
Kerberos
默认情况下，此验证器被禁用，并在浏览器流中跳过。
身份提供程序 Redirector
此操作通过 Actions > Config 链接进行配置。它重定向到另一个用于 身份代理的 IdP。
表单
由于此子流标记为 替代方案，因此如果 Cookie 身份验证类型通过，则不会执行它。此子流包含需要执行的额外验证类型。红帽构建的 Keycloak 会加载这个子流的执行并处理它们。
第一次执行是 Username Password Form，它是一个呈现用户名和密码页面的身份验证类型。它标记为 必需的，因此用户必须输入有效的用户名和密码。
第二个执行是 Browser - Conditional OTP 子流。这个子流是 条件的，并根据 Condition - User Configured 执行的结果执行。如果结果为 true，红帽构建的 Keycloak 会加载这个子流的执行并处理它们。
下一个执行是 Condition - User Configured 身份验证。此身份验证检查红帽构建的 Keycloak 是否在用户流中配置了其他执行。Browser - Conditional OTP 子流仅在用户配置了 OTP 凭证时才执行。
最后的执行是 OTP Form。红帽构建的 Keycloak 将这个执行标记为 需要，但只有用户在因为 条件 子流中的设置而设置了 OTP 凭证时才运行。如果没有，用户不会看到 OTP 表单。
8.3.1.2. 要求
控制执行某个操作的一组单选按钮。
8.3.1.2.1. 必需
流中的所有 必需 元素都必须成功执行。如果一个必需的元素失败，则流会终止。
8.3.1.2.2. 替代方案
只有单个元素必须成功执行，才能评估流成功。因为 Required 流元素足以将流标记为成功，所以包含 Required 流元素的 Alternative 流元素将无法执行。
8.3.1.2.3. Disabled
元素不计算将流标记为成功。
8.3.1.2.4. 条件
这个要求类型只在子流中设置。
- 条件 子流包含执行。这些执行必须评估逻辑语句。
- 如果所有执行都评估为 true，则 Conditional 子流将充当 Required。
- 如果有任何执行评估为 false，则 Conditional 子流将充当 Disabled。
- 如果没有设置执行，Conditional 子流充当 Disabled。
- 如果流包含执行，且流没有设置为 Conditional，则红帽构建的 Keycloak 不会评估执行，执行被视为功能 禁用。
8.3.2. 创建流
在设计流时，会应用重要的功能和安全注意事项。
要创建流，请执行以下操作：
流程
- 点菜单中的 Authentication。
- 点 Create flow。
您可以复制并修改现有流。单击"Action list" （行末尾的三个点），单击 Duplicate，然后为新流输入一个名称。
在创建新流时，您必须首先使用以下选项创建一个顶层流：
- Name
- 流的名称。
- 描述
- 您可以设置为流的描述。
- 顶级流类型
- 流的类型。类型 客户端仅用于客户端 （应用程序）的身份验证。对于所有其他情况，请选择 基本。
创建顶层流
当红帽构建的 Keycloak 创建流时，Red Hat build of Keycloak 会显示 Add step, 和 Add sub-flow 按钮。
一个空新流
三个因素决定了流和子流的行为。
- 流和子流的结构。
- 流中的执行
- 子流和执行中设置的要求。
执行具有各种操作，从发送重置电子邮件以验证 OTP。使用 Add step 按钮添加执行。
添加身份验证执行
身份验证执行可以选择性地配置引用值。这可供 身份验证方法参考(AMR) 协议映射器用于填充 OIDC 访问和 ID 令牌（有关 AMR 声明的更多信息，请参阅 RFC-8176）。当为客户端配置了 身份验证方法引用(AMR) 协议映射器时，它将使用用户在身份验证流中成功完成的任何验证器的参考值填充 amr 声明。
添加验证器引用值
存在两种类型的执行，自动执行 和交互式执行 。Automatic executions 与 Cookie 执行类似，并将在流中自动执行操作。交互式执行将暂停流以获取输入。执行操作成功将其状态设置为 success。要完成流，至少需要一个 成功状态 的执行。
您可以使用 Add sub-flow 按钮将子流添加到顶层流中。Add sub-flow 按钮显示 Create Execution Flow 页面。此页面与 Create Top Level Form 页面类似。区别在于 Flow Type 可以是 basic （默认）或 表单。表单 类型构建了一个子流，它为用户生成表单，类似于内置的 注册流程。子流成功取决于它们的执行评估，包括其包含子流。有关子流的工作方式的信息，请参阅执行要求部分。???
添加执行后，检查要求是否有正确的值。
流中的所有元素在元素旁边都有一个 Delete 选项。有些执行有一个 HBAC 菜单项（齿轮图标）来配置执行。也可以使用 Add 步骤和 Add sub-flow 链接将执行和子流 添加到子流中。
由于执行顺序很重要，因此您可以通过拖动名称来移动执行和子流。
在配置身份验证流时，请确保正确测试您的配置，以确认设置中没有安全漏洞。我们建议您测试各种基本情况。例如，在身份验证前从用户帐户中删除各种凭证时，请考虑测试用户的身份验证行为。
例如，当 2nd-factor authenticators （如 OTP Form 或 WebAuthn Authenticator）被配置为 REQUIRED，且用户没有特定类型的凭证，用户可以在身份验证本身中设置特定的凭证。这种情况意味着，在身份验证过程中，用户不会与此凭证进行身份验证。因此，对于浏览器身份验证，请确保使用一些第一因素凭证（如 Password 或 WebAuthn Passwordless Authenticator）配置身份验证流。
8.3.3. 创建无密码浏览器登录流
为了说明流程的创建，本节描述了创建高级浏览器登录流程。此流的目的是允许用户使用 WebAuthn 的无密码方式登录，或使用密码和 OTP 进行双因素身份验证。
流程
- 点菜单中的 Authentication。
- 点 Flows 选项卡。
- 点 Create flow。
-
输入
Browser Password-less作为名称。 - 点 Create。
- 点 Add execution。
- 从列表中选择 Cookie。
- 点击 Add。
- 为 Cookie 验证类型选择 Alternative，以将其要求设置为替代。
- 点 Add step。
- 从列表中选择 Kerberos。
- 点击 Add。
- 点 Add step。
- 从列表中选择 Identity Provider Redirector。
- 点击 Add。
- 为 Identity Provider Redirector 身份验证类型选择 Alternative 来将其要求设置为替代。
- 点 Add sub-flow。
- 输入 Forms 作为名称。
- 点击 Add。
为 Forms 验证类型选择 Alternative，以将其要求设置为替代。
浏览器流的常见部分
- 点 Forms 执行的 + 菜单。
- 选择 Add step。
- 从列表中选择 Username Form。
- 点击 Add。
在这个阶段，表单需要一个用户名，但没有密码。我们必须启用密码身份验证以避免安全风险。
- 点 Forms 子流的 + 菜单。
- 点 Add sub-flow。
-
输入
Authentication作为名称。 - 点击 Add。
- 选择 Authentication authentication type 是必需的，以设置其要求。
- 点 Authentication 子流的 + 菜单。
- 点 Add step。
- 从列表中选择 WebAuthn Passwordless Authenticator。
- 点击 Add。
- 为 Webauthn Passwordless Authenticator 身份验证类型选择替代方案，以将其要求设置为替代。
- 点 Authentication 子流的 + 菜单。
- 点 Add sub-flow。
-
输入
Password with OTP作为名称。 - 点击 Add。
- 选择 Alternative for the Password with OTP authentication type，将其要求设置为替代。
- 点 带有 OTP 子流的 Password 的 + 菜单。
- 点 Add step。
- 从列表中选择 Password Form。
- 点击 Add。
- 选择 Password Form authentication type 是必需的，以将其要求设置为 required。
- 点 带有 OTP 子流的 Password 的 + 菜单。
- 点 Add step。
- 从列表中选择 OTP Form。
- 点击 Add。
- 点 OTP Form 身份验证类型的 Required，将其要求设置为 required。
最后，更改绑定。
- 单击屏幕顶部的 Action 菜单。
- 从菜单中选择 绑定流。
- 点 Browser Flow 下拉列表。
- 点击 Save。
无密码浏览器登录
输入用户名后，流可以正常工作：
如果用户记录了 WebAuthn 免密码凭据，他们可以使用这些凭证直接登录。这是免密码登录。用户也可以选择 Password with OTP，因为 WebAuthn Passwordless 执行和 Password with OTP 流被设置为 Alternative。如果它们被设置为 Required，用户必须输入 WebAuthn、password 和 OTP。
如果用户使用 WebAuthn 免密码身份验证 选择 Try 另一个 链接，用户可以在 Password 和 Passkey (WebAuthn password)之间进行选择。在选择密码时，用户需要继续并使用分配的 OTP 登录。如果用户没有 WebAuthn 凭据，用户必须输入密码，然后是 OTP。如果用户没有 OTP 凭证，则会要求记录一个凭证。
因为 WebAuthn Passwordless 执行被设置为 Alternative 而不是 Required，因此这个流永远不会要求用户注册 WebAuthn 凭证。要使用户具有 Webauthn 凭证，管理员必须为用户添加必要的操作。通过以下方法进行此操作：
创建高级流（如），这可能会产生副作用。例如，如果您启用了为用户重置密码的功能，则可以从密码表单访问。在默认的 Reset Credentials 流中，用户必须输入其用户名。由于用户已在 浏览器无密码 流中输入了用户名，因此对于用户体验，这个操作对于红帽构建的 Keycloak 和子优化是不需要的。要更正这个问题，您可以：
-
复制
重置凭据流。将其名称设置为无密码的重置凭据，例如： - 单击 Choose user 步骤的 Delete (trash icon)。
- 在 Action 菜单中，选择 Bind flow，然后从下拉菜单中选择 Reset credentials flow，然后单击 Save
8.3.4. 使用步骤机制创建浏览器登录流程
本节论述了如何使用步骤机制创建高级浏览器登录流。步骤身份验证的目的是允许根据用户的特定身份验证级别访问客户端或资源。
流程
- 点菜单中的 Authentication。
- 点 Flows 选项卡。
- 点 Create flow。
-
输入
Browser Incl Step up Mechanism作为名称。 - 点击 Save。
- 点 Add execution。
- 从列表中选择 Cookie。
- 点击 Add。
- 为 Cookie 验证类型选择 Alternative，以将其要求设置为替代。
- 点 Add sub-flow。
- 输入 Auth Flow 作为名称。
- 点击 Add。
- 点 Alternative，Auth Flow 验证类型将它的 requirement 设置为 alternative。
现在，您可以为第一个身份验证级别配置流。
- 点 Auth Flow 的 + 菜单。
- 点 Add sub-flow。
-
输入
1st Condition Flow作为名称。 - 点击 Add。
- 点 1st Condition Flow 验证类型的 Conditional 将要求设置为条件。
- 点 1st Condition Flow 的 + 菜单。
- 单击 Add condition。
- 从列表中选择 Conditional - Level Of Authentication。
- 点击 Add。
- 点 Conditional - Level Of Authentication authentication type 来将其要求设置为 required。
- 点 iwl iwl (gear 图标)。
-
输入
Level 1作为别名。 -
在验证级别(LoA)输入
1。 -
将 Max Age 设置为 36000。这个值以秒为单位，相当于 10 小时，这是在 realm 中设置的默认
SSO Session Max超时。因此，当用户使用此级别进行身份验证时，后续的 SSO 登录可以重新使用这个级别，用户不需要在用户会话结束前与这个级别进行身份验证，默认为 10 小时。 点 Save
为第一个身份验证级别配置条件
- 点 1st Condition Flow 的 + 菜单。
- 点 Add step。
- 从列表中选择 Username Password Form。
- 点击 Add。
现在，您可以为第二个身份验证级别配置流。
- 点 Auth Flow 的 + 菜单。
- 点 Add sub-flow。
-
输入
2nd Condition Flow作为一个别名。 - 点击 Add。
- 点 2nd Condition Flow 验证类型的 Conditional 将要求设置为条件。
- 点 2nd Condition Flow 的 + 菜单。
- 单击 Add condition。
- 从项目列表中选择 Conditional - Level Of Authentication。
- 点击 Add。
- 点 Conditional - Level Of Authentication authentication type 来将其要求设置为 required。
- 点 iwl iwl (gear 图标)。
-
输入
Level 2作为别名。 -
在验证级别(LoA)输入
2。 - 将 Max Age 设置为 0。因此，当用户进行身份验证时，这个级别仅对当前身份验证有效，但不对后续任何 SSO 身份验证有效。因此，在请求此级别时，用户始终需要再次使用此级别进行身份验证。
点 Save
为第二个身份验证级别配置条件
- 点 2nd Condition Flow 的 + 菜单。
- 点 Add step。
- 从列表中选择 OTP Form。
- 点击 Add。
- 点 OTP Form 身份验证类型的 Required，将其要求设置为 required。
最后，更改绑定。
- 单击屏幕顶部的 Action 菜单。
- 从列表中选择 Bind flow。
- 从下拉菜单中选择 浏览器流。
- 点击 Save。
使用 step-up 机制的浏览器登录
请求特定的身份验证级别
要使用 步骤机制，您可以在身份验证请求中指定请求的身份验证(LoA)级别。claim 参数用于此目的：
https://{DOMAIN}/realms/{REALMNAME}/protocol/openid-connect/auth?client_id={CLIENT-ID}&redirect_uri={REDIRECT-URI}&scope=openid&response_type=code&response_mode=query&nonce=exg16fxdjcu&claims=%7B%22id_token%22%3A%7B%22acr%22%3A%7B%22essential%22%3Atrue%2C%22values%22%3A%5B%22gold%22%5D%7D%7D%7D
claims 参数以 JSON 指定：
claims= {
"id_token": {
"acr": {
"essential": true,
"values": ["gold"]
}
}
}红帽构建的 Keycloak javascript 适配器支持轻松构建此 JSON 并在登录请求中发送它。如需了解更多详细信息，请参阅 Javascript 适配器文档。
您还可以使用 simpler 参数 acr_values 而不是 claims 参数来请求特定级别，作为非essential。这在 OIDC 规格中提到。
您还可以为特定客户端配置默认级别，当参数 acr_values 或带有 acr 声明 的参数声明不存在时使用。如需了解更多详细信息，请参阅 客户端 ACR 配置。
要请求 acr_values 作为文本（如 金级）而不是数字值，您可以在 ACR 和 LoA 之间配置映射。可以在域级别（推荐）或客户端级别进行配置。有关配置，请参阅 ACR 到 LoA 映射。
如需了解更多详细信息，请参阅官方 OIDC 规格。
流逻辑
上述配置的身份验证流程的逻辑如下：
如果客户端需要高的身份验证级别，即身份验证 2 级别(LoA 2)，用户必须执行完整的双因素身份验证：Username/Password + OTP。但是，如果用户已在红帽构建的 Keycloak 中已有会话，该会话已使用用户名和密码(LoA 1)登录，则用户只要求提供第二个身份验证因素(OTP)。
该条件中的选项 Max Age 决定后续身份验证级别有效的时长（以秒为单位）。此设置有助于确定用户是否在后续身份验证中再次显示身份验证因素。如果 声明 或 cr_values 参数请求了特定的级别 X，并且已使用级别 X 进行身份验证，但它已过期（例如，max age 被配置为 300，在 310 秒之前验证用户），则会要求用户再次与特定级别重新进行身份验证。但是，如果级别尚未过期，该用户将自动被视为使用该级别进行身份验证。
使用 Max Age 的值为 0 表示，该特定级别只针对这个单一身份验证有效。因此，要求该级别的每个重新身份验证都需要使用该级别再次进行身份验证。这对需要应用中安全性（如发送付款）且始终要求使用特定级别进行身份验证的操作很有用。
请注意，当通过用户浏览器将登录请求从客户端发送到 Keycloak 的红帽构建时，URL 中的用户可能会更改 声明 或 cr_ value 等参数。如果客户端使用 PAR （推送的授权请求）、请求对象或其他阻止用户在 URL 中重写参数的机制，则可以缓解这种情况。因此，在身份验证后，建议客户端检查 ID Token 以仔细检查令牌中的 acr 是否与预期的级别对应。
如果参数没有请求显式级别，则红帽构建的 Keycloak 将需要使用身份验证流中找到的第一个 LoA 条件进行身份验证，如上例中的 Username/Password。当用户已使用该级别进行身份验证并且该级别已过期时，用户不需要重新进行身份验证，但令牌中的 cr 将具有值 0。结果被视为仅基于 长期浏览器 cookie 进行身份验证，如 OIDC Core 1.0 规格的第 2 节所述。
当管理员指定了多个流时，可能会出现冲突的情况，为每个流设置不同的 LoA 级别，并将流分配给不同的客户端。但是，该规则始终相同：如果用户有一定级别，则它只需要具有该级别来连接到客户端。管理员最多确保 LoA 一致。
示例情境
- 对于级别 1 条件，最大期限配置为 300 秒。
-
在不请求任何证书的情况下发送登录请求。将使用级别 1，用户需要使用用户名和密码进行身份验证。令牌将具有
acr=1。 -
另一个登录请求将在 100 秒后发送。由于 SSO，用户会自动进行身份验证，令牌将返回
acr=1。 -
另一登录请求在 201 秒后发出（自 2 中的身份验证后计算为 301 秒）由于 SSO，用户会自动进行身份验证，但令牌将返回
cr=0，因为级别 1 被视为过期。 -
发送另一个登录请求，但现在它会在
claims参数中明确请求 ACR 级别 1。用户将被要求重新使用用户名/密码进行身份验证，然后在令牌中返回acr=1。
令牌中的 ACR 声明
ACR 声明通过在 acr 客户端范围中定义的 acr loa level 协议映射程序添加到令牌中。此客户端范围是 realm 默认客户端范围，因此将添加到域中所有新创建的客户端。
如果您不希望令牌内部的 acr 声明或需要一些自定义逻辑来添加它，您可以从客户端中删除客户端范围。
请注意，当登录请求请求一个带有 claims 参数作为 基本 声明时，红帽构建的 Keycloak 将始终返回指定级别之一。如果无法返回指定级别中的一个（例如，如果请求的级别未知或大于身份验证流中配置的条件），则红帽构建的 Keycloak 将会抛出错误。
8.3.5. 客户端请求注册或重置凭证
通常，当用户从客户端应用程序重定向到 Keycloak 的红帽构建时，会触发 浏览器 流。如果启用了域 注册，则此流程可以允许用户注册，用户点击登录屏幕上的 Register。另外，如果为域启用了 Forget 密码，用户可以在登录屏幕上点 Forget 密码，这会触发 Reset credentials 流，用户可以在电子邮件地址确认后重置凭证。
有时，客户端应用程序直接重定向到 注册屏幕或重置 凭据 流会很有用。当用户在正常登录屏幕上点 Register 或 Forget 密码时，生成的操作将与 的操作匹配。自动重定向到注册或重置凭证屏幕，如下所示：
-
当客户端希望用户直接重定向到注册时，OIDC 客户端应将 OIDC 登录 URL 路径(
/auth)中的最后一个片断替换为/registrations。因此，完整 URL 可能类似如下：https://keycloak.example.com/realms/your_realm/protocol/openid-connect/registrations。 -
当客户端希望用户直接重定向到
Reset 凭证流时，OIDC 客户端应使用替换 OIDC 登录 URL 路径(/forgot-credentials/auth)中的最后一个片断。
前面的步骤是客户端唯一支持的方法来直接请求注册或重置凭证流。为了安全起见，不支持它，推荐客户端应用程序绕过 OIDC/SAML 流，并直接重定向到其他红帽构建的 Keycloak 端点（如 /realms/realm_name/login-actions 或 /realms/realm_name/broker）。
