升级指南

要运行独立模式的升级脚本，请完成以下步骤:

对于独立高可用 (HA) 模式，必须同时升级所有实例。

要运行独立HA模式的升级脚本，请完成以下步骤:

对于域模式，所有实例必须同时升级。

要运行域模式的升级脚本，请完成以下步骤:

要启用数据库架构的自动升级，请将migrationStrategy属性值设置为 “update”，用于 默认连接sjpa提供程序:

或者运行这个CLI命令:

使用此设置启动服务器时，如果数据库架构已更改，则会自动迁移数据库 在新版本中。

在具有数百万条记录的巨大表上创建索引很容易花费大量时间 并可能导致升级时的重大服务中断。 对于这些情况，我们添加了用于自动创建索引的阈值 (记录数)。 默认情况下，此阈值为300000记录。 当记录数高于阈值时，不会自动创建索引， 服务器日志中会有一条警告消息，包括SQL命令，以后可以手动应用。

要更改阈值，请设置索引创建阈值属性，默认值连接liquibase提供者:

或者运行这个CLI命令:

要启用手动升级数据库架构，请将migrationStrategy属性值设置为 “manual”，默认为 连接sjpa提供程序:

或者运行这个CLI命令:

使用此配置启动服务器时，它会检查是否需要迁移数据库。 所需的更改 写入到SQL文件中，您可以对该文件进行检查并手动对数据库运行。 有关如何 将此文件应用于数据库，请参阅您正在使用的关系数据库的文档。 更改后 写入文件后，服务器退出。

如果您已自定义任何模板，则需要仔细查看对模板所做的更改 决定是否需要将这些更改应用于自定义模板。 很可能你需要应用相同的 更改自定义模板。 如果您尚未自定义任何列出的模板，则可以跳过此部分。

最佳实践是使用diff工具比较模板，以查看可能需要对模板进行哪些更改 定制模板。 如果您仅进行了较小的更改，则将更新后的模板与您的模板进行比较会更简单 定制模板。 但是，如果您进行了许多更改，则将新模板与您的模板进行比较可能会更容易 自定义的旧模板，因为这将显示您需要进行哪些更改。

下面的屏幕截图比较了来自登录主题的info.ftl模板和一个示例自定义主题:

通过此比较，很容易识别出第一个更改 (“Hello world!!”) 是一个定制，而 第二个更改 (“if pageRedirectUri”) 是对基本主题的更改。 通过将第二个更改复制到您的自定义模板， 您已成功更新您的自定义模板。

对于替代方法，以下屏幕截图将旧安装中的info.ftl模板与 新安装中更新的info.ftl模板:

通过此比较，很容易确定基本模板中已更改的内容。 然后你必须手动 对您修改后的模板进行相同的更改。 由于这种方法不如第一种方法简单，因此只能使用 如果第一种方法不可行，这种方法。

如果您添加了对另一种语言的支持，则需要应用上面列出的所有更改。 如果您没有添加 支持另一种语言，你可能不需要改变任何东西; 你只需要做出改变，如果你已经改变了 主题中的受影响消息。

对于添加的值，请查看基本主题中消息的值，以确定是否需要自定义该消息。

对于重命名键，请在自定义主题中重命名键。

对于已更改的值，请检查基本主题中的值，以确定是否需要对自定义主题进行更改。

如果要从keycloak或rh-sso主题继承样式，则可能需要更新自定义样式以反映 对内置主题的样式进行了更改。

最佳实践是使用diff工具比较旧服务器安装和 新服务器安装。

例如，使用diff命令:

查看更改并确定它们是否影响您的自定义样式。

客户端策略功能是自Keycloak 12以来的预览功能，并且没有适当的支持。 如果您尝试了此功能并配置了一些客户端策略或客户端配置文件 在Keycloak 12或Keycloak 13中，您将需要在新版本中再次配置客户端策略和客户端配置文件。 配置的格式变化很大 由于它只是预览，因此我们不提供在Keycloak 12或Keycloak 13中创建的客户端策略和客户端配置文件的自动迁移。

当独立的.xml包含对任何SmallRye模块的引用时，需要手动更改。 SmallRye模块已从基础WildFly发行版中删除，并且服务器未启动 如果配置引用了它们。 因此，如果配置在独立。xml指的是这些模块， 服务器配置迁移通过migrate-standalone.cli在对配置进行任何更改之前失败。 在这种情况下，要执行服务器配置迁移，您必须手动删除所有引用的行 小黑麦模块。 在默认配置中，您需要专门删除以下几行:

Keycloak服务器已升级为使用Wildfly 23作为底层容器。 这并不直接涉及任何 但是，请注意与迁移相关的这些更改:

Keycloak服务器已升级为使用Wildfly 22作为底层容器。 这并不直接涉及任何 但是，请注意与迁移相关的这些更改:

