服务器管理指南

每个UI屏幕都在Keycloak中国际化。 默认语言是英语，但是如果您打开 国际化打开主题选项卡您可以选择要支持的语言环境以及默认语言环境 会的。 下次用户登录时，他们将能够在登录页面上选择一种语言用于登录屏幕， 用户帐户管理UI和管理控制台。 的服务器开发指南解释 如何提供其他语言。 主题提供的所有国际化文本都可以覆盖 通过特定领域的文本本地化tab。

如果用户没有密码，或者密码已被删除，则设置密码部分将显示在页面上。

要为用户创建密码，请键入新密码。 点击设置密码输入所有内容后的按钮。 如果临时开关打开，这个新密码只能使用一次，用户将被要求在密码打开后更改密码 登录。

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

或者，如果你有电子邮件设置后，您可以向询问的用户发送电子邮件 他们重置密码。 选择更新密码从重置动作列表框并单击发送电子邮件。 你可以选择 设置默认为预设的电子邮件链接的有效性令牌领域设置中的选项卡。 发送的电子邮件包含一个链接，该链接将使用户进入更新密码屏幕。

请注意，用户只能拥有密码类型的单个凭据。

您无法在管理控制台中为特定用户配置其他类型的凭据。 这是用户的责任。 您只能删除用户的凭据凭据选项卡，例如，如果用户丢失了OTP设备，或者如果凭据 已经妥协了。

您还可以指定所需的操作，这些操作将在创建新用户时添加到帐户中，即通过添加用户按钮用户 列表屏幕，或通过用户注册登录页面上的链接。 要指定 默认的必需操作转到身份验证左侧菜单项，然后单击所需的操作tab。

只需单击中的复选框默认操作全新用户登录时要执行的必需操作列。

许多组织都要求新用户首次登录时，他们需要同意条款和条件 网站的。 Keycloak将此功能作为必需的操作实现，但需要进行一些配置。 一方面，你 必须去所需的操作前面描述的选项卡，并启用条款和条件行动。 您还必须编辑 条款。ftl文件中的基地登录主题。 请参阅服务器开发指南有关扩展和扩展的更多信息 创造主题。

为了防止机器人注册，Keycloak已与Google reCAPTCHA集成。 要启用此功能，您需要首先转到谷歌Recaptcha网站 并创建一个API密钥，以便您可以获取reCAPTCHA站点密钥和秘密。 (仅供参考，默认情况下localhost可以工作，因此您不必指定域)。

接下来，您需要在Keycloak管理控制台中执行一些步骤。 单击身份验证左侧菜单项并转到流动tab。 选择注册从下拉菜单中流出 在此页面上列出。

将 “recaptcha” 要求设置为必需通过单击适当的单选按钮。 这将使 屏幕上的reCAPTCHA。 接下来，您必须输入在Google reCAPTCHA网站上生成的reCAPTCHA网站密钥和机密。 单击reCAPTCHA流条目右侧的 “操作” 按钮，然后单击 “Config” 链接，然后在此配置页面上输入reCAPTCHA站点密钥和秘密。

您要做的最后一步是更改Keycloak设置的一些默认HTTP响应头。 Keycloak 将阻止网站在iframe中包含任何登录页面。 这是为了防止点击劫持攻击。 你需要 授权Google在iframe内使用注册页面。 去 的领域设置左侧菜单项，然后转到安全防御tab。 您需要添加https://www.google.com到 两者的值X-框架-选项和内容安全策略标题。

执行此操作后，reCAPTCHA应该会显示在您的注册页面上。 您可能想要编辑注册。ftl在您的登录中 主题与reCAPTCHA按钮的位置和样式有关。 请参阅服务器开发指南 有关扩展和创建主题的更多信息。

除了启用声明 _ 用户 _ 配置文件功能，您应该为领域启用用户配置文件。 为此，请单击领域设置链接在 左侧菜单并打开启用用户配置文件开关。

启用它并单击保存按钮，您可以访问用户配置文件选项卡，您可以从其中管理用户属性的配置。

通过启用领域的用户配置文件，Keycloak将对基于用户配置文件配置的属性管理方式施加其他约束。 总而言之，以下是启用该功能时应期望的列表:

在接下来的主题中，我们将探索如何管理用户配置文件配置以及它如何影响您的领域。

用户配置文件配置是在每个领域的基础上管理的。 为此，点击 领域设置左侧菜单上的链接，然后单击用户配置文件tab。

在属性子选项卡您具有当前与用户配置文件关联的属性列表。 默认情况下，配置是根据用户根属性创建的，并且每个属性在验证和许可方面都配置了一些默认值。

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

在JSON编辑器子选项卡您可以使用定义明确的JSON架构查看和编辑配置。 在任何其他选项卡上进行的任何更改都将反映在此选项卡上显示的JSON配置中。

在下一节中，您将学习如何从属性子选项卡。

在属性子选项卡您可以创建、编辑和删除与用户配置文件关联的属性。

要定义新属性并将其与用户配置文件相关联，请单击创建属性列表右上角的按钮。

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

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

要创建新组，请单击创建属性组列表右上角的按钮。

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

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

JSON模式定义如下:

该架构支持您需要的任意多个属性。

对于每个属性，您应该定义一个名称还有，可选地，必需,权限,以及注释设置。

用户配置文件的主要功能之一是可以基于属性元数据动态呈现面向用户的表单。 将功能启用到您的领域后，将使用特定主题模板呈现诸如注册和更新配置文件之类的表单，以基于用户配置文件配置动态呈现页面。

也就是说，如果默认渲染机制满足您的需求，则根本不需要自定义模板。 如果您仍然需要对主题进行自定义，请查看以下模板:

默认渲染机制提供以下功能:

为了确保用户配置文件符合配置，管理员可以使用验证简介最终强制用户在对Keycloak进行身份验证时更新其配置文件所需的操作。

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

