Skip to content

Commit 4a17e10

Browse files
danciaclaradanciaclara
authored
Merge pull request #478 from makeplane/update-idp-group-sync
Update IdP Group Sync
2 parents ddd4dce + 66be8e2 commit 4a17e10

1 file changed

Lines changed: 98 additions & 48 deletions

File tree

‎docs/authentication/group-sync.md‎

Lines changed: 98 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,90 +1,140 @@
11
---
2-
title: Manage project access with IdP groups
3-
sidebar_label: Group Sync
2+
title: Sync access with IdP groups
3+
sidebar_label: IdP Group Sync
44
hide_title: true
5-
description: Automatically provision project memberships based on identity provider groups.
5+
description: Automatically provision workspace roles, project memberships, and private collection access from your identity provider's groups.
66
---
77

88
# IdP Group Sync <Badge type="warning" text="Enterprise Grid" />
99

10-
:::info
11-
Group syncing is currently available on the self-hosted Commercial Edition and supports OIDC only. SAML and LDAP support is coming soon.
10+
:::info Availability
11+
Group syncing is currently available on the self-hosted Commercial and Airgapped Editions.
1212
:::
1313

14-
Group syncing lets workspace admins map identity provider groups to Plane projects. When users sign in via OIDC, their project memberships are provisioned and kept in sync automatically.
14+
IdP Group Sync lets workspace admins map identity provider groups to access in Plane. When a user signs in through SSO, Plane reads the groups on their identity and automatically grants the matching access, then keeps it in sync as their group membership changes in your IdP.
15+
16+
You can map groups to three things:
17+
18+
- **Workspace roles** - the role a user gets in the workspace.
19+
- **Project access** - membership and role in specific projects, or in all projects.
20+
- **Private collection access** - view, comment, or edit access to private wiki collections.
21+
22+
This removes manual onboarding and offboarding: access follows group membership in your identity provider.
23+
24+
## Supported providers
25+
26+
Group sync works with all three SSO methods. One provider is active per workspace at a time.
27+
28+
| Provider | Sync on login | Scheduled offline sync |
29+
| -------- | ------------- | ---------------------- |
30+
| **OIDC** | Yes | Yes |
31+
| **SAML** | Yes | No |
32+
| **LDAP** | Yes | Yes |
33+
34+
SAML groups are only present in the login assertion, so SAML syncs at login only. It does not support the scheduled offline sync. OIDC and LDAP can fetch groups from the provider on a schedule as well as at login.
1535

1636
## Prerequisites
1737

18-
- OIDC SSO configured and working
19-
- Identity provider configured to send group claims in the OIDC token
38+
- SSO configured and working with OIDC, SAML, or LDAP.
39+
- Your identity provider configured to send groups (as a claim for OIDC, an assertion attribute for SAML, or an attribute for LDAP).
2040

2141
## Turn on group syncing
2242

2343
1. Navigate to **Workspace Settings → Group syncing**.
2444
2. Toggle on **Enable group syncing**.
2545

