Group

A Group is a set of Users, and a subject in an entity's Permissions. Granting a permission to a Group grants it to everyone in the Group, so access can follow teams in your org chart rather than individual people: when someone joins or leaves a team in your identity provider, their access in ConfigHub changes with it.

Groups come from your identity provider

Groups and their membership are managed in your identity provider, not in ConfigHub, so there is no API to create, rename, or delete a Group or to add people to one. When a User signs in, ConfigHub reads the groups in their token's groups claim, provisions a Group for any it hasn't seen before, and records the User's Groups in their GroupIDs. A Group therefore appears in ConfigHub only once one of its members has signed in.

A Group's Slug and DisplayName are taken from the identity provider's name for it, and its ExternalID is the identity provider's identifier for it.

Like Users, Groups are not scoped to an Organization. Groups in the identity provider span every Organization, so switching Organizations keeps the same Groups.

A User's membership is read at sign-in, so a change made in the identity provider takes effect in ConfigHub the next time that User signs in.

Viewing Groups

You can see only the Groups you belong to. A Group you are not in is reported as not found, so that its existence is not revealed.

cub group list
cub group get my-team

A User's Groups are also in the GroupIDs of their User:

cub user list --where "Username = 'user@example.com'" -o jq='.[].User.GroupIDs'

Granting permissions to a Group

Each category in an entity's Permissions holds Subjects, which can name Groups by ID in GroupIDs alongside Users in UserIDs. A member of the Group is allowed whatever the category allows, and grants to a User and to their Groups add up. See Authorization for the categories.

Name a Group you belong to in --permission as group:<slug or ID>:

cub space update payments-prod --patch --permission ViewChildren:group:my-team

To remove the grant, prefix it with -:

cub space update payments-prod --patch --permission -ViewChildren:group:my-team

Service accounts in Groups

A service account never signs in through the identity provider, so it is added to a Group in ConfigHub. Adding it gives it the Group's grants, so that automation can act as a member of a team. It is named as in --permission:

cub group add my-team serviceaccount:deploy-bot
cub group remove my-team serviceaccount:deploy-bot

An Organization admin or manager may change a Group's service accounts, and so may a member of the Group. Either way, Manage permission on the service account is also needed. A service account's Groups are read when it authenticates, so it picks up a change the next time it does.

Workers in Groups

A Worker's bot user also never signs in through the identity provider. Adding a Worker to a Group gives it the Group's grants:

cub group add-worker my-team platform-dev/release-bot
cub group remove-worker my-team platform-dev/release-bot

The Worker is named as <space>/<slug>, by ID, or by a slug only one Space holds. An Organization admin or manager may change a Group's Workers, and so may a member of the Group who has Manage permission on the Worker. Since only members can look a Group up by slug, an admin or manager who is not a member names the Group by ID. Adding a Worker that is already in the Group, or removing one that isn't, changes nothing.

A Worker's Groups are read when it authenticates, so it picks up a change the next time it does. A Worker keeps the Groups it was added to even when the person who added it leaves the Group in the identity provider.

See also the Group API reference and the cub group commands.