默认情况下，验证简介动作被禁用。 要启用它，请单击 身份验证左侧菜单上的链接，然后单击所需的操作tab。 在此选项卡上，单击注册按钮并选择验证简介行动。

在将用户配置文件功能启用到某个领域之前，您应该注意一些重要的注意事项。 通过提供单个位置来管理属性元数据，该功能对可以设置给用户的属性以及如何管理这些属性非常严格。

在用户管理方面，管理员只能管理用户配置文件配置中定义的属性。 设置为用户且尚未在用户配置文件配置中定义的任何其他属性将无法访问。 建议使用要向用户或管理员公开的所有用户属性来更新用户配置文件配置。

同样的建议适用于那些访问用户REST API来查询用户信息的人。

关于Keycloak内部用户属性，例如LDAP_ID,LDAP_ENTRY_DN,或者Kerberos _ 校长,如果您希望能够访问这些属性，则应将它们作为用户配置文件配置中的属性。 建议将这些属性标记为仅对管理员可见，以便在通过管理控制台管理用户属性或通过用户API查询用户时可以查看它们。

关于主题，如果您已经对传统模板 (使用用户根属性进行硬编码的模板) 进行了自定义，则在呈现面向用户的表单时不会使用自定义模板，而是动态呈现这些表单的新模板。 理想情况下，您应该避免对模板进行任何自定义，并尝试坚持这些新模板提供的行为，以便为您动态呈现表单。 如果它们仍然不足以满足您的要求，您可以自定义它们，也可以向我们提供任何反馈，以便我们讨论增强新模板是否有意义。

以下是每种策略类型的解释:

您的OTP发生器有两种不同的算法可供选择。 基于时间 (TOTP) 和基于计数器 (HOTP)。 对于TOTP，您的令牌生成器将散列当前时间和共享秘密。 服务器通过比较验证OTP 在提交的值的一定时间窗口内的所有哈希值。 因此，TOTPs仅在很短的时间窗口 (通常为30秒) 内有效。 对于HOTP，使用共享计数器而不是当前时间。 服务器每次成功的OTP登录都会增加计数器。 所以，只有有效的OTPs 登录成功后更改。

TOTP被认为更安全，因为可匹配的OTP仅在短时间内有效，而HOTP的OTP可以 在不确定的时间内有效。 HOTP更加用户友好，因为用户不必急于输入 时间间隔到之前的OTP。 随着Keycloak实现TOTP的方式，这种区别变得更多了 模糊。 每次服务器要增加计数器时，HOTP都需要更新数据库。 这可能是性能消耗 当负载很大时，在身份验证服务器上。 因此，为了提供更有效的替代方案，TOTP不记得密码 用。 这绕过了做任何DB更新的需要，但缺点是TOTPs可以在有效的时间间隔内重新使用。 为了未来 Keycloak的版本计划您将能够配置TOTP是否在时间间隔内检查较旧的OTPs。

Keycloak带有一定数量的内置流。 这些流不能修改，但需求可以修改为 适合你的需求。

本节对内置的浏览器登录流程进行了演练。 在 左下拉列表选择浏览器来到下面显示的屏幕:

如果将鼠标悬停在流选择列表右侧的工具提示 (微小的问号) 上，这将描述 流动是，也是。

的Auth类型列是将执行的身份验证或操作的名称。 如果身份验证缩进 这意味着它处于子流中，并且可能会或可能不会根据其父级的行为而执行。 的要求 列是一组单选按钮，它们定义了操作是否将执行。 让我们描述一下每个收音机 在这种情况下，button的意思是。

本节更深入地解释流是如何工作的，以及如何创建自己的流。 请注意，有重要的功能和安全性 设计自己的流程时的注意事项。 创建错误的流程可能不会让任何人登录，让用户以比您更少的验证进入 喜欢，或者只是导致错误。

要创建流程，您可以:

创建新流时，您必须创建顶层流

具有以下选项:

一旦创建了流，除了新的和复制按钮，你现在有了，删除,添加执行和添加流。

流的最终作用取决于流和子流的结构，这些流中的执行以及在 子流程和执行。

执行可以添加添加执行按钮。 执行可以执行多种操作，从发送重置电子邮件到验证OTP。 如果你把鼠标悬停在 旁边的工具提示 (微小的问号)提供者,这将描述执行的作用。

这些可以分为自动执行和交互式执行。 自动执行类似于饼干执行，并将自动 当在流中遇到它们时，执行它们的动作。 交互式执行会停止流动，通常是为了获得一些用户输入。 执行的执行 成功将获得成功状态。 这很重要，因为这是流程是否成功的一部分。 例如，一个空的浏览器流量 不允许任何人登录。 为此，它将需要至少一个执行成功评估，例如用户名密码表单这是正确的 已填写并提交。

子流可以在顶层流中添加添加流按钮，它打开一个创建执行流程与创建顶级表单 页。 唯一的区别是流量类型可以是通用(像以前一样)，或者表格。 的表格类型用于构造一个子流，该子流生成 用户的单个表单，例如内置的表单注册流。 子流是一种特殊类型的执行，评估为成功 取决于它们包含的执行如何评估 (这包括对它们包含的子流的评估)。 以及这个评估的逻辑 取决于每个执行和子流的要求。

充分理解这一点需要更完整地解释需求在评估流时是如何工作的，这也适用于子流。 请参阅执行要求部分有关更多详细信息，请参见上方。

请注意，添加执行后，您应该检查需求是否设置为正确的值。 即使只有一个可能的要求，它 可能发生未设置的情况。

构造流时，添加到流中的所有元素都将具有行动右侧菜单。 添加到流中的所有元素都有一个删除 此菜单中的选项可将其从流程中删除。 执行可以包含配置菜单选项来配置执行，就像 身份提供商重定向器。 子流还可以添加执行和子流，其添加执行和添加流菜单选项。

