SSO & SAML
Learn how to share your GitBook content via SSO & SAML
Control organization access with email domains or SAML single sign-on (SSO). Configure both in your organization’s Settings → Access.
Single sign-on via email domain
Add email domains to let people with matching verified email addresses join your organization when they sign in.
To configure email domains:
In the organization menu, click Settings.
Under Organization, select Access.
Under Allowed email domains, add each domain you want to allow, such as
mycompany.com.Under New members, choose the Default role for people who join automatically.
Only work email domains are accepted. Personal email domains, such as gmail.com, can’t be added.
SAML single sign-on
SAML SSO gives members access through your identity provider (IdP).
GitBook uses your IdP for member authentication. Organization admins can still sign in with another method. This prevents lockouts after an incorrect SSO configuration.
Prerequisites
SAML SSO is available on the Enterprise plan.
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 admin of the GitBook organization.
Set up SAML in GitBook
You must be an organization admin to configure SAML.
To configure SAML:
In the organization menu, click Settings.
Under Organization, select Access.
Under SAML, click Register identity provider and enter the details from your IdP.
Save the configuration, then share the SSO sign-in URL with your members.
GitBook doesn't send an announcement email after you save the configuration.
You need these details from your IdP:
Label — displayed on the sign-in page.
Entity ID.
Single Sign On URL.
X.509 certificate — include the complete certificate.
Set up the IdP
Most SAML 2.0-compliant IdPs need service provider details. In GitBook, open Settings → Organization → Access and find the values for your organization under SAML.
Copy those values into your IdP to finish the SAML configuration.
GitBook needs the NameID to contain the member’s email address. Use urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress for the NameID format. Many IdPs offer this format as EMAIL.
Custom attributes
GitBook reads these custom attributes from the SAML assertion when creating an account.
first_name
first_name and last_name fields will be combined to produce the display name for the user in GitBook
last_name
first_name and last_name fields will be combined to produce the display name for the user in GitBook
Creating end-user accounts
To add members, create accounts for them in your IdP. The first time a new member logs in to GitBook via the IdP, a GitBook account will be created for them via automatic IdP provisioning. The user will have access to organization resources as an organization member.
Removing accounts
Removing a member from the IdP will prevent the user from being able to sign in to the corresponding GitBook account, but will not remove the account from GitBook. We advise also removing the account from the GitBook organization.
Controlling access
Once you have set up SAML SSO, the onus is on the IdP to control who can access your GitBook account.
Security notice
GitBook never links an existing account to your identity provider on an admin's behalf. Only the account owner can link it, by signing in through your IdP.
If someone already has a GitBook account under the email address your IdP sends, signing in with SAML doesn't add them to your organization automatically. To give them access:
Invite them to your organization.
If Enforce SSO isn't enabled, invite them from Members in your organization's settings.
If Enforce SSO is enabled, use the
invitesAPI endpoint with"sso": true:
Ask them to sign in to GitBook with their existing account and open your organization. When GitBook prompts them, they sign in through your IdP, which links their account to your SSO.
The invite adds an existing account as a member straight away. The API response lists it under failedSSOEmails, because the account isn't linked to your IdP yet. Accounts created by the invite are linked immediately.
Alternatively, the person can delete their existing GitBook account, then sign in to your organization with SAML. GitBook creates a new account and adds it to your organization. Deleting an account removes its access to every other organization.
Last updated
Was this helpful?