spring-addons多租户架构指南如何让资源服务器动态接受任意Keycloak realm的Token【免费下载链接】spring-addonsAdditional Spring Boot auto-configuration for OAuth2 / OpenID REST项目地址: https://gitcode.com/gh_mirrors/sp/spring-addonsspring-addons是一款为 Spring Boot 应用提供 OAuth2 / OpenID 与 REST 自动配置的开源扩展库。在本文中我们将深入讲解spring-addons多租户架构的核心机制并手把手教你如何让资源服务器在运行时动态接受任意 Keycloak realm 签发的 Token无需修改一行配置即可接入新租户。这是一份面向 Spring 开发者的实战指南全程无需手动编写 SecurityFilterChain。什么是多租户架构一份资源服务器服务多家企业多租户Multi-tenancy是 SaaS 系统的标配同一套后端 API要为成百上千家客户企业提供服务而每家企业的用户身份与权限彼此隔离。在 OAuth2 / OIDC 的世界里租户隔离通常通过独立的 OpenID ProviderOP / issuer实现。以 Keycloak 为例它的realm领域就是天然的多租户隔离单元每个 realm 拥有独立的用户库、客户端、角色与密钥每个 realm 对应一个独立的 issuer 地址格式为${keycloak-host}/realms/{realm-id}Token 中的ississuer声明直接标明它由哪个 realm 签发对资源服务器而言信任哪些 issuer、如何根据iss决定安全上下文就是多租户架构的核心问题。静态多租户与动态多租户两种模式如何选spring-addons将多租户清晰地划分为两种场景模式适用场景配置方式静态多租户启动前已知全部可信 issuer在com.c4-soft.springaddons.oidc.ops数组中为每个 OP 写一组属性动态多租户运行期才新增 issuer如 B2B 新客户签约实现OpenidProviderPropertiesResolver接口运行时解析静态模式虽然简单但在B2B 场景下会有致命缺陷每当一家新公司订阅服务系统就要为其创建专属 issuer然后重启资源服务器才能生效——这在生产环境是不可接受的。spring-addons 动态多租户的价值正在于此应用启动后任意新增的 Keycloak realm 签发的 Token 都能被自动识别与信任。这正是本文教程resource-server_multitenant_dynamic所要解决的问题完整代码可参考 samples/tutorials/resource-server_multitenant_dynamic/。spring-addons 动态多租户实现原理OpenidProviderPropertiesResolver动态多租户的钥匙是spring-addons-starter-oidc中的一个扩展点接口OpenidProviderPropertiesResolver.java。它的职责非常单一根据 Token 中的声明claims解析出应该使用哪一组 OpenID Provider 配置属性。接口签名如下public interface OpenidProviderPropertiesResolver { OptionalOpenidProviderProperties resolve(MapString, Object claimSet); }Spring 容器启动时spring-addons-starter-oidc会自动扫描应用上下文中实现了该接口的 Bean。每当有请求携带 Token 进入资源服务器框架就会调用你的resolve方法用返回的OpenidProviderProperties完成 JWT 解码、验签与权限映射。 关键设计OpenidProviderProperties中的属性与ops数组中的配置项结构完全一致只是来源从静态配置文件变成了运行时解析。最快配置方法3 步让资源服务器动态接受任意 Keycloak realm 的 Token下面以官方教程 README.md 为蓝本演示完整的接入过程。依赖仅需在 pom 中加入spring-addons-starter-oidc见 pom.xml。第 1 步定义适用于所有 realm 的通用配置在application.yml中把iss配置为 Keycloak 的主机地址不含/realms/{realm-id}部分这样所有 realm 的 issuer 都以此为前缀scheme: http keycloak-port: 8080 keycloak-host: ${scheme}://localhost:${keycloak-port} com: c4-soft: springaddons: oidc: ops: - iss: ${keycloak-host} authorities: - path: $.realm_access.roles - path: $.resource_access.*.roles这里同时配置了Keycloak 角色到 Spring Security authorities 的映射$.realm_access.roles读取 realm 级角色$.resource_access.*.roles读取各客户端资源角色。第 2 步实现动态解析器核心代码创建配置类实现OpenidProviderPropertiesResolver。核心逻辑是取 Token 的iss声明只要它以前缀形式匹配配置中的 Keycloak 主机地址就认定该 realm 可信。完整实现见 WebSecurityConfig.javaConfiguration EnableMethodSecurity public class WebSecurityConfig { Component public class IssuerStartsWithOpenidProviderPropertiesResolver implements OpenidProviderPropertiesResolver { private final SpringAddonsOidcProperties properties; // ... 构造器注入属性配置 Override public OptionalOpenidProviderProperties resolve(MapString, Object claimSet) { final var tokenIss Optional.ofNullable(claimSet.get(JwtClaimNames.ISS)) .map(Object::toString) .orElseThrow(() - new RuntimeException(Invalid token: missing issuer)); return properties.getOps().stream().filter(opProps - { final var opBaseHref Optional.ofNullable(opProps.getIss()) .map(URI::toString).orElse(null); if (!StringUtils.hasText(opBaseHref)) { return false; } return tokenIss.startsWith(opBaseHref); }).findAny(); } } }这段代码的妙处在于无论 Keycloak 上新建多少个 realm只要 Token 的iss以http://localhost:8080开头即来自这台 Keycloak 服务器的任意 realm就会被接受。生产环境还可以改用更严格的模式匹配例如限定域名或路径层级。第 3 步在 Keycloak 中创建多租户客户端为每个租户realm创建自己的 OAuth2 客户端。以下图为例客户端需开启Client authentication机密客户端并正确配置重定向 URI各租户使用 authorization-code 流程获取 Token 后即可带着 Token 访问资源服务器。用测试验证动态多租户是否生效教程自带的单元测试覆盖了完整的鉴权逻辑参见 GreetingControllerTest.java。核心断言思路✅ 无 Token 请求 → 返回401 Unauthorized✅ 任意合法 realm 签发的 Token → 正常访问/greet✅ 携带NICE角色权限的 Token → 可访问受PreAuthorize(hasAuthority(NICE))保护的/nice你会发现整个测试过程中根本不需要为每个 realm 单独写任何配置。新增租户 在 Keycloak 里新建 realm资源服务器零改动。小结spring-addons 让动态多租户回归简单回顾整条链路✅零 SecurityFilterChain 代码——spring-addons-starter-oidc自动配置✅运行期动态信任——OpenidProviderPropertiesResolver按iss前缀匹配任意 Keycloak realm✅权限映射灵活——通过 JSON path 配置即可从 Keycloak 角色 claim 生成 authorities✅配置即隔离——新增租户无需重启服务天然适配 B2B SaaS 的按需签约场景如果你正在搭建多租户 SaaS 后端又苦于为每个租户维护一套安全配置不妨把spring-addons 动态多租户方案放进你的技术选型清单。想深入了解底层自动配置机制可以继续阅读 SpringAddonsOidcProperties.java或直接跑一遍教程样例感受动态多租户开箱即用的畅快体验 【免费下载链接】spring-addonsAdditional Spring Boot auto-configuration for OAuth2 / OpenID REST项目地址: https://gitcode.com/gh_mirrors/sp/spring-addons创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考