How to use Azure AD Integration for Visitor Authentication

This page describes how to use the Azure AD (now known as Microsoft Entra ID) integration to publish your space behind Visitor Authentication

There is a known limitation with the Azure integration where heading URL fragments will be removed upon authentication. The user will still land on the correct page, but will be taken to the top of the page instead of the heading in the URL. Once an user is authenticated this behavior will no longer occur during a session and the user would be directed to the correct heading.

This is due to a security measure put in place by Microsoft.

Setting up Entra

First, sign in to Entra platform. In the left sidebar, navigate to Identity > Applications > App registrations. You may need admin permissions to do this.

And click on New registration button in the screen that opens up. Name it appropriately.

Under Supported account types, select Accounts in this organizational directory only.

Click Register.

You should see a screen like the following

Go back to the Overview page. Make a note of the Application (client) ID and Directory (tenant) ID.

Click on "Add a certificate or secret". You should see the following screen

Click on "New client secret". Enter a suitable description in the side panel that shows up and click add. Copy the value of the secret (not Secret ID) just created. This would be the Client Secret.

We will need these to configure our Azure Visitor Authentication Integration.

Installing the Azure Visitor Authentication Integration

Navigate to the Integrations tab in a space and locate the VA-Azure integration or navigate directly to this https://app.gitbook.com/integrations/VA-Azure.

Install the integration on your organization (if necessary) and then install it on your desired space.

Upon installation on space, you will see a screen asking you enter the Client ID, Tenant ID, and Client Secret.

For Client ID, Tenant ID, and Client Secret, paste in the value you copied from Entra Dashboard.

Click Save.

Copy the URL displayed in the modal and enter it as a Redirect URI in Entra (as shown in the below screenshot). Hit Save. Note that you may need to select Web as a platform before it lets you enter a Redirect URI.

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

Upon accessing the published content URL and after logging in with your Azure credentials, you may see a screen telling you that you need to "Request approval" from your admin. Your admin can grant this request by accessing the published content URL, logging in, and granting approval on behalf of the organization.