第 5 章 迁移由 Red Hat Single Sign-On 7.6 保护的应用程序
Red Hat build of Keycloak 引入了对应用程序如何使用一些 Red Hat Single Sign-On 7.6 Client Adapters 的关键更改。
除了不再发布一些客户端适配器外，红帽构建的 Keycloak 还引进了修复和改进，影响客户端应用程序如何使用 OpenID Connect 和 SAML 协议。
在本章中，您将找到解决这些更改并迁移应用程序以与红帽构建的 Keycloak 集成的说明。
5.1. 迁移 OpenID Connect 客户端
从此红帽构建的 Keycloak 发行版本开始，以下 Java Client OpenID Connect Adapters 不再发布
- Red Hat JBoss Enterprise Application Platform 6.x
- Red Hat JBoss Enterprise Application Platform 7.x
- Spring Boot
- Red Hat Fuse
与首次发布这些适配器时，OpenID Connect 现在广泛在 Java 生态系统中可用。此外，通过使用技术堆栈中提供的功能（如应用服务器或框架）来实现更好的互操作性和支持。
这些适配器已达到其生命周期，且只在 Red Hat Single Sign-On 7.6 中提供。强烈建议您寻找替代方案，使应用程序与 OAuth2 和 OpenID 连接协议的最新更新保持更新。
5.1.1. OpenID Connect 协议和客户端设置的主要变化
5.1.1.1. 访问类型客户端选项不再可用
当您创建或更新 OpenID Connect 客户端时，Access Type 不再可用。但是，您可以使用其他方法来实现此功能。
- 要达到 Bearer only 功能，请创建一个没有身份验证流的客户端。在客户端详情的 Capability config 部分中，确保未选择任何流。客户端无法从 Keycloak 获取任何令牌，这等同于使用 Bearer 只能访问类型。
- 要实现 公共 功能，请确保为这个客户端禁用客户端身份验证，并且至少启用一个流。
- 要实现 机密 功能，请确保为客户端启用客户端身份验证，并且至少启用一个流。
布尔值标志 bearerOnly 和 publicClient 仍然存在于客户端 JSON 对象上。在通过 admin REST API 创建或更新客户端时，或者通过部分导入或域导入导入此客户端时，可以使用它们。但是，这些选项在管理控制台 v2 中不直接提供。
5.1.1.2. 有效重定向 URI 验证方案的更改
如果应用程序客户端使用非 http (s)自定义方案，则验证现在要求一个有效的重定向模式明确允许该方案。允许自定义方案的模式示例为 custom:/test, custom:/testAttr 或 custom:。为了安全起见，一般模式（如 * ）不再涵盖它们。
5.1.1.3. 支持 OpenID Connect Logout 端点中的 client_id 参数
支持 client_id 参数，它基于 OIDC RP-Initiated Logout 1.0 规范。此功能可用于检测在无法使用 id_token_hint 参数时，应该使用哪些客户端进行 Post Logout Redirect URI 验证。当在没有参数 id_token_hint 的情况下使用 client_id 参数时，仍需要向用户显示 logout confirmation 屏幕，因此如果他们不希望向用户显示 logout 确认屏幕，则鼓励客户端使用 id_token_hint 参数。
5.1.2. 有效的 Post Logout Redirect URI
Valid Post Logout Redirect URIs 配置选项添加到 OIDC 客户端，并与 OIDC 规格一致。您可以使用不同的重定向 URI 在登录和注销后进行重定向。用于 Valid Post Logout Redirect URI 的值 + 表示注销使用与 选项 Valid Redirect URI 指定的相同重定向 URI 集。由于向后兼容性，从之前的版本迁移时，这个更改也会与默认行为匹配。
5.1.2.1. userinfo 端点更改
5.1.2.1.1. 错误响应更改
UserInfo 端点现在返回与 RFC 6750 完全兼容的错误响应(OAuth 2.0 授权框架： Bearer Token Usage)。错误代码和描述（如果可用）作为 WWW-Authenticate challenge 属性而不是 JSON 对象字段提供。
根据错误条件，响应将如下：
如果没有提供访问令牌：
401 Unauthorized WWW-Authenticate: Bearer realm="myrealm"
如果同时使用几种方法来提供访问令牌（如 Authorization 标头 + POST access_token 参数），或者 POST 参数会被重复：
400 Bad Request WWW-Authenticate: Bearer realm="myrealm", error="invalid_request", error_description="..."
如果访问令牌缺少
openid范围：403 Forbidden WWW-Authenticate: Bearer realm="myrealm", error="insufficient_scope", error_description="Missing openid scope"
如果无法为 UserInfo 响应签名/加密解析加密密钥：
500 Internal Server Error
如果令牌验证错误，则返回
401 Unauthorized和invalid_token错误代码。这个错误包括用户和客户端相关的检查，并实际捕获所有剩余的错误情况：401 Unauthorized WWW-Authenticate: Bearer realm="myrealm", error="invalid_token", error_description="..."
5.1.2.1.2. 对 UserInfo 端点的其他更改
现在，访问令牌需要具有 openid 范围，它被 UserInfo 视为特定于 OpenID Connect 而非 OAuth 2.0 的功能。如果令牌中缺少 openid 范围，则请求将被拒绝为 403 Forbidden。请参阅上一节中。
userinfo 现在检查用户状态，并在用户被禁用时返回 invalid_token 响应。
5.1.2.1.3. 更改服务帐户客户端的默认客户端 ID 映射器。
Service Account 映射器已更改。Client 的默认客户端 IDToken Claim Name 字段值已从 clientId 改为 client_id。client_id 声明符合 OAuth2 规格：
clientId userSession note 仍然存在。
5.1.2.1.4. 在 OAuth 2.0/OpenID Connect Authentication Response 中添加是参数
RFC 9207 OAuth 2.0 Authorization Server Issuer Identification 规格添加 该参数 在 OAuth 2.0/OpenID Connect Authentication Response 中用于实现安全授权响应。
在过去的版本中，我们没有这个参数，但现在红帽构建的 Keycloak 会默认添加这个参数。但是，一些 OpenID Connect / OAuth2 适配器，特别是较旧的红帽构建的 Keycloak 适配器，这个新参数可能会出现问题。例如，参数在成功向客户端应用程序进行身份验证后始终存在于浏览器 URL 中。
在这些情况下，禁用向身份验证响应添加 iss 参数可能很有用。这可以针对管理控制台中的特定客户端完成，具体位于带有 OpenID Connect 兼容性模式 的部分中的客户端详细信息。您可以启用 Exclude Issuer From Authentication Response，以防止将 iss 参数添加到身份验证响应中。