26-
![Group syncing](https://media.docs.plane.so/sso/enable-group-sync.webp#hero)
46+
![Group syncing](https://media.docs.plane.so/sso/enable-idp-group-sync.webp#hero)
2747

2848
## Configure sync settings
2949

30-
| Setting | Description | Default |
31-
| ----------------------- | ---------------------------------------------------------------------------- | --------------------- |
32-
| **Sync on login** | Update group membership and project access when a user signs in | Enabled (recommended) |
33-
| **Offline sync** | Run sync automatically every six hours, without waiting for users to log in | Disabled |
34-
| **Auto remove** | Automatically remove users from projects when they no longer match the group | Disabled |
35-
| **Group attribute key** | The identity provider attribute used to identify and sync user groups | `groups` |
50+
Under **Configure group sync**, set how syncing behaves.
51+
52+
| Setting | Description | Default |
53+
| -------------------------- | --------------------------------------------------------------------------------------------------------- | -------- |
54+
| **Sync on login** | Update the user's group membership and access when they sign in | Enabled |
55+
| **Offline sync** | Run a sync every two hours automatically, without waiting for users to log in (OIDC and LDAP only) | Disabled |
56+
| **Auto remove** | Remove users from the workspace and projects when no group matches | Disabled |
57+
| **Group attribute key** | The identity provider attribute that carries the user's groups | `groups` |
58+
| **Default workspace role** | The role assigned to users who are auto-added to the workspace but don't match any workspace role mapping | - |
3659

37-
Set **Group attribute key** to match exactly what your IdP sends. Common values include `groups` (default), `roles`, `memberOf`, or `custom:groups`.
60+
Set **Group attribute key** to match exactly what your IdP sends. Common values are `groups` (default), `roles`, `memberOf`, or `custom:groups`.
3861

3962
## Add group mappings
4063

41-
Each mapping links an IdP group to a Plane project with a default role.
64+
Group syncing has three kinds of mapping, each in its own section on the page. Each mapping starts from an **IdP group name** and grants access when a user is in that group. A user in several matching groups always receives the **highest** role or access across them.
65+
66+
### Workspace role mapping
67+
68+
Maps a group to a workspace role.
4269

43-
1. Under **Group mapping**, click **Add new group sync**.
70+
1. Under **Workspace role mapping**, click **Add group sync**.
4471
2. Enter the **User group** name exactly as it appears in your IdP.
45-
3. Select the **Project** to grant access to.
72+
3. Select the **Workspace role**.
73+
4. Click **Add**.
74+
75+
If a user is auto-added to the workspace but matches no workspace role mapping, they get the **Default workspace role** from the settings above.
76+
77+
### Project role mapping
78+
79+
Maps a group to one or more projects with a project role.
80+
81+
1. Under **Project role mapping**, click **Add group sync**.
82+
2. Enter the **User group** name.
83+
3. Choose the target:
84+
- Select a **Project**, or
85+
- Turn on **Apply to all projects** to map the group to every project in the workspace, including projects created later.
4686
4. Choose the **Project role**: Admin, Member, or Guest.
4787
5. Click **Add**.
4888

49-
![Add new group sync](https://media.docs.plane.so/sso/add-new-group-sync.webp#hero)
89+
### Private collection access mapping
90+
91+
Maps a group to a private wiki collection with an access level. Collections group your workspace's wiki pages; only **private** collections have membership, so only private collections can be mapped.
92+
93+
1. Under **Private collection access mapping**, click **Add group sync**.
94+
2. Enter the **User group** name.
95+
3. Select the **Private collection**.
96+
4. Choose the **Collection access**: View, Comment, or Edit.
97+
5. Click **Add**.
98+
99+
## What happens on sync
100+
101+
When a user signs in (or during an offline sync), Plane resolves their groups and applies access in order: workspace role first, then project access, then private collection access.
102+
103+
| Situation | Result |
104+
| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
105+
| User is not in the workspace but matches a mapped group | Added to the workspace with the matching workspace role, or the default workspace role, then granted the mapped project and collection access |
106+
| User is in the workspace and matches a project or collection mapping | Granted or updated to the mapped access |
107+
| User matches several groups mapping to the same target | Receives the highest role or access across the matches |
108+
| User is in the workspace but matches no mapping | No access is added. With Auto remove on, synced access is revoked (see below) |
50109

51-
Repeat for additional group-to-project mappings.
110+
## When users leave groups
52111

53-
## What happens on login
112+
Removal only happens when **Auto remove** is enabled. When a user no longer matches a mapping, Plane revokes the access that group sync granted, in this order: projects, private collections, and finally the workspace.
54113

55-
| Condition | Result |
56-
| ------------------------------------------------------ | ------------------------------------------------------------- |
57-
| User not in workspace, but in a mapped group | Added to workspace as Member, then added to mapped project(s) |
58-
| User in workspace, in mapped group, not yet in project | Added to project with configured role |
59-
| User in workspace, in mapped group, already in project | No change |
60-
| User in workspace, not in any mapped group | No action |
114+
Group sync only ever touches access it granted itself. The following are never changed or removed by syncing:
61115

62-
## When users leave IdP groups
116+
- **Manually granted access.** Workspace roles, project memberships, and collection access that an admin assigned by hand are never modified or removed. Only access added by group sync is subject to auto-remove.
117+
- **The last admin.** A user is never removed if they are the last admin of the workspace or of a project.
63118

64-
If a user is removed from an IdP group and **Auto remove** is enabled, they're removed from the corresponding project. They are never removed from the workspace.
119+
Manual roles are also never downgraded by syncing. If someone was manually made a project Admin, a group mapping for a lower role will not lower them.
65120

66-
**These users are never auto-removed**
121+
## Sync behavior and safeguards
67122

68-
- Users who were manually added to the project
69-
- Users who are the sole project admin
123+
- A user in multiple groups mapped to the same project, workspace, or collection gets the **highest** role or access among them.
124+
- **Manually assigned** roles and memberships are never overridden, downgraded, or auto-removed.
125+
- The **last admin** of a workspace or project is protected from removal.
126+
- A **workspace guest** cannot be granted a project Admin role through a mapping, even if a group maps to Admin.
127+
- Adding a paid workspace role through sync respects your seat limits.
128+
- **Sync errors never block sign-in.** If syncing fails, the user still logs in and the error is logged.
70129

71-
## Sync behavior
130+
## Common use cases
72131

73-
- Users in multiple groups mapped to the same project receive the highest role across all matching groups.
74-
- Roles assigned manually in Plane are never downgraded by group syncing.
75-
- Workspace guests cannot be assigned as project admins, regardless of group mapping.
76-
- Members manually invited to the project are never auto-removed.
77-
- Workspace membership is always preserved.
78-
- Sole project admins are protected from removal.
79-
- Sync errors never block user login.
132+
**New hire provisioning.** Map your `engineering` group to a Member role on all engineering projects (or use Apply to all projects). New engineers get access on their first sign-in with no admin action.
80133

81-
## Common usecases
134+
**Department scoping.** Map `product-team`, `design-team`, and `marketing-team` to their respective projects so people only see what is relevant to them.
82135

83-
**New hire provisioning**
84-
Map your `engineering` group to all engineering projects. New engineers get access on first login without admin intervention.
136+
**Workspace role assignment.** Map `leadership` to a higher workspace role and set a conservative Default workspace role, so most synced users land as Members while leads are elevated automatically.
85137

86-
**Department scoping**
87-
Map `product-team`, `design-team`, and `marketing-team` to their respective projects. Users only see what's relevant to them.
138+
**Wiki access control.** Map `security-team` to a private "Security runbooks" collection with Edit access, and `all-staff` to the same collection with View, so the right people can read and the right people can maintain it.
88139

89-
**Contractor offboarding**
90-
Map `contractors` to projects with Guest role and enable Auto remove. Access is revoked the moment they're removed from the IdP group.
140+
**Contractor offboarding.** Map `contractors` to projects with the Guest role and enable Auto remove. Access is revoked when they are removed from the IdP group, applied at their next login or at the next scheduled sync.

0 commit comments

Comments
 (0)