最后，由于执行顺序很重要，因此您可以使用向上和向下按钮在执行和子流各自的流中上下移动 设置在他们名字的左边。

为了说明流的创建，本节介绍更高级的浏览器登录流的创建。 此流程的目的是允许 用户在使用无密码方式登录之间进行选择网络认证,以及带有密码和OTP的双因素身份验证。 创建的流程类似于标准浏览器登录，但是在到达用户名选择时会有所不同。 然而，你不会复制流程，而是 从一开始创建流程:

用户名形式类似于 “浏览器” flow的用户名密码形式，但仅要求提供用户名，从而允许用户执行无密码登录。 但是，请注意，这不可避免地允许对您的Keycloak服务器进行用户枚举攻击。 为了方便起见，这是不可避免的安全风险， 因此，流程应该确保攻击者不能只需要猜测密码就可以输入。

产生的最终流如下:

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

重要的是要注意，由于WebAuthn无密码执行设置为替代方案而不是必需,此流程将永远不会要求用户注册WebAuthn凭据。 对于用户 要拥有Webauthn凭据，该用户必须具有管理员添加的必需操作。 首先通过确保Webauthn无密码注册 在领域中启用了所需的操作 (请参阅网络认证documentation)，然后通过使用凭证重置a的一部分 用户的凭据管理菜单。

创建更高级的流程 (例如此流程) 可能会产生一些细微的副作用。 例如，如果要启用重置密码的功能 对于用户，则可以从密码表单访问。 在默认的 “重置凭据” 流程中，用户必须输入其用户名。 自 他已经在 “无浏览器密码” 流程中较早地输入了用户名，这对于Keycloak来说是不必要的，并且在用户方面是次优的 经验。 要纠正这一点，你可以:

这是平台依赖的。 确切的步骤取决于您的操作系统和您要使用的Kerberos供应商。 有关如何准确设置和配置Kerberos服务器，请参阅Windows Active Directory，MIT Kerberos和您的操作系统文档。

至少你需要:

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

密钥标签文件/tmp/http.keytab需要在运行Keycloak服务器的主机上访问。

您需要在您的机器上安装一个kerberos客户端。 这也是平台依赖的。 如果您使用的是Fedora，Ubuntu或RHEL，则可以安装软件包freeipa-客户端,其中包含一个Kerberos客户端和其他几个实用程序。 配置kerberos客户端 (在Linux上，它在文件中/etc/krb5.conf)。 您需要放置您的Kerberos领域，并至少配置您的服务器将运行的HTTP域。 对于示例领域MYDOMAIN.ORG，您可以配置域 _ 领域像这样的部分:

接下来，您需要使用HTTP主体导出keytab文件，并确保运行Keycloak服务器的进程可以访问该文件。 对于生产而言，如果仅通过此过程而不是其他人可读，则是理想的选择。 对于上面的MIT Kerberos示例，我们已经将keytab导出到/tmp/http.keytab。 如果您的KDC和Keycloak在同一台主机上运行， 你已经有那个文件了。

客户端需要安装kerberos客户端并如上所述设置krb5.conf。 此外，他们需要在浏览器中启用SPNEGO登录支持。 见为Kerberos配置火狐如果你正在使用那个浏览器。 URI。mydomain.org必须在网络.negotiate-auth.trusted-uris配置选项。

在Windows域中，客户端通常不需要配置任何特殊内容，因为IE已经能够参与Windows域的SPNEGO身份验证。

为了更轻松地使用Kerberos进行测试，我们提供了一些示例设置进行测试。

Kerberos 5支持证书委托的概念。 在这种情况下，您的应用程序可能希望访问Kerberos票证，以便 他们可以重新使用它与Kerberos保护的其他服务进行交互。 由于SPNEGO协议是在Keycloak服务器中处理的， 您必须将GSS凭据传播到您的应用程序 在从Keycloak服务器传输到您的应用程序的OpenID Connect令牌声明或SAML断言属性中。 要将此声明插入到令牌或断言中，每个应用程序都需要启用称为gss授权证书。 这在映射器应用程序的选项卡 客户端页面。 见协议映射器章节了解更多细节。

应用程序将需要反序列化它从Keycloak收到的声明，然后才能使用它对其他服务进行GSS调用。 将凭据从访问令牌反序列化为GSSCredential对象后，将需要使用此凭据创建GSSContext 传递给方法GSSManager。创建文本例如，像这样:

我们有一个例子，详细展示了这一点。 它在示例/kerberos在Keycloak示例分发或演示分发下载中。 您也可以直接查看示例来源这里。

请注意，您还需要配置可转发kerberos门票在krb5.conf将对委托凭据的支持归档并添加到浏览器中。

在Kerberos V5协议中，境界是在Kerberos数据库 (通常是LDAP服务器) 中定义的一组Kerberos主体。 Kerberos协议具有跨领域信任的概念。 例如，如果有2个kerberos领域A和B，则跨领域信任 将允许来自领域A的用户访问领域B的资源 (服务)。这意味着领域B信任领域A。

Keycloak服务器支持跨领域信任。 要实现这一目标，需要做的事情很少:

如果您有问题，我们建议您启用其他日志记录来调试问题:

正则表达式过滤仅在身份来源设置为使用正则表达式匹配SubjectDN或者使用正则表达式匹配IssuerDN。

以下各节介绍如何配置WildFly/Undertow和Keycloak服务器以启用X.509客户端证书身份验证。

当直接向Keycloak服务器发送HTTP请求时，WildFly undertow子系统将建立SSL握手并提取客户端证书。 然后将客户端证书保存到属性中javax.servlet.request.X509Certificate的HTTP请求，如servlet规范中指定的。 然后，Keycloak X509身份验证器将能够从此属性查找证书。

