Skip to main content
Video tutorial · 1:27

User groups

A user group holds roles and resource grants. Every member of the group has them. Use groups when several people need the same access — a web team that manages the same certificates and targets, an operations group that may run deploys in two projects — instead of repeating the same roles and grants on every user.

Groups can also be linked to LDAP groups and to the groups of each SSO provider: at every sign-in a user joins the groups linked to the groups the directory or provider names and leaves the ones it is no longer in.

What a group is​

  • Organisation-wide. A group belongs to the organisation, like a user, and can hold roles in any of its projects. The page that manages groups is marked Global in the Settings menu.
  • Roles. A group takes roles exactly like a user: org-wide or in one project — an org-wide role counts like a user's own org-wide role, so an org-wide admin group lets its members manage users and settings, not only every project — and a project role covers either the Whole project or Only granted resources. A group can not hold the owner role — owner is always given to a user directly.
  • Grants. When a group's role in a project is limited to granted resources, the group gets grants there like a user does: a role on single resources, a role on every resource of a type, and May create.
  • Members. A user is a member when it was added by hand, when an LDAP or SSO sign-in added it, or several of these. Groups do not contain other groups.

How roles combine​

A member's own roles and the roles of every group it belongs to form one list. In each project the highest role wins, wherever it comes from. Each role keeps its own scope, so the result is the same rule as for a single user with two roles:

The user's own role in project PIts group's role in PResult in P
—operator, whole projectoperator on everything
viewer, whole projectadmin, only grantedviewer on everything; admin on what the group (or the user) was granted
admin, whole projectviewer, whole projectadmin on everything (the own role is higher)
viewer, only grantedadmin, whole projectadmin on everything (the group role is higher)
operator, only grantedoperator, only grantedoperator on what the user or the group was granted
— (org-wide viewer)admin in P, whole projectadmin in P, viewer in every other project

Grants combine too. On each resource the member has the highest of its own grant and its groups' grants; May create holds when the user or any of its groups has it. The effective project role still caps every grant: a member whose highest project role is operator acts as an operator on a resource it was granted admin on.

The Roles dialog in Settings → Users shows a user's groups and, under Through groups, the roles it has from them (read-only — change them on the group).

Managing groups​

Open Settings → Groups (organisation owner only).

  1. Add group — a name (1–100 characters, unique in the organisation regardless of case) and an optional description.
  2. Details — name, description, the LDAP groups linked to this group (see below), and one field per SSO provider with that provider's groups (see SSO groups).
  3. Members — add users by hand or remove them. Members added through LDAP are shown with an LDAP tag (through an SSO provider, with the provider's name) and cannot be removed here: the next sign-in would add them back. Change their LDAP groups, or the group's links, instead. A user can be a member both by hand and through LDAP; removing the hand-added membership then keeps the LDAP one.
  4. Roles and grants — the group's roles. After a role limited to Only granted resources is saved, its Grants button opens the group's grants in that project.

Grants to a group can also be given on each resource's Access view: the member picker lists groups (with a Group tag) whose role in the project is limited to granted resources.

ActionWho may do it
Create, rename, delete groups; edit members, roles and LDAP linksOrganisation owner
Edit a group's grants in a projectAn admin of the whole project (as for a user's grants). In the UI the group page is owner-only; others use the API.
Give a group a role on one resource (Access view)Whoever may edit that resource's access. A restricted admin cannot hand out more than its own role.

A group can only be granted resources in a project where it holds a role.

Linking LDAP groups​

On a group's Details tab, LDAP groups lists the LDAP group names that put a user in this group. At every successful LDAP sign-in:

  1. CertAutoPilot asks the directory for the user's groups (the LDAP page's Group Filter, reading the Group attribute — for example cn — from each group entry it finds).
  2. The user joins every group linked to one of those names (the comparison ignores case and surrounding spaces) and leaves every group it had joined through LDAP whose links no longer match.
  3. Members added by hand are never added or removed by this.

Several groups may be linked to the same LDAP group; the user then joins all of them.

A cn is only a name — link by DN for groups that grant much

A cn matches any group entry with that name under the Group Base DN. Whoever can create a group somewhere under that base (a delegated OU, self-service groups) can create one with the same name, join it, and receive what the linked CertAutoPilot group gives. For groups that hold admin roles, set the LDAP page's Group attribute to dn — the entry's full distinguished name, exactly as Test Group Filter lists it — and link that DN, or narrow the Group Base DN to an OU only trusted administrators can write to. The Group attribute applies to every link, so switching it means updating every group's LDAP groups.

A change that adds or removes a membership is written to the audit log as GROUP_MEMBERSHIP_SYNCED.

When nothing is synced. Memberships stay exactly as they are when:

  • the LDAP page has no Group Filter (the directory is not asked for groups);
  • the group lookup fails — the sign-in itself then fails too, as before;
  • the user signs in with a local password, or LDAP is turned off.

A user removed from an LDAP group therefore leaves the linked CertAutoPilot group at its next LDAP sign-in, not before — and an open session keeps refreshing itself without signing in again, so that can take a long time. A membership LDAP added cannot be removed by hand (the next sign-in would add it back), so to cut access deactivate the account (sign-in and session refresh stop at once; an access token already issued stays valid for up to 15 minutes); fix the directory as well. Removing a group's LDAP links (editing the group) removes every membership LDAP added to it at once — the way out when syncing has stopped (no Group Filter, LDAP turned off) and LDAP-added memberships would otherwise stay for good.

