SCIM & directory sync
Auto-provision users and teams from your company directory with directory sync (backed by SCIM)
Directory sync allows you to automatically provision/deprovision users and teams from your company directory into your GitBook organization.
As users join your directory, they will be created and added to your GitBook organization.
You can also have teams in GitBook synchronize to your directory groups, and have all user memberships synchronize automatically.
Start by clicking setup directory sync from your organization settings SSO page.
You'll be taken through a setup process specific to your identity provider. Once the steps are complete, you'll be brought back to GitBook with directory sync enabled.
Once directory sync is setup, all synchronization is done automatically. As you make changes in your identity provider, those changes are reflected in GitBook.
You can synchronize your directory groups to GitBook teams. Once you've set up directory sync, click the link to configure your teams from the organization settings SSO page.
Each group you select will be synchronized to one team in GitBook. The name will be taken, and any members of the group will be synchronized as members of the team.
When a user is provisioned in GitBook, we use the following logic to determine their permission level in the organization:
- If the user has the
gitbookRoleattribute (case sensitive) in the identity provider set to a valid GitBook role (
read), we use that. If the
gitbookRoleattribute is set to
none, the user will not be provisioned into GitBook. Refer to your identity provider documentation for how to set custom attributes.
- If your organization has SAML enabled, we will default to the SAML default role.
- If we do not find a user-specific role, and if SAML is not enabled, the user will be added with the
Directory sync is designed to work with SAML single sign-on. When an organization has both SAML single sign-on and directory sync set up in the same organization:
- Any users who login with SAML will be linked to their appropriate user in the directory.
- Any users who are provisioned by the directory are required to log in with SAML.
When users and teams are provisioned through directory sync, the directory becomes the source of truth. You cannot change a user's name, e-mail address, or organization-level permission through the GitBook interface; it must all be done in the directory.
Users who are created via directory sync can only be members of that organization. If you have multiple GitBook organizations using the same directory sync, users will only be synced to one of the organizations.
If you require the same directory for multiple organizations, please get in touch with us.