但是，当Keycloak服务器在负载平衡器或反向代理后面侦听HTTP请求时，可能是代理服务器提取客户端证书并建立相互的SSL连接。 反向代理通常将经过身份验证的客户端证书放在基础请求的HTTP头中，然后将其转发到后端Keycloak服务器。 在这种情况下，Keycloak必须能够从HTTP标头而不是从HTTP请求的属性中查找X.509证书链，就像对Undertow所做的那样。

如果Keycloak位于反向代理后面，则通常需要配置x509cert-lookupKEYCLOAK_HOME/standalone/configuration/standalone.xml中的SPI 连同默认提供程序，它从HTTP头查找证书，我们还有两个额外的内置提供程序:haproxy和阿帕奇,接下来将对其进行描述。

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

注册weauthn认证器后，用户执行以下操作 假设上面的身份验证流配置与条件子流使用网络认证器被使用:

注册weauthn身份验证器时，Keycloak会验证此weauthn身份验证器生成的证明语句。 在此验证过程中，Keycloak验证了此证明声明的可信度。 它需要信任锚的证书。 Keycloak使用密钥斗篷信任商店因此，您需要提前将这些证书导入到其中。

如果要省略此证明语句可信赖性验证，请禁用此信任商店或将WebAuthn策略的配置项 “证明传递首选项” 设置为 “无”。

WebAuthn通常用于双因素身份验证，但是可能需要将其用作第一因素身份验证。 在这种情况下， 具有以下功能的用户无密码WebAuthn凭据将能够在没有密码的情况下对Keycloak进行身份验证。 Keycloak允许使用WebAuthn 作为无密码和双因素身份验证机制在单个领域的上下文中甚至在单个身份验证流的上下文中。

管理员通常可能要求用户为WebAuthn无密码身份验证注册的安全密钥必须满足不同的 (通常更强) 的要求。 例如，这些安全密钥可能要求用户使用PIN对该安全密钥进行身份验证，或者 安全密钥应通过更强的证书授权进行证明。

由于这种情况，Keycloak允许管理员配置单独的WebAuthn无密码策略。 有一个单独的必需操作 类型Webauthn无密码注册和单独的类型认证器WebAuthn无密码认证器。

您可以允许或拒绝对条件流中的资源的访问。 两个验证者拒绝访问和允许访问通过条件控制对资源的访问。

这是一个示例，如何拒绝所有没有该角色的用户的访问角色1并显示由属性定义的错误消息deny-role1。 此示例包括条件-用户角色和拒绝访问执行。

最后一件事是在登录主题中定义带有错误消息的属性消息属性(对于英语):

OIDC有不同的方式让客户端或应用程序验证用户并接收身份和访问令牌。 其中 您使用的路径在很大程度上取决于请求访问的应用程序或客户端的类型。 所有这些流程都在 OIDC和OAuth 2.0规范，因此此处仅提供简要概述。

OIDC具有与注销机制相关的三种不同规范，所有这些规范目前处于草稿状态:

同样，由于所有这些都在OIDC规范中进行了描述，因此我们在此仅进行简要概述。

以下是Keycloak发布的OIDC端点列表。 如果您使用非Keycloak客户端适配器来 与auth服务器交谈OIDC。 这些都是相对的URL，URL的根是HTTP(S) 协议，主机名，通常以 /授权,例如https:// localhost:8080/auth。

您还可以在您的领域设置中的 “OpenID端点配置” 下找到这些端点。

在所有这些替换中{领域名称}用王国的名字。

SAML定义了执行身份验证协议时交换XML文档的几种不同方式。 的重定向和邮政绑定 覆盖基于浏览器的应用程序。 的ECP绑定涵盖REST调用。 还有其他绑定类型，但只有Keycloak 支持这三个。

Keycloak真的只有一个端点用于所有SAML请求。

http(s):// authserver.host/auth/realms/{realm-name}/protocol/saml

所有绑定都使用此端点。

的Docker API文档最好地描述和说明此过程，但是下面将从Keycloak身份验证服务器的角度进行简要总结。

Keycloak实际上只有一个端点用于所有Docker auth v2请求。

http(s):// authserver.host/auth/realms/{realm-name}/protocol/docker-v2

OAuth 2.0相互TLS证书绑定访问令牌启用

相互TLS将访问令牌和刷新令牌与在TLS握手期间交换的客户端证书绑定。 这可以防止找到窃取这些令牌的方法的攻击者行使令牌。 这种类型的令牌称为密钥持有者令牌。 与承载令牌不同，密钥持有者令牌的接收者可以验证令牌的发送者是否合法。

如果令牌请求满足以下条件，则Keycloak将使用客户端证书绑定访问令牌和刷新令牌，并将其作为密钥持有者令牌发行。 如果不满足所有条件，Keycloak将拒绝令牌请求。

要在Keycloak中启用相互TLS，请参见在WildFly中启用相互SSL。

在以下情况下，Keycloak将验证客户端发送访问令牌或刷新令牌; 如果验证失败，Keycloak将拒绝令牌。

请看相互TLS客户端证书绑定访问令牌有关更多详细信息，请在OAuth 2.0相互TLS客户端身份验证和证书绑定访问令牌中。

代码交换的证明密钥 (PKCE)

当攻击者窃取发给合法客户端的授权代码时，PKCE会阻止攻击者接收适用于该代码的令牌。

管理员可以选择以下三个选项:

代码交换代码挑战方法的证明键

请看用于OAuth公共客户端代码交换的RFC 7636证明密钥有关更多详细信息。

签名和加密的ID令牌支持

Keycloak可以根据Json网络加密 (JWE)规格。 管理员可以确定每个客户端是否加密ID令牌。 默认情况下，此功能被禁用。

加密ID令牌的密钥称为内容加密密钥 (CEK)。 Keycloak和客户需要协商使用哪种CEK以及如何交付它。 这样做的方法称为密钥管理模式。

