Groups 分组字段

CZL Connect 提供 groups 输出能力，用于表达用户在当前应用中的分组和基础权限。接入方可以直接消费该字段完成轻量权限控制、后台角色区分和业务等级映射。

如果应用已经有更复杂的会员、订阅、组织或资源权限体系，也可以继续在应用内部维护更细粒度的规则，再把 groups 作为上层分组输入。

适用场景

以下情况适合使用 groups：

• 您希望直接使用 CZL Connect 提供的分组做权限判断
• 您需要快速搭建一个轻量应用，没有独立的权限系统
• 您希望用一组稳定的分组值表达后台权限和业务等级

以下情况建议在 groups 之上补充应用自身规则：

• 应用已经有自己的会员或订阅体系
• 权限由组织、团队、项目、资源归属等业务规则决定
• 购买、续费、退款、到期等状态由应用自身维护

当前分组

CZL Connect 目前保留以下分组值：

• admin
• viewer
• t0
• t1
• t2
• t3
• t4
• t5

其中：

• admin 和 viewer 更偏向应用后台的管理权限
• t0 到 t5 更适合作为应用内的业务分层或等级映射

分组继承规则

groups 采用层级展开输出：

t0 -> t1 -> t2 -> t3 -> t4 -> t5 -> viewer -> admin

例如用户当前分组为 t3 时，输出可能包含：

{
  "groups": "t0,t1,t2,t3"
}

如果分组为 admin，则输出可能包含：

{
  "groups": "t0,t1,t2,t3,t4,t5,viewer,admin"
}

输出方式

groups 可能出现在以下位置：

• OAuth2 userinfo
• OIDC userinfo
• OIDC id_token

接入方可以直接消费这个字段进行分组判断，也可以把它映射到应用内部更细的权限体系。

接入建议

推荐做法如下：

1. 使用 groups 作为应用的标准分组输出
2. 将 admin / viewer 用于后台权限控制
3. 将 t0-t5 用于业务分层、功能等级或套餐映射
4. 如有更复杂的业务规则，再在应用内部补充细粒度权限判断

如果您已经有成熟的权限体系，推荐做法是：

• 使用 CZL Connect 完成登录和身份识别
• 将 sub、邮箱、头像等身份信息同步到应用
• 使用 groups 作为上层分组输入
• 在应用内部继续判断会员、角色和资源访问权限

读取示例

JavaScript

function hasGroup(userGroups, requiredGroup) {
  if (!userGroups) return false;
  return userGroups.toLowerCase().split(',').includes(requiredGroup.toLowerCase());
}

Go

func hasGroup(userGroups string, requiredGroup string) bool {
    if userGroups == "" {
        return false
    }

    for _, group := range strings.Split(strings.ToLower(userGroups), ",") {
        if group == strings.ToLower(requiredGroup) {
            return true
        }
    }

    return false
}

最佳实践

• 优先为每个用户分配明确的分组，而不是依赖应用侧猜测
• admin / viewer 适合后台权限，t0-t5 适合业务分层
• 不要把购买状态、订阅状态直接硬编码到固定的 t0-t5
• 如需复杂权限控制，请在应用自身维护角色、套餐和授权规则，并与 groups 做清晰映射