Okta Setup

How to setup GitBook as an Okta SAML 2.0 app

🧠 Note: 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 and are looking into registering GitBook on Okta's app marketplace, but in the meantime, this guide should help you get set up 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.

Set up 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 paste in https://www.example.com (or any other URL), we will fix this later.

Configure SAML on GitBook

After going through the setup process for Okta, you should see the following page:‌

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

Return to Okta

Now go back to your Okta admin dashboard and reconfigure the app we set up 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 contact us 👋.