JWE规范确定了5种类型的密钥管理模式。 Keycloak支持其中的密钥加密。

在密钥加密中，客户端生成非对称密码学的密钥对。 公钥用于加密CEK。 Keycloak为每个ID令牌生成CEK，通过此生成的CEK加密ID令牌，并通过此客户端的公钥加密此CEK。 客户端通过其私钥解密此加密的CEK，并通过解密的CEK解密ID令牌。 因此，除客户端以外的任何一方都无法解密ID令牌。

客户端需要传递其公钥以将CEK加密到Keycloak上。 Keycloak支持从客户端提供的URL下载公钥。 客户端需要根据Json网络密钥 (JWK)规格。 这样做的方法定义在签署JWT的保密客户凭证。 详细程序如下:

密钥加密的算法定义在Json网络算法 (JWA)规格。 Keycloak支持RSAES-PKCS1-v1_5(RSA1_5)，使用默认参数 (rsa-oaep) 的RSAES OAEP，以及使用SHA-256和MFG1 (RSA-OAEP-256) 的RSAES OAEP 256。 选择该算法的详细过程如下:

CEK的ID令牌加密算法也定义在JWA规格。 Keycloak支持AES_CBC_HMAC_SHA2算法和AES GCM算法。 选择该算法的详细过程如下:

OAuth 2.0推送的授权请求

的基本特征OAuth 2.0推送的授权请求已经得到支持。

有关PAR的更多详细信息，请参见PAR规格。

有两个配置参数。 前者可以在每个客户端的高级设置上设置，以激活和停用PAR。

可以在每个领域的领域设置的令牌选项卡上设置后者，以确定PAR的请求URI的生存期。

如果你已经设置了客户的访问类型到机密在客户的 设置标签，一个新的凭据选项卡将显示。 请注意，凭据仅选项卡 单击后显示保存设置屏幕底部的按钮，带有 机密访问类型。 作为处理此类客户端的一部分，您必须配置 客户端的凭据。

的客户端验证器列表框指定要用于机密客户的凭据类型。 它默认为客户端ID和secret。 秘密是自动为您和再生秘密 按钮允许您重新创建这个秘密，如果你想要或需要。

或者，您可以选择使用签名的Json Web令牌 (JWT) 或x509证书验证 (也称为相互TLS)，而不是秘密。

选择此凭据类型时，您还必须在选项卡中为客户端生成私钥和证书钥匙。 私钥将用于对JWT进行签名，而证书则由服务器用于验证签名。

点击生成新密钥和证书按钮来启动此过程。

当您生成这些密钥时，Keycloak将存储证书，您需要下载私钥 和证书供您的客户使用。 选择所需的存档格式并指定私钥的密码 和存储。

你也可以选择 通过外部工具生成这些，然后导入客户端的证书。

您可以从中导入多种格式，只需选择存储证书的存档格式， 选择文件，然后单击导入按钮。

最后请注意，如果您选择使用JWKS网址。 在这种情况下，您可以在其中提供URL 客户端在JWK格式。 这是灵活的，因为当 客户端更改其密钥，Keycloak将自动下载它们，而无需在Keycloak端重新导入任何内容。

如果使用Keycloak适配器保护的客户端，则可以配置JWKS URL，例如https://myhost.com/myapp/ k_jwks假设https://myhost.com/myapp是 客户端应用程序的根URL。 见服务器开发指南有关更多详细信息。

如果您在客户端验证器列表框，您可以使用由客户端秘密签名的JWT而不是私钥。

此客户端机密将用于客户端对JWT进行签名。

通过启用此选项，Keycloak将验证客户端在TLS握手期间是否使用了正确的X509证书。

验证程序还使用配置的regexp验证表达式检查证书的主题DN字段。 对一些人来说 用例，接受所有证书就足够了。 在这种情况下，您可以使用(。*？) (？: $)表情。

Keycloak有两种方法可以从请求中获取客户端ID。 第一个选项是客户id 查询中的参数 (在第2.2节中描述OAuth 2.0规范)。 第二种选择是供应客户id作为表单参数。

每个OIDC客户端都有一个内置的服务账户这允许它获得访问令牌。 这被覆盖在OAuth 2.0规格下客户凭证授予。 要使用此功能，您必须设置访问类型你的客户机密。 当你这么做的时候， 的已启用服务帐户开关将出现。 你需要打开这个开关。 还要确保你有 配置您的客户端凭据。

要使用它，您必须已经注册了有效的机密客户端，您需要检查开关已启用服务帐户在此客户端的Keycloak管理控制台中。 在选项卡中服务帐户角色您可以配置代表此客户端检索的服务帐户可用的角色。 请记住，您必须在角色范围映射 (选项卡) 中具有可用的角色范围) 也是这个客户的，除非你 有允许的全范围上。 与普通登录一样，访问令牌中的角色是以下内容的交集:

要调用的其余URL是/auth/realms/{领域名称}/协议/openid-connect/token。 在此URL上调用是POST请求，需要您发布客户端凭据。 默认情况下，客户端凭据由中客户端的clientId和clientSecret表示授权: 基本标头，但您也可以使用签名的JWT断言或任何其他用于客户端身份验证的自定义机制对客户端进行身份验证。 您还需要使用参数grant_type = 客户端 _ 凭据根据OAuth2规范。

例如，用于检索服务帐户的POST调用可以如下所示:

回应会是这样标准JSON文档来自OAuth 2.0规范。

默认情况下，唯一返回的访问令牌。 没有返回刷新令牌，也没有创建用户会话 默认情况下，在成功身份验证后的Keycloak端。 由于缺少刷新令牌，因此在访问令牌过期时需要重新进行身份验证， 但是，这并不意味着Keycloak服务器端有任何额外的开销，因为默认情况下不会创建会话。