增加了对只读用户属性的支持。 这包括用户属性，这些属性不应该由用户编辑 或由管理员在使用REST API或Keycloak用户界面更新用户时。 这可能很重要，尤其是如果你 使用:

请参阅中的详细信息威胁模型缓解章节。

如果您使用OpenID Connect参数请求 _ uri,存在一个要求，您的客户需要有效请求uri配置。 这可以通过客户端详细信息页面上的管理控制台或通过admin REST API或客户端注册API进行配置。 有效请求uri需要 以包含请求URI值的列表，该值对于特定客户端是允许的。 这是为了避免SSRF攻击。 有可能使用通配符 或类似的相对路径，例如有效的重定向uri选项，但是出于安全目的，我们通常建议将其用作特定值 尽可能。

Keycloak服务器已升级为使用Wildfly 21作为底层容器。 这并不直接涉及任何 但是，请注意与迁移相关的这些更改:

使用Docker协议成功进行身份验证后，不会创建任何用户会话。 有关详细信息，请参阅服务器管理指南。

Keycloak登录主题组件已升级到PatternFly 4。 旧的PatternFly 3与新的PatternFly 3同时运行，因此可以保留PF3组件。 但是，对登录主题的设计进行了一些更改。 由于它们，请升级您的自定义登录主题。 可以在Keycloak/例子/主题/日出目录。 不需要额外的设置。

在此Keycloak版本中，OAuth2客户端凭据授予端点默认情况下不会发出刷新令牌。 此行为与OAuth2规范一致。 作为此更改的副作用，成功进行客户端凭据身份验证后，不会在Keycloak服务器端创建用户会话，从而导致 在提高性能和内存消耗方面。 鼓励使用客户端凭据授予的客户端停止使用 刷新令牌，而是始终在每个请求中使用grant_type = 客户端 _ 凭据而不是使用刷新令牌作为授权类型。 与此相关，Keycloak支持撤销OAuth2撤销端点中的访问令牌，因此允许客户端 如果需要，撤销个人访问令牌。

为了向后兼容，存在坚持旧版本行为的可能性。 使用此功能时，刷新令牌仍将在 将创建具有客户端凭据授予和用户会话的成功身份验证。 这可以为中的特定客户端启用 Keycloak管理控制台，在客户端详细信息部分中OpenID连接兼容模式用开关使用刷新令牌进行客户端凭据授予。

Keycloak服务器已升级为使用Wildfly 20作为底层容器。 这并不直接涉及任何 但是，请注意与迁移相关的这些更改:

在以前的Keycloak版本中，当LDAP提供程序配置为导入用户关闭，可以更新 用户，即使某些非LDAP映射属性已更改。 这种情况导致了令人困惑的行为，当属性似乎被更新时， 但事实并非如此。 在当前版本中，如果更改了任何非LDAP映射属性，则根本不允许执行更新。

这不应影响大多数部署，但在某些罕见情况下可能会受到影响。 例如，如果你以前 尝试使用admin REST API更新用户，并且该用户的属性更改不正确，因此可以进行更新。 与 当前版本，无法进行更新，您将立即被告知原因。

田野用户名,电子邮件,名字和姓氏在用户模型迁移到自定义属性，作为在即将发布的版本中将更复杂的用户配置文件添加到Keycloak的准备。 如果数据库包含具有该确切名称的自定义属性的用户，则需要在升级之前迁移自定义属性。 此迁移不会自动发生。 否则，它们将不再被从数据库中读取，并可能被删除。 这种情况意味着用户名现在也可以通过以下方式访问和设置用户模型。getFirstAttribute (用户模型。用户名)。 其他领域也存在类似的含义。 SPIs子类化的实现者用户模型直接或间接应确保之间的行为设置用户名和setSingleAttribute (用户模型。用户名，…)(与其他字段相似) 是一致的。 如果策略评估功能的用户在评估中使用属性的数量，则必须调整其策略，因为默认情况下，每个用户现在将具有四个新属性。

的公共API用户模型没有改变。 无需更改访问用户数据的前端资源或SPIs。 此外，数据库还没有改变。

Instagram IdP现在使用新的API，就像旧的旧版API一样已弃用。 这需要获取新的API凭据。 有关详细信息， 请参考服务器管理指南。

对于使用Instagram IdP的现有用户，尤其是唯一身份验证的用户，需要特别注意 选项。 这些用户必须在2020年9月30日前使用Instagram IdP登录Keycloak。 那一天之后，他们将拥有 使用不同的身份验证方法 (如密码) 登录以手动更新其Instagram社交链接，或创建 Keycloak的新帐户。 这是因为Instagram用户id在新旧API之间不兼容，但是 新的API暂时返回新的和旧的用户id以允许迁移。 Keycloak一旦用户自动迁移ID 登录。

在以前的版本中，Keycloak宣传了两个内省端点:令牌 _ 反省 _ 端点和反省 _ 终点。 后者是由RFC-8414。 前者，以前被弃用， 现已被移除。

