第 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 客户端
从此 Red Hat build of 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 Only 访问类型。
- 要实现 公共 功能，请确保为此客户端禁用客户端身份验证，并且至少启用了一个流。
- 要实现 机密 功能，请确保 为客户端 启用客户端身份验证，并且至少启用了一个流。
客户端 JSON 对象上仍然存在 bearerOnly 和 publicClient。它们可用于在管理员 REST API 创建或更新客户端时使用，或者在通过部分导入或域导入时导入此客户端时使用。但是，这些选项不能直接在管理控制台 v2 中提供。
5.1.1.2. 验证有效重定向 URI 的方案的更改
如果应用程序客户端使用非 http (s)自定义方案，验证现在需要有效的重定向模式明确允许该方案。允许自定义方案的示例模式为 custom:/test, custom:/test decisions 或 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 确认屏幕，则鼓励客户端使用 id_token_hint 参数。
5.1.2. 有效的 Post Logout Redirect URI
Valid Post Logout Redirect URIs 配置选项添加到 OIDC 客户端，并与 OIDC 规格保持一致。您可以在登录和注销后，使用一组不同的重定向 URI 进行重定向。用于 Valid Post Logout Redirect URIs 的值 + 表示注销使用与 Valid Redirect URIs 选项的相同集合。由于向后兼容性，这个更改还与从以前的版本迁移时的默认行为匹配。
5.1.2.1. userinfo 端点更改
5.1.2.1.1. 错误响应更改
UserInfo 端点现在返回与 RFC 6750 完全兼容的错误响应(OAuth 2.0 Authorization Framework: 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. 更改 Service Account 客户端的默认客户端 ID 映射器。
Service Account 映射程序已被更改。Client 的默认客户端 ID令牌 Claim Name 字段值已从 clientId 改为 client_id。client_id 声明符合 OAuth2 规格：
clientId userSession 备注仍然存在。
5.1.2.1.4. 向 OAuth 2.0/OpenID Connect Authentication Response 中添加的 iss 参数
RFC 9207 OAuth 2.0 Authorization Server Issuer Identification 规格在 OAuth 2.0/OpenID Connect Authentication Response 中添加了参数，以实现安全授权响应。
在以前的版本中，我们没有这个参数，但红帽构建的 Keycloak 默认会添加这个参数，如规格的要求。但是，一些 OpenID Connect / OAuth2 适配器（特别是旧的红帽构建的 Keycloak 适配器）可能会遇到这个新参数的问题。例如，在客户端应用成功身份验证后，参数始终存在于浏览器 URL 中。
在这些情况下，将 iss 参数添加到身份验证响应中可能会很有用。这可以在 Admin Console 中的客户端详情中针对带有 OpenID Connect 兼容性模式 的特定客户端完成。您可以启用 Exclude Issuer From Authentication Response，以防止将 iss 参数添加到身份验证响应中。