因此，无需注销，但是可以通过将请求发送到所描述的OAuth2吊销端点来撤销已发布的访问令牌 在OpenID连接端点节。

部署密钥斗篷的典型环境通常由一组机密或者公众客户 使用Keycloak进行身份验证的应用程序 (前端客户端应用程序)。

还有服务(称为资源服务器在OAuth 2规范中)，它服务于来自前端客户端的请求 应用程序并提供资源。 这些服务通常需要访问令牌(不记名令牌) 将发送给他们 为特定请求进行身份验证。 此令牌以前是由前端应用程序尝试登录时获得的 对抗Keycloak。

在服务之间的信任度较低的环境中，您可能会遇到以下情况:

在许多服务之间高度信任的环境中，此流程可能不是问题。 然而，在其他环境中， 服务之间的信任度较低，这可能是有问题的。

为了防止如上例中的访问令牌的任何滥用，建议限制观众在令牌上并配置 您的服务来验证令牌上的受众。 如果这样做了，上面的流程将会改变，就像这样:

如果客户端想要调用良好的服务稍后，它将需要通过使用 范围 = 良好的服务。 然后，返回的令牌将包含良好的服务作为观众:

并可用于调用良好的服务。

IDP启动的登录是一项功能，允许您在Keycloak服务器上设置一个端点，该端点将您登录到特定的应用程序/客户端。 在设置标签为您的客户端，您需要指定IDP发起的SSO URL名称。 这是一个简单的字符串，里面没有空格。 之后，您可以通过以下URL引用您的客户端:根/身份验证/领域/{领域}/协议/saml/客户端/{网址名称}

IDP发起的登录实施更喜欢邮政超过重定向绑定 (检查saml绑定有关更多信息)。 因此最终绑定和SP URL的选择方式如下:

如果您的客户端需要特殊的中继状态，您也可以在设置选项卡中的IDP启动SSO继电器状态场。 或者，浏览器可以在中继状态查询参数，即 根/身份验证/领域/{领域}/协议/saml/客户端/{url-name}？中继状态 = 状态。

使用时身份经纪,可以从 外部IDP。 如上所述，实际客户端是为在经纪人IDP处IDP发起的登录设置的。 外部国内流离失所者有 为应用程序设置客户端IDP发起的登录将指向指向代理的特殊URL和 代表中介IDP上选定客户端的IDP发起的登录端点。 这意味着在客户端设置中 在外部IDP:

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

您可以通过标准SAML实体描述符XML文件导入SAML 2.0客户端，而不是手动注册SAML实体客户端。 有一个导入添加客户端页面上的选项。

单击选择文件按钮并加载您的实体描述符文件。 您应该查看那里的所有信息，以确保所有内容都正确设置。

一些SAML客户端适配器，如mod-auth-mellon需要IDP的XML实体描述符。 你可以通过 转到这个公共网址:根/身份验证/领域/{领域}/协议/saml/描述符

映射器实现具有优先顺序。 此优先级顺序不是映射器的配置属性; 相反，它是 映射器具体实现的属性

映射器在管理控制台中按映射器列表中的顺序排序，令牌或断言中的更改将是 使用该顺序应用，最低的顺序首先应用。 这意味着依赖于其他 实现按所需的顺序处理。

例如，当我们首先要计算令牌将包含的角色时，我们首先根据 那些角色。 然后，我们处理一个JavaScript脚本，该脚本使用令牌中已经可用的角色和受众。

用户会话详细信息通过映射器定义，并取决于各种标准。 当您在客户端上使用或启用功能时，将自动包含用户会话详细信息。 您也可以单击添加内置包含会话详细信息的按钮。

模拟用户会话提供以下详细信息:

服务帐户会话提供以下详细信息:

的脚本映射器允许您通过运行用户定义的JavaScript代码将声明映射到令牌。 有关如何 将脚本部署到服务器，请看一下JavaScript提供商。

部署脚本后，您应该能够从可用映射器列表中选择部署的脚本。

创建客户端作用域时，必须选择协议。 然后只能链接使用相同协议的客户端 有了这个客户端范围。

创建新领域后，您可以看到菜单中有一个预定义 (内置) 客户端范围的列表。

客户端范围，离线访问,当客户端想要获取离线令牌时很有用。 在 离线访问部分或者在OpenID连接规范, 其中，使用值定义范围参数离线访问。

客户端范围简介,电子邮件,地址和电话也定义在OpenID连接规范。 这些客户端作用域没有定义任何角色作用域映射，但是它们定义了一些协议映射器，这些映射器对应 到OpenID Connect规范中定义的声明。

例如，当您单击以打开电话客户端作用域并打开映射器选项卡，您将看到协议映射器， 对应于说明书中定义的范围的权利要求电话。

当电话客户端作用域链接到一个客户端，该客户端自动继承在 电话客户端范围。 为此客户端发行的访问令牌将包含有关用户的电话号码信息，假设 用户有一个定义的电话号码。

内置客户端作用域完全包含根据规范定义的协议映射器， 但是，您可以自由编辑客户端范围并创建/更新/删除任何协议映射器 (或角色范围映射)。

客户端范围角色在OpenID Connect规范中未定义，也不会自动添加到范围 访问令牌中的声明。 此客户端作用域具有一些映射器，用于将用户的角色添加到访问令牌和 可能会为具有至少一个客户角色的客户添加一些受众，如观众部分。

客户端范围网络起源也没有在OpenID Connect规范中定义，也没有添加到范围索赔。 这是用的 向访问令牌添加允许的web源允许-起源索赔。

客户端范围微轮廓-jwt是为了处理中定义的索赔而创建的MicroProfile/JWT Auth规范。 此客户端作用域为upn索赔和领域角色映射器组索赔。 这些映射器 可以根据需要进行更改，以便可以使用不同的属性来创建MicroProfile/JWT特定的权利要求。

