Okta Setup

How to setup GitBook as an Okta SAML 2.0 app

Our SSO setup flow was modeled after GSuite's SSO flow, so admittedly the setup flow is a bit awkward/tricky with Okta.

We're working on improvements to the flow and are looking into registering GitBook on Okta's app marketplace, but in the meantime this guide should help you get setup and running.

Overview

Here's what you need to at a high level:

  1. Setup a new SAML 2.0 app in Okta, go through the process putting in "invalid" ACS urls (that's the awkward part)

  2. Get the IDP info from Okta to configure SAML on GitBook

  3. Return to Okta to redo the setup (step 1) now that GitBook shows the URLs you need to paste into Okta's app setup.

1. Setup SAML 2.0 app on Okta

Go to your Okta admin dashboard, then click Create New App :

Then create a SAML 2.0 App:

When prompted to put in the Single-Sign-on URL just pasted in https://www.example.com (or any other URL), we'll fix this later.

2. Configure SAML on GitBook

After going through the setup process for Okta, you should see a page like this:

That will show you a page with all the info to fill in this form on GitBook:

3. Return to Okta

Now go back to your Okta admin dashboard and reconfigure the app we setup in the 1st step.

Paste in the ACS URL that GitBook now shows in your SSO settings.

Now you should be all set 🎉

If you encounter any issue or need help setting this up, please reach out to support@gitbook.com