多租户模式下NestJS-Keycloak-Connect角色匹配错误求助

问题分析 #

从日志可见，用户的admin角色存在于realm_access.roles中，但nestjs-keycloak-connect的RoleGuard默认会检查客户端级角色（即resource_access下对应client的角色），而非Realm级角色，这就导致了明明有角色却提示匹配失败的问题。

解决方案 #

方案1：在@Roles装饰器中指定检查Realm级角色 #

修改控制器的@Roles配置，添加mode: RoleMode.REALM来明确要求检查Realm级角色：

import { Roles, RoleMode } from 'nestjs-keycloak-connect';

@Controller(':company')
@UseGuards(AuthGuard, RoleGuard)
export class CompanyController {
  @Get('/')
  @Roles({
    roles: ['admin'],
    mode: RoleMode.REALM // 指定检查Realm级角色
  })
  view(@Param('company') company: string) {
    return `your company is : ${company}`;
  }
}

方案2：全局配置默认检查Realm级角色 #

如果你的项目大部分接口都需要检查Realm级角色，可以在KeycloakModule的全局配置中设置默认的角色验证模式：

import { KeycloakModule, RoleMode } from 'nestjs-keycloak-connect';

@Module({
  imports: [
    KeycloakModule.register({
      // 其他Keycloak配置（如auth-server-url、realm、client-id等）
      roleValidationMode: RoleMode.REALM, // 全局默认检查Realm角色
    }),
  ],
})
export class AppModule {}

方案3：确认多租户Realm映射正确 #

多租户模式下，需确保每个请求对应的Realm配置正确，Token中的iss字段（如日志中的http://localhost:8080/realms/testrealm）与当前租户的Realm配置完全匹配，避免因Realm不匹配导致角色读取错误。

内容的提问来源于stack exchange，提问作者cybercoder