客户端范围包含与同意屏幕相关的选项。 这些选项只有在链接的客户端配置为 需要同意 (如果需要同意在客户端上启用了开关)。

客户端范围和客户端之间的链接配置在客户端范围特定客户端的选项卡。 有两种方法 客户端范围和客户端之间的链接。

标签映射器和范围的客户端包含仅为此客户端声明的协议映射器和角色范围映射。 它们不包含从客户端范围继承的映射器和范围映射。 然而，看看 有效的协议映射器将是 (协议映射器定义在客户端本身以及从链接的客户端范围继承) 以及为特定客户端生成令牌时使用的有效角色范围映射。

当您单击客户端范围客户端的选项卡，然后打开子选项卡评估。 从这里你 可以选择要应用的可选客户端范围。 这也将向您显示范围参数，需要 从应用程序发送到Keycloak OpenID Connect授权端点。

为特定用户发行令牌时，仅在允许用户使用客户端作用域时才应用客户端作用域。 在这种情况下 客户端作用域本身没有定义任何角色作用域映射，则自动允许每个用户使用此 客户端范围。 但是，当客户端作用域具有在其自身上定义的任何角色作用域映射时，则用户必须至少是 其中一个角色。 换句话说，用户角色和客户端范围的角色之间必须有交叉。 复合材料 评估此交集时会考虑角色。

如果不允许用户使用客户端范围，则在生成令牌时将不使用协议映射器或角色范围映射 并且客户端作用域不会出现在范围令牌中的值。

的领域默认客户端范围允许您定义一组客户端范围，这些范围将自动链接到新创建的客户端。

打开左侧菜单项客户端范围然后选择默认客户端范围。

从这里，选择要添加为的客户端范围默认客户端范围给新创建的客户和可选客户端范围 给新创建的客户。

创建客户端后，如果需要，可以取消链接默认客户端范围。 这类似于你 移除默认角色。

术语范围在少数地方使用Keycloak。 作用域的各种出现相互关联，但可能有 不同的背景和意义。 为了澄清，这里我们解释各种范围用于Keycloak。

客户端策略实现以下几点。

客户端策略概念独立于任何特定协议。 但是，Keycloak目前仅支持OpenID Connect (OIDC) 协议。

客户端策略由四个构建块组成: 条件，执行器，配置文件和策略。

策略，配置文件，条件，执行程序可以由Admin REST API配置，这也意味着管理控制台。 要做到这一点，有一个标签境界→领域设置→客户端策略 ,这意味着管理员可以在每个领域拥有客户端策略。

的全球客户档案在每个领域都自动可用。 但是没有客户端策略 默认配置。 这意味着，如果管理员希望例如其领域的客户端符合FAPI，则始终需要创建任何客户端策略。 全球 配置文件无法更新，但是管理员可以轻松地将它们用作模板并创建自己的配置文件，如果他们想在全局配置文件配置中做一些细微的更改。 管理控制台中有可用的JSON编辑器，它简化了基于某些全局配置文件的新配置文件的创建。

客户端策略可以替换中描述的客户端注册策略保护应用程序和服务指南。 然而，客户注册政策也仍然共存。 这意味着例如在动态客户端注册请求创建/更新客户端期间，客户端策略和 应用客户端注册策略。

当前的计划是删除客户端注册策略功能，并且现有的客户端注册策略将自动迁移到新的客户端策略中。 = = 角色

角色标识用户的类型或类别。 管理员,用户,经理,以及员工都是可能存在的典型角色 在一个组织中。 应用程序通常将访问权限和权限分配给特定角色，而不是将单个用户分配为交易 用户的粒度可能太细，难以管理。 例如，管理控制台具有特定角色，这些角色向用户授予权限 访问管理控制台UI的部分并执行某些操作。 角色有一个全局名称空间，每个客户端也有自己的 可以定义角色的专用名称空间。

默认角色允许您在通过新创建或导入任何用户时自动分配用户角色映射 身份经纪。 要指定默认角色，请转到角色左侧菜单项，然后单击默认角色标签，或者你可以 搜索默认-角色-${realmName}在领域角色选项卡，然后单击编辑。 请注意默认-角色-${realmName} 不能删除角色，因为它同时充当领域和客户端默认角色的容器。

从屏幕截图中可以看到，已经有很多默认角色默认设置。

在大师境界。 这些是:

具有管理员角色是超级用户，可以完全访问服务器上的任何领域。 具有创造领域角色 被允许创造新的领域。 他们将被授予对他们创造的任何新境界的完全访问权限。

中的管理员用户大师可以将realm授予系统中一个或多个其他领域的管理权限。 Keycloak中的每个领域都由客户端表示大师境界。 客户端的名称是<境界名称>-境界。 这些客户端每个都有定义的客户端级别角色，这些角色定义了不同的 管理单个领域的访问级别。

可用的角色有:

将您想要的角色分配给用户，他们将只能使用管理控制台的特定部分。

让我们先看看允许 仅管理一个客户端和一个客户端的管理员。 在我们的例子中，我们有一个境界 被称为测试一个客户叫销售-应用。 在领域测试我们会给一个 该领域中的用户权限仅管理该应用程序。

您可能要做的另一件事是限制管理员允许的角色集 分配给用户。 继续我们的最后一个示例，让我们扩展 “sales-admin” 的权限集 用户，以便他还可以控制允许哪些用户访问此应用程序。 通过细粒权限，我们可以 启用它，以便销售管理员只能分配授予特定访问权限的角色 的销售-应用。 我们还可以对其进行限制，以便管理员只能映射角色 并且不执行任何其他类型的用户管理。

的销售-应用定义了三个不同的客户端角色。

我们想要销售管理员用户能够将这些角色映射到系统中的任何用户。 的 执行此操作的第一步是允许管理员映射角色。 如果我们点击 查看线索角色，你会看到有一个权限此角色的选项卡。

