How to use the AWS Cognito Integration for Visitor Authentication

This page describes how to use the AWS Cognito integration to publish your space behind Visitor Authentication

Installing the Cognito integration

Navigate to integrations within the GitBook app, select Visitor Authentication as the category, and install the AWS Cognito integration. You may need to install it in your organization and then on your selected space.

Once you've installed it on your space, go to configuration and make a note of the Callback URL right above the Save button. We will need it to set up Cognito.

Setting up Cognito

Go to your desired User Pool in Cognito, and click on App integration. Make a note of the Cognito domain, we will need it to configure the integration.

Scroll to the bottom and click "Create app client". For the app type, select "Confidential client." Scroll down to Hosted UI settings. In allowed Callback URLs, enter the Callback URL you got from GitBook upon installing the integration on a space.

Scroll further down to "OAuth 2.0 grant types"- make sure "Authorization code grant" is selected.

For "OpenID connect scopes", make sure OpenID is selected.

Scroll down and click "Create app client".

Click on the created app client and make a note of the Client ID and Client Secret.

Configuring the integration

Open up the Cognito integration's configuration screen for the space you installed the integration on.

It should look like the following image:

For Client ID, Cognito Domain, and Client Secret, paste in the values you got from Cognito.

Hit Save.

Now, in GitBook, open the Share modal (top right of the screen) for your space, and click "Share to an audience", and then enable the "Publish with Visitor Authentication" toggle. Choose the Cognito integration as your backend for Visitor Authentication, hit Save, and you're done! The space is now published behind Visitor Authentication controlled by Cognito. To try it out, copy the link where the space is published (you can get this from the Share modal- click "Copy published link") and open the link in a new tab. You will be asked to sign in with AWS Cognito, which confirms that your space is published behind Visitor Authentication.