多租户系统中如何从OpenID Connect SSO提供商映射角色？

一、是否存在多租户角色的标准OIDC声明？ #

OIDC核心规范并未定义专门的租户特定角色标准声明，但行业内有通用的实践方案：

• 通用roles声明：多数SSO提供商支持在ID令牌或用户信息中返回roles字段，但默认是扁平数组，不带租户上下文，需要自行扩展格式（比如"tenantA:Admin"）。
• groups声明：可用来传递租户与角色的组合，比如将用户所属的租户角色组命名为tenantA_Admin，后端解析时拆分出租户和角色。
• 自定义私有声明：OIDC允许使用带域名前缀的自定义声明（避免与标准声明冲突），例如https://your-platform.com/claims/tenant-roles，结构设计为数组：

  {
    "https://your-platform.com/claims/tenant-roles": [
      {"tenantId": "tenant_001", "role": "Admin"},
      {"tenantId": "tenant_002", "role": "Org-Reader"}
    ]
  }
  

二、如何从OIDC响应中获取并映射角色？ #

按以下步骤实现：

1. 确定角色存储位置
   • 优先从ID令牌提取：后端无需额外调用接口，直接解析ID令牌的payload即可获取角色信息。
   • 若角色仅存在于用户信息端点：后端需使用访问令牌调用SSO的/userinfo接口，从返回结果中提取角色。
2. 解析租户与角色的关联关系
   • 若使用扁平格式（如["tenantA-Admin", "tenantB-User"]）：通过字符串分割（按-或:）提取租户ID和角色值。
   • 若使用自定义结构化声明：直接解析数组，匹配当前请求的租户ID（可从登录时的租户选择、域名或请求参数获取），取出对应角色。
3. 映射到平台角色
   • 建立映射规则表，统一SSO角色与平台角色的对应关系，例如：
     • SSO的admin → 平台Admin
     • SSO的user → 平台User
     • SSO的org_reader → 平台Org-Reader
   • 验证角色合法性：确保SSO返回的角色属于平台允许的三种角色，非法角色直接拒绝认证。
4. 存储会话权限
   • 将解析后的租户ID+角色存入后端会话（如Redis、数据库），后续请求直接从会话读取权限，无需重复解析令牌。

三、多租户角色分配的最佳实践 #

• 强制结构化角色声明：避免使用无上下文的扁平角色数组，统一采用租户+角色的结构化格式，减少歧义。
• 绑定租户上下文：用户登录时必须明确指定租户（如登录页面选择租户、子域名区分租户），后端仅加载当前租户的角色权限。
• 控制令牌大小：仅传递当前租户的角色信息，不要将用户所有租户的角色都塞进令牌，避免令牌过大影响性能。
• 严格验证令牌：后端必须验证令牌的签名、issuer、过期时间，同时校验自定义声明的格式和角色合法性，防止篡改。
• 同步角色变更：在用户每次登录时同步SSO的角色信息，或提供手动同步入口，确保平台权限与SSO保持一致。

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