如果我们点击该选项卡并打开已启用权限上，你会看到 是我们可以应用策略的许多操作。

我们感兴趣的是地图-角色。 单击此权限并添加相同的 在前面的示例中创建的用户策略。

我们所做的是说销售管理员可以映射查看线索作用。 我们所拥有的 未完成的是指定允许管理员映射此角色的用户。 要做到这一点 我们必须去用户此领域的管理控制台部分。 点击 用户左侧菜单项将我们带到领域的用户界面。 你应该看到一个 权限tab。 单击并启用它。

我们感兴趣的许可是地图-角色。 这是一项限制性政策 因为它只允许管理员将角色映射到用户。 如果我们点击 地图-角色权限，并再次添加我们为此创建的用户策略，我们的销售管理员 将能够将角色映射到任何用户。

我们要做的最后一件事是添加视图-用户对销售管理员。 这将 允许管理员查看他想要添加的领域中的用户销售-应用角色。

除了管理特定的客户端或客户端的特定角色之外，您还可以使用精细的权限做更多的事情。 本章定义了可以描述的权限类型的整个列表 一个境界。

建议定期旋转按键。 为此，您应该从创建优先级高于 现有的活动密钥。 或创建具有相同优先级的新密钥，并使以前的密钥变得被动。

一旦新密钥可用，所有新令牌和cookie都将使用新密钥进行签名。 当用户向 应用程序SSO cookie使用新签名进行更新。 当OpenID Connect令牌刷新时，新令牌是 用新钥匙签名。 这意味着随着时间的推移，所有的cookie和令牌将使用新的密钥，并在一段时间后 旧钥匙可以移除。

您等待多长时间删除旧密钥是安全性和确保所有cookie和令牌都已更新之间的权衡。 一般来说，几周后放下旧钥匙应该是可以接受的。 期间未活跃的用户 在添加的新密钥和删除的旧密钥之间必须重新进行身份验证。

这也适用于离线令牌。 为了确保它们已更新，应用程序需要先刷新令牌 旧钥匙被移除。

作为指导方针，最好每3-6个月创建一次新密钥，并在新密钥后1-2个月删除旧密钥 创建了密钥。

要添加新生成的keypair，请选择提供商并选择rsa生成从下拉列表中。 您可以更改优先级 以确保新的keypair成为活动的keypair。 您也可以更改关键大小如果你想要更小或更大的键 (默认为2048， 支持的值是1024、2048和4096)。

点击保存添加新密钥。 这将生成一个新的keypair，包括自签名证书。

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

要添加在其他地方获得的keypair和证书，请选择提供商并选择rsa从下拉列表中。 你可以改变 确保新的keypair成为活动的keypair的优先级。

点击选择文件对于私有RSA密钥上传您的私钥。 文件应该以PEM格式编码。 你 不需要上传公钥，因为它是从私钥中自动提取的。

如果您有密钥的签名证书，请单击选择文件旁边X509证书。 如果你没有 您可以跳过此操作，然后将生成自签名证书。

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

填写以下值密钥库,密钥库密码,密钥别名和密钥密码然后点击保存。

找到键盘活动然后在提供者列。 这将把你带到 密钥提供程序的配置屏幕。 点击活动转动它关,然后点击保存。 的 密钥将不再处于活动状态，只能用于验证签名。

找到键盘活动然后在提供者列。 这将把你带到 密钥提供程序的配置屏幕。 点击已启用转动它关,然后点击保存。 的 密钥将不再启用。

或者，您可以从提供商表。

Keycloak的签名密钥仅存储在本地，并且永远不会与客户端应用程序，用户或其他 实体。 但是，如果您认为您的领域签名密钥受到损害，则应首先如上所述生成新的keypair，并且 然后立即移除受损的keypair。

然后，为了确保客户端应用程序不会接受由受损密钥签名的令牌，您应该更新并推送之前的策略 可以从管理控制台执行的领域。 推动新政策将确保客户端应用程序不会接受现有的 由受损密钥签名的令牌，但客户端应用程序也将被迫从Keycloak下载新的keypair，因此 被破坏的密钥签名的令牌将不再有效。 请注意，您的休息和机密客户必须已设置管理网址,这样 Keycloak能够向他们发送有关未推送策略的请求。

您必须完成许多步骤才能启用Bitbucket登录。

首先，打开身份提供者左侧菜单项并选择比特桶从添加提供程序下拉列表。 这将把你带到添加身份提供程序页。

在您可以单击之前保存,您必须获得一个客户端ID和客户秘密从比特桶。

要使用Bitbucket启用登录，您必须首先在 Bitbucket云上的OAuth。

单击添加消费者按钮。

复制重定向URI从Keycloak添加身份提供程序页面，并将其输入到Bitbucket Add OAuth Consumer页面的回调URL字段中。

在同一页面上，标记电子邮件和阅读下面的盒子账户以允许您的应用程序读取用户电子邮件。

完成注册后，单击保存。 这将打开Bitbucket中的应用程序管理页面。 从此页面中找到客户端ID和秘密，以便您可以将它们输入到Keycloak中添加身份提供程序页。 点击保存。

要启用Facebook登录，您必须完成许多步骤。 首先，去身份提供者左侧菜单项 并选择脸书从添加提供程序下拉列表。 这将把你带到添加身份提供程序页。

您还不能单击保存，因为您需要获取一个客户端ID和客户秘密来自Facebook。 你需要的一条数据 页面是重定向URI。 当你在Facebook注册Keycloak为客户时，你必须把它提供给Facebook，所以 把这个URI复制到你的剪贴板上。

要使用Facebook启用登录，您首先必须在Facebook开发者控制台。

登录控制台后，屏幕右上角有一个下拉菜单，显示我的应用程序。 选择添加新应用 菜单项。

选择网站图标。 单击跳过并创建应用程序ID按钮。