不再需要在JavaScript适配器中设置promiseType，并且两者同时可用。 它是 建议更新应用程序以使用本机promise API (然后和抓住) 尽快作为旧版API (成功和错误) 将在某个时候被移除。

版本9.0.1修复了一个问题，该问题可能会在领域中创建重复的顶级组。 然而，存在 以前重复的组会使升级过程失败。 Keycloak服务器可能会受到此问题的影响 如果它使用的是H2、MariaDB、MySQL或PostgreSQL数据库。 在启动升级之前，请检查服务器是否包含 重复的顶级组。 例如，可以在数据库级别执行以下SQL查询以列出它们:

每个领域中只能存在一个具有相同名称的顶级组。 重复项应在 升级。 升级中的错误包含消息更改设置元INF/jpa-changelog-9.0.1.xml::9.0.1- KEYCLOAK-12579-add-not-null-constraint::keycloak失败。

对如何选择登录页面的区域设置以及区域设置的时间进行了许多改进 为用户更新。

请参阅服务器管理指南有关更多详细信息。

在2038年int不再能够保存秒1970年的值，因此我们正在努力将它们更新为 长值。 此外，另一个问题与处理int值存在于令牌表示中。 一个int将由 默认结果为0在JSON表示形式中，而不应该包括

有关已弃用的确切方法和替换方法的更多详细信息，请参见JavaDocs。

旧的请求和固定的主机名提供程序被替换为新的默认主机名提供程序。 请求 和固定的主机名提供程序现在已弃用，建议切换到默认主机名提供程序为 尽快。

Keycloak服务器已升级为使用Wildfly 18作为底层容器。 这并不直接涉及任何 但是，请注意与迁移相关的这些更改:

到目前为止，允许管理员通过Keycloak管理控制台将脚本上传到服务器，以及 通过RESTful Admin API。

目前，这种能力是禁用默认情况下，用户应该更喜欢直接将脚本部署到服务器。 有关更多详细信息， 请看看JavaScript提供商。

在以前的版本中，允许开发人员向JavaScript适配器提供客户端凭据。 目前，这种能力是移除,因为客户端应用程序不安全保守秘密。

我们做了一些与身份验证流程相关的重构和改进，这需要在迁移过程中注意。

我们在存储用户凭据方面增加了更大的灵活性。 除其他事项外，每个用户都可以具有相同的多个凭据 类型，例如多个OTP凭据。 结果，对数据库模式进行了一些更改。 然而，来自 以前的版本应自动更新为新格式，并且用户仍应能够使用其密码或OTP登录 以前版本中设置的凭据。

Keycloak服务器已升级为使用Wildfly 17作为底层容器。 这并不直接涉及任何 但是，请注意与迁移相关的这些更改:

Keycloak服务器已升级为使用Wildfly 16作为底层容器。 这并不直接涉及任何 但是，请注意与迁移相关的这些更改:

我们增加了一个新的微轮廓-jwt可选的客户端范围，用于处理中定义的声明MicroProfile/JWT Auth规范。 这个新的客户端作用域定义了协议映射器，以将经过身份验证的用户的用户名设置为upn索赔和 将领域角色设置为组索赔。

我们在OIDC身份提供程序配置中添加了一个名为接受提示 = 无来自客户端的转发确定国内流离失所者 能够处理转发的请求，其中包括提示 = 无查询参数。

到目前为止，当收到带有提示 = 无一个领域会返回一个登录 _ 必需如果用户是 在未检查用户是否已通过IDP身份验证的情况下未在领域中进行身份验证。 从现在开始，如果默认 可以为身份验证请求确定IDP (通过使用kc_idp_hint查询参数或通过设置默认IDP 对于领域)，如果接受提示 = 无来自客户端的转发IDP已启用开关，身份验证请求被转发到IDP 以检查用户是否已在那里进行身份验证。

重要的是要注意，仅在指定了默认IDP的情况下才考虑此切换，在这种情况下，我们知道 在哪里转发身份验证请求，而不必提示用户选择IDP。 如果无法确定默认IDP 我们不能假设哪一个将用于满足身份验证请求，因此不执行请求转发。

Keycloak服务器已升级为使用Wildfly 15作为底层容器。 这并不直接涉及任何 但是，请注意与迁移相关的这些更改:

截至4.8.1版本的Keycloak中的Google身份提供商实现依赖于Google + API端点 用于授权和获取用户配置文件的端点。 从3月2019日起，Google将取消支持 对于Google + API，支持新的Google登录身份验证系统。 Keycloak身份提供程序已更新 要使用新的端点，因此如果使用此集成，请确保升级到Keycloak版本4.8.2或更高版本。

如果您遇到错误，说在目录中找不到应用程序标识符，则必须在 谷歌API控制台门户以获取新的应用程序id和机密。