The Group attribute is read from the group entries

The Group attribute names the attribute of the group entry that carries its name — usually cn. An attribute that the group entries do not have (for example memberOf, which lives on user entries) yields no group names at all, and every sign-in then removes the user from all groups it joined through LDAP. Test it with the Group Filter's test on the LDAP page before linking groups: it lists the group names a sign-in would read and warns when the entries lack the attribute.

Default role for new LDAP users​

Settings → Sign-in → LDAP → New Users → Default role for new LDAP users decides what a user gets at its first LDAP sign-in:

  • Viewer (all projects) — the default and the behaviour of earlier versions: an org-wide viewer role.
  • None — only what its groups give — no role of its own. The user has exactly what its linked groups give; with no matching group it can sign in but sees no project.

The setting applies only when the account is created; existing users keep their roles. Roles you set later in Settings → Users are never changed by a sign-in.

Linking SSO provider groups​

Each SSO provider gets its own field on a group's Details tab (Keycloak groups, AD FS groups, …) — two providers of the same type are separate fields. List the values that provider sends in its groups claim or attribute. At every sign-in through that provider with Sync group memberships on, the user joins the groups linked to the values it sent and leaves the groups it had joined through that provider whose links no longer match. Memberships added by hand, through LDAP or through another provider are not touched.

  • Values are compared ignoring case and surrounding spaces.
  • Microsoft Entra ID sends group object IDs: link the IDs, not the display names.
  • When the provider sends no groups claim, the user is in no group there (identity providers leave the claim out then): the memberships this provider added are removed. Only a list the provider marks as incomplete (Entra ID group overage), or one with values that are not text, leaves memberships unchanged for that sign-in.
  • Moving an account to another sign-in method removes the memberships its old method added.
  • Deleting a provider removes its links from every group and the memberships it added.
  • In the API a provider's mappings use provider: "sso:<provider id>".

When access disappears​

EventWhat goes
A member is removed (by hand, or by an LDAP sign-in)The roles and grants it had only through that group — at its next request, without signing in again
A group is deletedIts roles, memberships and grants
A group loses its role in a projectIts grants in that project (unless it keeps an org-wide role; such grants then give nothing, see below)
A user is deletedIts memberships (and its own roles and grants)
A project is deletedEvery group role and group grant in it
A granted resource is deletedEvery grant on it, the groups' included

A deactivated user keeps its memberships; reactivating it restores the access they give.

A member's own grants stay when it leaves a group or the group loses its project role: without a role in the project they give nothing, and they apply again if the user regains one. Removing the user's own role in Settings → Users removes them in every project the user no longer reaches at all — a project it still reaches through a group keeps them.

A group's grants count only while the group's own role in the project is limited to granted resources. Grants a group kept after its role there became a whole-project (or org-wide) one give its members nothing, exactly like a user's grants after its role is switched back to Whole project.

What a member may do and which projects it sees are decided on every request, so a membership or group-role change applies at once.

Multi-node installs​

A node still running a version without groups ignores group roles and group grants: on that node a member has only its own roles, so access can only shrink there. Two LDAP exceptions: an LDAP sign-in served by such a node gives a new user the org-wide viewer role even when the default role is None, and does not sync groups; and saving the LDAP page there drops the default-role setting (it reads as Viewer again). A group cannot be given a role until every node runs a version with groups (the Groups page answers every node must run a version that supports groups…, API 409 CLUSTER_UPGRADE_REQUIRED): an older node gives every LDAP user without own roles the org-wide viewer role at sign-in, and that role stays after the upgrade, so a groups-only setup made earlier would see more than intended. Upgrade every node before relying on groups or the default role; check Settings → Users for org-wide viewer roles an older node added.

Troubleshooting​

An LDAP user is not added to the group​

Check, in order: the LDAP page has a Group Filter; Test Group Filter with the user's DN finds the group; the value in the group's LDAP groups equals the Group attribute of that entry (not its DN, unless the attribute holds the DN). The user must sign in again after you change the link.

Every LDAP sign-in removes the user from its groups​

The directory answers with no group names — usually the Group attribute is not an attribute of the group entries (see the warning above).

A member sees more than the group gives​

Its own roles count too, and the highest role wins. Open Settings → Users → Roles on the user: its own roles are at the top, the group ones under Through groups.

The Grants button on a group role is greyed out​

Save the role with Only granted resources first (Save roles).

API​

MethodPathPurpose
GET / POST/groupsList / create groups (owner)
GET / PATCH / DELETE/groups/{id}One group (name, description, external_mappings: [{provider, value}] — provider is ldap or sso:<provider id>)
GET / PUT/groups/{id}/membersMembers with sources; PUT {user_ids} replaces the hand-added members
GET / PUT/groups/{id}/rolesThe group's roles (owner is refused with 400)
GET/users/{id}/groupsA user's groups with the sources of each membership
GET/users/{id}/rolesroles (the user's own) and inherited (from groups, each with via_group)
GET / PUT/projects/{projectId}/groups/{groupId}/grantsOne group's grants in a project
PUT/projects/{projectId}/grants/{resourceType}/{resourceId}Entries accept {group_id, role} next to {user_id, role}
GET/projects/{projectId}/membersUsers and groups (kind: user | group) with their effective role and scope

Full details: API reference → User groups.

See also​

Video tutorial

Short, hands-on videos showing this feature working for real. English audio, English and Turkish subtitles. All video tutorials →

Groups and Resource Grants (Least Privilege)YouTube ↗