Groups Field

CZL Connect provides a groups output that expresses a user's groups and basic permissions in the current app. Your app can consume this field directly for lightweight access control, admin role separation, and business tier mapping.

If your app already has a more complex membership, subscription, organization, or resource permission system, you can keep maintaining finer-grained rules inside your app and use groups as a higher-level input.

When to Use

Use groups when:

• You want to make access decisions directly from the groups CZL Connect provides
• You need to build a lightweight app quickly and have no separate permission system
• You want a stable set of group values to express admin permissions and business tiers

Add your app's own rules on top of groups when:

• Your app already has its own membership or subscription system
• Permissions depend on business rules such as organization, team, project, or resource ownership
• Your app maintains the state of purchases, renewals, refunds, and expirations

Available Groups

CZL Connect currently reserves the following group values:

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

Of these:

• admin and viewer are intended for admin permissions in your app
• t0 to t5 are intended for business tiers or level mapping inside your app

Group Inheritance

groups is delivered as a JSON array of strings, expanded along the level hierarchy:

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

For example, if a user's group is t3, the output can include:

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

If the group is admin, the output can include:

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

Where to Read It

groups can appear in:

• OAuth 2.0 userinfo
• OIDC userinfo
• OIDC id_token

Your app can consume this field directly for group checks, or map it to a finer-grained permission system inside your app.

Integration Recommendations

We recommend the following:

1. Use groups as your app's standard group output
2. Use admin / viewer for admin permissions
3. Use t0-t5 for business tiers, feature levels, or plan mapping
4. If you have more complex business rules, add fine-grained permission checks inside your app

If you already have a mature permission system, we recommend:

• Use CZL Connect for sign-in and identity
• Sync identity information such as sub, email, and avatar into your app
• Use groups as a higher-level input
• Keep evaluating membership, roles, and resource access inside your app

Examples

JavaScript

function hasGroup(userGroups, requiredGroup) {
  if (!Array.isArray(userGroups)) return false;
  return userGroups.some((g) => g.toLowerCase() === requiredGroup.toLowerCase());
}

Go

func hasGroup(userGroups []string, requiredGroup string) bool {
    for _, group := range userGroups {
        if strings.EqualFold(group, requiredGroup) {
            return true
        }
    }

    return false
}

Best Practices

• Assign each user an explicit group instead of having your app guess
• Use admin / viewer for admin permissions and t0-t5 for business tiers
• Do not hard-code purchase or subscription state into fixed t0-t5 values
• For complex access control, maintain roles, plans, and authorization rules in your app, and map them to groups clearly