您可能需要为Google用户提供的非标准声明调整自定义映射器 信息端点，并通过Google登录API以不同的名称提供。 请查阅谷歌文档 有关可用索赔的最新信息。

因此，使用LinkedIn，所有开发人员都需要迁移到其api和OAuth 2.0的2.0版本。 因此，我们已经更新了 我们的LinkedIn社交经纪人。

使用此代理的现有部署在使用的版本2获取用户的配置文件时可能会开始出现错误 LinkedIn api。 此错误可能与缺少授予用于配置代理的客户端应用程序的权限有关 在身份验证过程中，可能无权访问配置文件API或请求特定的OAuth2作用域。

即使对于新创建的LinkedIn客户端应用程序，您也需要确保客户端能够请求r_liteprofile和 R _ 电子邮件地址OAuth2作用域，至少客户端应用程序可以从https://api.linkedin.com/v2/me端点。

由于LinkedIn在访问会员信息方面施加的这些隐私限制，以及由 当前会员的个人资料API，LinkedIn社交经纪人 现在使用会员的电子邮件地址作为默认用户名。 这意味着R _ 电子邮件地址总是在以下情况下设置 在身份验证期间发送授权请求。

我们添加了新的领域默认客户端范围角色和网络起源。 这些客户端作用域包含协议 映射器将用户的角色和允许的web origins添加到令牌中。 在迁移过程中，这些客户端作用域应该是 自动添加到所有OpenID Connect客户端作为默认客户端作用域。 因此，在数据库之后不需要设置 迁移完成。

要将本机JavaScript promise与JavaScript适配器一起使用，现在需要设置承诺类型到原生在 init选项。

在过去，如果本地承诺可用，则返回一个包装器，该包装器同时提供了遗留的Keycloak承诺和 土著承诺。 这导致了问题，因为错误处理程序并不总是在本机错误事件之前设置， 导致未捕获 (承诺)错误。

Keycloak至4.5.0版本的Microsoft身份提供程序实现依赖于实时SDK 用于授权和获取用户配置文件的端点。 从2018年11月开始，微软正在取消支持 对于支持新的Microsoft Graph API的实时SDK API。 Keycloak身份提供程序已更新 要使用新的端点，因此如果正在使用此集成，请确保升级到Keycloak版本4.6.0或更高版本。

在 “实时SDK应用程序” 下注册的旧版客户端应用程序将无法与Microsoft Graph端点一起使用 由于应用程序的id格式的更改。 如果您遇到错误，说应用程序标识符 在目录中找不到，您必须在 微软应用程序注册门户以获取新的应用程序id。

Keycloak服务器已升级为使用Wildfly 14作为底层容器。 这并不直接涉及任何 但是，请注意与迁移相关的这些更改:

Keycloak服务器已升级为使用Wildfly 13作为底层容器。 这并不直接涉及任何 但是，请注意与迁移相关的这些更改:

在以前的版本中，建议使用过滤器来指定允许的主机名。 现在有可能 设置一个固定的主机名，这使得更容易确保使用有效的主机名，并且还允许内部 通过替代URL (例如内部ip地址) 调用Keycloak的应用程序。 它是 建议您在生产中改用这种方法。

我们添加了对客户端作用域的支持，这需要在迁移过程中注意。

我们添加了对UMA 2.0的支持。 此版本的UMA规范引入了一些关于如何从服务器获取权限的重要更改。

以下是UMA 2.0支持引入的主要更改。 见授权服务指南有关详细信息。

OpenID Connect会话管理规范要求参数会话状态存在于OpenID Connect身份验证响应中。

在过去的版本中，我们没有此参数，但是现在Keycloak根据规范的要求默认添加此参数。

但是，某些OpenID Connect / OAuth2适配器，尤其是较旧的Keycloak适配器，可能对此新参数有问题。

例如，在对客户端应用程序成功进行身份验证后，该参数将始终存在于浏览器URL中。 在这些情况下，禁用添加会话状态身份验证响应的参数。 这是可以做到的 对于Keycloak管理控制台中的特定客户端，在带有OpenID连接兼容模式, 中描述与旧适配器的兼容性。 专用从身份验证响应中排除会话状态开关存在， 可以打开它来防止添加会话状态身份验证响应的参数。

我们添加了两种新的密码哈希算法 (pbkdf2-sha256和pbkdf2-sha512)。 新的领域将使用pbkdf2-sha256 具有27500哈希迭代的哈希算法。 由于pbkdf2-sha256比pbkdf2稍快，因此迭代 从20000增加到27500。

如果密码策略包含哈希算法的默认值 (未指定)，则升级现有领域 迭代 (20000)。 如果您更改了散列迭代，则需要手动更改为pbkdf2-sha256 使用更安全的哈希算法。

