SAML single sign-on
This feature is included in the Business plan.
SAML-based Single Sign-On (SSO) gives members access to GitBook through an identity provider (IdP) of your choice.
GitBook easily integrates with your existing identity provider (IdP) so you can provide your employees with single sign-on to GitBook using the same credentials and login experience as your other service providers (such as Slack and Dropbox).
By using SSO, your employees will be able to log into GitBook using the familiar identity provider interface, instead of the GitBook login page. The employee’s browser will then forward them to GitBook. The IdP grants access to GitBook when SSO is enabled and GitBook's own login mechanism is deactivated. In this way, authentication security is shifted to your IdP and coordinated with your other service providers.
SAML SSO on GitBook is supported for all Identity providers, and works well with:
Azure
Google for Work / G Suite
Okta
OneLogin
Your company’s identity provider (IdP) must support the SAML 2.0 standard.
You must have administrative permission on the IdP.
You must be an organization admin to enable SSO for your GitBook Organization.
After configuring SSO on your IdP, you will be able to upload or enter metadata manually. When the setup is successful, administrators will see a confirmation dialog and the URL of the SSO login for end-users will be displayed. GitBook does not send announcement emails when set up is complete. It is the responsibility of the administrator to notify company employees (and convey the login URL to them) so they can access GitBook via SSO.
You will need to find three pieces of information to your organization settings:
A sign-in page URL (also called a login URL)
Identity Provider Issuer
An X.509 certificate
Tips: You can enter anything as a Provider Label, it'll be displayed on the login page for your company employees.
Most SAML 2.0 compliant identity providers require the same information about the service provider for set up. (GitBook is the service provider.) These values are specific to your GitBook organization and are available in the settings tab of the GitBook team where you want to enable SSO.
GitBook requires that the NameID contain the user’s email address. Technically we are looking for: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
GitBook also requires some attributes mapping:
Application Attribute | Category (Google G Suite) | User Field (Google G Suite) |
first_name | Basic Information | First Name |
last_name | Basic Information | Last Name |
To add end-users, create accounts for these users in the IdP. The first time each new user logs in to GitBook via the IdP, a GitBook account will be created for each of them via automatic IdP provisioning. The user will have access to organization resources as an organization member.
Tips: Set-up requires lower case email addresses. Do not use mixed case email addresses.
In the SSO settings, you can set a default role. This role will be applied to every new organization's members:
👀 Reader: read-only access to all spaces
✍ Writer: read and write access to all spaces
🎩 Admin: read, write and admin access
Tips: You can find more details about permissions 👉 here. Keep in mind that you can change the role of a user any time in the Team settings.
Removing an end-user from the IdP will prevent the user from being able to login to the corresponding GitBook account, but will not remove the account from GitBook. We advise removing the end-users account from the GitBook org associated with IdP as well.
🧠 Note: Automated de-provisioning is not yet supported, but we'll soon release a SCIM API.
For security reasons, users who signed up to an organization before the SSO was set up have to continue to log in normally. SSO will only benefit users who log in to an organization after the setup is complete. Admins could also ask prior SSO users to delete their account (or change their email) and then they should be able to login with SSO.