OpenID Connect规范需要该参数范围有价值openid用于初始授权请求。 所以穿着Keycloak 2.1.0我们更改了适配器以使用范围 = openid在重定向URI到Keycloak。 现在我们也更改了服务器部分和ID令牌 将被发送到应用程序，只要范围 = openid真的很常用。 如果未使用，则ID令牌将被跳过，仅访问令牌和刷新令牌将被发送到应用程序。 这还允许您可以故意省略ID令牌的生成-例如出于空间或性能目的。

直接授予 (OAuth2资源所有者密码凭据授予) 和服务帐户登录 (OAuth2客户端凭据授予) 现在默认情况下也不使用ID令牌。 您需要明确添加范围 = openid包含ID令牌的参数。

我们正在努力支持多个数据中心。 作为第一步，我们引入了身份验证会话和操作令牌。 身份验证会话取代了以前版本中使用的客户端会话。 操作令牌目前特别用于场景，其中 身份验证器或requiredActionProvider要求向用户发送电子邮件，并要求用户单击电子邮件中的链接。

以下是与此相关的具体更改，可能会影响您的迁移。

与此相关的第一个变化是引入新的Infinispan缓存身份验证会话和动作令牌在独立。xml或者standalone-ha.xml。 如果您使用我们的迁移CLI，您 不需要像你的那样关心独立 (-ha).xml文件将自动迁移。

第二个变化是身份验证SPI方法中某些签名的更改。 如果您使用自定义认证器或者 要求操作提供程序。 类AuthenticationFlowContext和要求操作上下文现在允许检索身份验证会话 而不是客户端会话。

我们还添加了一些对粘性会话的初始支持。 您可能想要更改您的loadbalancer/proxy服务器，并配置它，如果您不想遭受它的痛苦，并希望拥有更好的性能。 路线被添加到新的身份验证 _ 会话 _ 标识饼干。 群集文档中的更多信息。

另一个变化是，令牌。getClientSession()被移除了。 例如，如果您使用的是客户端启动的身份代理链接功能，这可能会影响您。

的脚本基础认证器将绑定名称从客户会话到身份验证会话,因此，如果您使用此身份验证器，则需要更新脚本。

最后，我们向管理控制台添加了一些新的超时。 例如，这允许您为管理员和用户本人触发的电子邮件操作指定不同的超时。

如果您从2.2.0或更早版本迁移，并且使用了脱机令牌，则脱机令牌的令牌标头中没有KID。 我们在2.3.0中将KID添加到令牌标头中，并具有多个领域密钥的功能，因此Keycloak能够根据令牌KID找到正确的密钥。

对于没有KID的离线令牌，Keycloak 2.5.1将始终使用active realm密钥来找到用于令牌验证的正确密钥。 换句话说，旧的迁移 离线令牌将起作用。 例如，您的用户在1.9.8中请求离线令牌，然后您从1.9.8迁移到2.5.1，然后您的用户将 仍然能够在2.5.1版本中刷新他的旧脱机令牌。

但是存在限制。 一旦您更改了领域活动密钥，用户将无法刷新旧的离线令牌 再也没有了。 因此，在所有具有离线令牌的用户刷新其令牌之前，您不应该更改活动域密钥。 显然是新的 刷新的令牌将在标头中包含KID，因此在所有用户交换其旧的脱机令牌后，您可以自由更改active realm密钥。

的领域中的infinispan子系统中定义的缓存独立。xml或者standalone-ha.xml配置文件，现在默认具有10000记录的逐出。 这是相同的默认值，就像用户缓存。

还有授权缓存现在默认情况下没有任何驱逐。

keycloak-server-spi模块已拆分为keycloak-server-spi和keycloak-server-spi-private。 内的api keycloak-server-spi不会在次要版本之间更改，而我们保留权利，并且很可能会更改 次要版本之间的keycloak-server-spi-private中的api。

SAML中的密钥断言和文档现在使用rsa-oaep加密方案进行加密。 如果要使用加密的断言，请确保服务提供商了解此加密方案。 在SP无法处理新方案的不太可能的情况下，Keycloak 使用系统属性启动时，可以使用遗留RSA-v1.5加密方案 Keycloak.saml.key_trans.rsa_v1.5设置为真。

即使您在集群中使用Keycloak，缓存领域和用户在infinispan子系统中定义standalone-ha.xml是 现在总是本地缓存。 单独的缓存工作exists，它处理在集群节点之间发送无效消息和通知整个集群 底层的哪些记录领域和用户缓存应该失效。

所有支持分页的Admin REST API端点现在都将默认的max结果设置为100。 如果你想回来 超过100个条目，您需要用？max = <结果>。

在2.3.0版本中，我们添加了对公钥轮换的支持。 当管理员在Keycloak管理控制台中旋转领域键时，客户端 适配器将能够识别它，并自动从Keycloak下载新的公钥。 然而，这种自动下载新的 如果你没有钥匙，钥匙就完成了领域-公钥带有硬编码公钥的适配器中的选项。 因此，我们不建议 使用领域-公钥适配器配置中的选项。

注意此选项仍然受支持，但是如果您真的想在适配器配置中使用硬编码的公钥，它可能会很有用 永远不要从Keycloak下载公钥。 从理论上讲，这样做的原因之一是，如果您在适配器和Keycloak之间存在不受信任的网络，则可以避免中间人攻击， 但是，在这种情况下，使用HTTPS是更好的选择，这将保护适配器和Keycloak之间的所有请求。

在此版本中，我们添加了新的缓存钥匙到infinispan子系统，该子系统在独立。xml或者standalone-ha.xml配置文件。 它还定义了一些驱逐和到期。 此缓存在内部用于缓存实体的外部公钥 受服务器 (身份提供者或客户端，使用带有签名JWT的身份验证) 的信任。

的数据库JPA和Mongo的财产现在都是已弃用并且是替换为 initializeEmpty 和迁移策略。initializeEmpty可以将bet设置为真或者假并控制空数据库是否应该 被初始化。迁移策略可以设置为更新,验证和手册。手册仅支持 关系数据库，并将编写一个SQL文件，对数据库架构进行所需的更改。 请注意 对于Oracle数据库，创建的SQL文件包含设置定义关闭Oracle SQL客户端理解的命令。 如果脚本被任何其他客户端使用，请用 如果此类功能不适用，您可以选择禁用变量扩展或完全删除它。

以下情况受到影响:

身份提供程序不再具有将其设置为默认身份验证提供程序的选项。 而是转到身份验证，选择浏览器流和配置身份提供商重定向器。 它具有设置默认身份提供程序的选项。

从1.0.0升级。不再支持Final。 要升级到此版本，请升级到1.9.8。升级前的最终版本 至2.0.0。

新领域的默认密码散列间隔已增加到20K (从之前的1)。 这一变化将产生影响 关于用户进行身份验证时的性能。 例如，使用旧的默认值 (1)，哈希密码需要不到1毫秒的时间，但是使用 新的默认值 (20K) 相同的操作可能需要50-100 ms。

将管理员用户添加到Keycloak的脚本已重命名为添加-用户-密钥斗篷。

我们删除了选项auth-server-url-for-backend-requests，因为在某些情况下使用它的问题。 更详细地说， 可以从2个不同的上下文 (内部和外部) 访问Keycloak服务器，这导致令牌验证等问题。

如果您仍然想使用此选项提供的网络优化 (避免应用程序发送反向通道请求 通过loadbalancer，但直接将它们发送到本地Keycloak服务器)，您可能需要在主机配置 (DNS) 级别处理它。

我们已经将主题和提供者目录从独立/配置/主题和独立/配置/提供程序到主题和提供商分别。 如果您添加了自定义主题和提供程序，则需要将它们移动到新位置。 您还需要更新keycloak-server.json因为它因此而改变了。

以前，如果您已将我们的SAML或OIDC Keycloak子系统适配器安装到WildFly或JBoss EAP中，无论您是否使用Keycloak，我们都会自动将Keycloak客户端jar包含到每个应用程序中。 如果您为该适配器打开了Keycloak身份验证 (通过子系统或web.xml中的auth-method)，则这些库现在仅添加到您的部署中

客户注册服务端点已从{领域名称}/客户端到{领域名称}/客户端-注册。

在OpenID Connect身份验证响应中，我们用来将会话状态返回为会话状态根据规范，这是不正确的，已重命名为会话状态。

1.2年，我们弃用了许多与OpenID Connect规范不一致的端点，这些端点现在已被删除。 这也适用于在1.8中替换为新的introspect端点的validate令牌端点。

template.ftl中的反馈已被移动，格式略有变化。

我们的大多数模块和源代码已合并为两个maven模块: keycloak-server-spi和keycloak-services。 SPI接口在server-spi中，实现在keycloak-services中。 所有与JPA相关的模块都已合并到keycloak-model-jpa下。 mongo和Infinispan在模块keycloak-model-mongo和keycloak-model-infinispan下也是如此。

要插入安全攻击向量，对于支持它的平台 (Tomcat 8，Undertow/WildFly，Jetty 9)，Keycloak OIDC和SAML适配器将在登录后更改会话id。 您可以关闭此行为检查适配器配置开关。

Keycloak SAML SP客户端适配器现在需要一个特定的端点，/saml向你的国内流离失所者登记。

在以前的版本中，我们随附了具有默认密码的默认管理员用户，现在已将其删除。 如果要进行1.8的新安装，则必须首先创建管理员用户。

为了增加对OAuth2规范的更多合规性，我们添加了一个新的端点用于令牌内省。 新的端点可以在/领域/{领域名称}/协议/openid-connect/token/introspect它完全基于RFC-7662。

的/领域/{领域名称}/协议/openid-连接/验证端点现在已弃用，我们强烈建议您尽快移至新的自省端点。 进行此更改的原因是RFC-7662提供了更标准和更安全的自省端点。

现在可以从OpenID Connect提供程序的配置中获得新的令牌内省URL/realms/{realm-name}/。知名/openid-configuration。 在那里你会找到一个有名字的索赔令牌 _ 反省 _ 端点在回应中。 仅机密客户允许调用新的端点，这些客户端通常将充当资源服务器并查找令牌元数据，以便执行本地授权检查。

为了增加对OpenID Connect规范的更多合规性，我们在管理控制台 “客户端设置” 页面中添加了标志，您可以在其中启用/禁用各种OpenID Connect/OAuth2流 (标准流、隐式流、直接访问授权、服务帐户)。 作为其中的一部分，我们有直接访问赠款(对应于OAuth2资源所有者密码证书授予) 默认情况下，新客户端禁用。

从以前版本迁移的客户端具有直接访问赠款启用，只要他们有标志仅直接赠款上。 的仅直接赠款标记被删除，就像您启用直接访问授权并禁用两个标准 + 隐式流一样，您将获得相同的效果。

我们还添加了内置客户端管理-cli每个领域。 这个客户有直接访问赠款启用。 因此，如果您使用的是Admin REST API或Keycloak admin-client，则应更新配置以使用管理-cli而不是安全-管理-控制台由于后者默认情况下不再启用直接访问授权。

在这个版本中，我们添加了首次经纪人登录,它允许您指定当通过Identity provider (或Social provider) 登录新用户时应该做什么，但是尚无链接到该社交帐户的Keycloak用户。 作为这项工作的一部分，我们添加了选项首次登录流程到身份提供程序，您可以在其中指定流，然后可以在身份验证管理控制台中的选项卡。

我们还删除了该选项首次登录时更新配置文件从身份提供程序设置，并将其移动到审查档案认证器。 因此，一旦您指定了应该将哪个流用于您的身份提供者 (默认情况下，它是首次经纪人登录流)，你去身份验证选项卡，选择流程，然后在下面配置选项审查档案认证器。

web.xml中的表单错误页面将不再适用于客户端适配器身份验证错误。 您必须为各种HTTP错误代码定义一个错误页面。 如果要捕获并处理适配器错误情况，请参阅文档以获取更多详细信息。

接口本身和方法签名没有改变。 然而，行为存在一些变化。 我们补充说首次经纪人登录此版本中的流程和方法IdentityProviderMapper.importNewUser现在被称为首次经纪人登录流程完成。 所以如果你想在审查档案页面，您需要使用该方法预处理联邦实体而不是importNewUser。 您可以通过调用设置任何属性BrokeredIdentityContext.setUserAttribute这将在审查档案页。

旧版本的Keycloak允许多次重用刷新令牌。 Keycloak仍然允许这样做，但也有一个选择撤销刷新令牌禁止它。 选项在管理控制台的令牌设置下。 当使用刷新令牌获取新的访问令牌时，还包括新的刷新令牌。 启用选项后，下次刷新访问令牌时应使用此新的刷新令牌。 不可能多次重复使用旧的刷新令牌。

我们做了一些重组，并重命名了一些包。 它主要是关于重命名util类的内部包。 应用程序中使用的最重要的类 (例如AccessToken或KeycloakSecurityContext) 以及SPI仍然保持不变。 但是，您可能会受到影响，并且需要更新类的导入。 例如，如果您使用的是多租户和KeycloakConfigResolver，您将受到影响，例如，类HttpFacade被移动到不同的包中-它是组织。Keycloak。适配器。spi。HttpFacade现在。

我们在此版本中添加了对脱机令牌的支持，这意味着我们现在将 “脱机” 用户会话保留到数据库中。 如果您不使用离线令牌，则不会为您保留任何内容，因此您无需担心更多DB写入的性能较差。 但是，在所有情况下，您都需要更新独立/配置/keycloak-server.json并添加用户会话像这样:

如果希望将会话保留在Mongo中而不是经典的RDBMS中，请使用provider蒙戈相反。

Infinispan现在是默认且唯一的领域和用户缓存提供程序。 在非聚集模式下，使用本地Infinispan缓存。 我们还删除了自定义的内存缓存和无缓存提供程序。 如果您在keycloak-server.json mem或none中设置了realmCache或userCache，请删除它们。 由于Infinispan是唯一的提供程序，因此不再需要realmCache和userCache对象，可以将其删除。

Infinispan现在是默认且唯一的用户会话提供程序。 在非聚集模式下，使用本地Infinispan缓存。 我们还删除了JPA和Mongo用户会话提供程序。 如果您将userSession keycloak-server.json设置为mem，jpa或mongo，请删除它。 由于Infinispan是唯一的提供程序，因此不再需要userSession对象，可以将其删除。

对于希望提高用户会话持久性的任何人，可以通过使用多个所有者配置用户会话缓存或使用复制的缓存来实现。 也可以将Infinispan配置为持久缓存，尽管这会对性能产生影响。

在默认主题中，我们现在从注册页面和帐户管理中删除了联系方式。 管理控制台现在列出了所有用户属性，而不仅仅是联系特定属性。 管理控制台还可以向用户添加/删除属性。 如果要添加联系方式，请参考示例中包含的地址主题。

过去，默认情况下禁用了直接授予API (或资源所有者密码凭据)，并且存在在领域上启用它的选项。 现在，直接授予API始终处于启用状态，并且删除了为领域启用/禁用的选项。

数据库更改也很少。 请记住在升级之前备份您的数据库。

UserFederationProvider接口几乎没有小的变化。 升级到较新版本时，您可能需要同步您的实现，并升级一些方法，这些方法已更改签名。 更改确实很小，但是需要改善联盟的绩效。

继上一版本中进行的发行版更改之后，Keycloak的独立下载现在基于WildFly 9.0.0.Final。 这也会影响只能部署到WildFly 9.0.0.Final或JBoss EAP 6.4.0.GA的覆盖。 服务器不再支持WildFly 8.2.0.Final。

现在有3个独立的适配器下载，用于WildFly，JBoss EAP和JBoss AS7:

确保你抓住正确的。

您还需要更新standalone.xml，因为扩展模块和子系统定义已更改。 见保护应用程序和服务指南有关详细信息。

Keycloak现在有3次下载: 独立、覆盖和演示包。 该独立软件适用于生产和非JEE开发人员。 Overlay旨在将Keycloak添加到现有的WildFly 8.2或EAP 6.4安装中，并且主要用于开发。 最后，我们有一个演示 (或开发) 捆绑包，旨在开发人员开始使用Keycloak。 此捆绑包包含一个WildFly服务器，其中包括Keycloak服务器和适配器。 它还包含所有文档和示例。

此版本再次包含对数据库的许多更改。 最大的一个是应用程序和OAuth客户端合并。 请记住在升级之前备份您的数据库。

应用程序和OAuth客户端现在合并到客户。 管理控制台的用户界面更新，数据库也更新。 您来自数据库的数据应该自动更新。 之前设置的应用程序将转换为具有以下功能的客户端需要同意开关关闭，OAuth客户端将转换为客户端，打开此开关。

此版本包含对数据库的许多更改。 请记住在升级之前备份您的数据库。

的价值国际空间站访问和id令牌中的声明已从领域名称到领域网址。 这是OpenID Connect规范所要求的。 如果您使用的是我们的适配器，则无需更改，除非您一直在使用仅承载而没有指定身份验证-服务器-网址,您现在必须添加它。 如果您使用的是另一个库 (或RSATokenVerifier)，则需要在验证时进行相应的更改国际空间站。

为了符合OpenID Connect规范，身份验证和令牌端点已更改为具有单个身份验证端点和单个令牌端点。 根据规格响应类型和Grant _ 类型参数用于选择所需的流。 旧端点 (/领域/{领域名称}/协议/openid-连接/登录,/领域/{领域名称}/协议/openid-connect/授予/访问,/领域/{领域名称}/协议/openid-连接/刷新,/领域/{领域名称}/协议/openid-connect/access/代码) 现在已弃用，并将在以后的版本中删除。

主题的布局发生了变化。 目录层次结构曾经是类型/名称这现在改为名称/类型。 例如，名为日出用于部署到独立/配置/主题/登录/日出,现在移动到独立/配置/主题/日出/登录。 进行此更改是为了更容易将同一主题的不同类型的组放入一个文件夹中。

如果您过去将主题部署为JAR，则必须创建需要Java代码的自定义主题加载器。 这已经被简化为只需要一个纯文本文件 (META-INF/keycloak-themes.json) 来描述罐子中包含的主题。

以前是一个专用的索赔应用程序和OAuth客户端的管理控制台中存在选项卡。 这用于配置哪些属性应进入特定应用程序/客户端的访问令牌。 已删除，并替换为更灵活的协议映射器。

您不需要关心数据库从以前版本的迁移。 我们为RDBMS和Mongo做了迁移脚本，这应该确保为特定应用程序/客户端配置的声明将被转换为相应的协议映射器 (尽管在迁移到新版本之前备份数据库还是更安全的)。 同样适用于从以前版本导出的JSON表示。

我们重构了社交提供商SPI，并将其替换为身份经纪SPI，这更加灵活。 的社会管理控制台中的选项卡重命名为身份提供者tab。

同样，您不需要像声明/协议映射器一样关心从以前版本迁移数据库。 社交提供者的配置和与用户的 “社交链接” 都将转换为相应的身份提供者。

你唯一需要的行动就是改变允许重定向URI在特定第三方社交提供商的管理控制台中。 您可以首先转到Keycloak管理控制台，然后从配置身份提供程序的页面复制重定向URI。 然后，您可以简单地将其作为允许的重定向URI粘贴到第三方提供商的管理控制台 (即 Facebook管理控制台)。