Visitor Authentication

Use JWT token to authorize anonymous access to private content.

This feature is currently accessible to all Enterprise customers. If you are interested in the Enterprise plan, please contact [email protected] for a quote.

GitBook provides different solutions to handle access management: private content accessible to members only, SAML SSO, public content.

With "Visitor Authentication", GitBook lets your server-side code handle who has access to the content.

How does it work?

Setup Guide

A complete example repository for Node.JS is available on GitHub: https://github.com/GitbookIO/example-visitor-authentication

Step 1: enable "Visitor Authentication"

In your private space, in the "Share" panel, enable the feature "Visitor Authentication".

This feature is only available for Enterprise customers. Reach out to [email protected] for more information.

Once enabled, you'll have access to a master signing key for this space. This key is bound to your space, and cannot be used for other spaces (even those in the same organization).

Step 2: sign a JWT token and grant access to a visitor

Here's an example of creating a JWT token by signing the access data with the master key using the library jsonwebtoken for Node JS.

const jwt = require('jsonwebtoken');
const gitbookSignKey = '<key copied from GitBook>'
const token = jwt.sign({ data: 'foobar' }, gitbookSignKey, { expiresIn: '1h' });
const redirectURL = `https://mycompany.gitbook.io/myspace/?jwt_token=${token}`;

Once you've created the key, you need to include in the URL of the GitBook content you wish the user to have access to (see redirectURL)

Here's a very simple Express application for signing keys and redirecting users:

const express = require('express');
const jwt = require('jsonwebtoken');
const app = express();
const port = 3000;
const gitbookSignKey = '<key copied from GitBook>'
app.get('/', (req, res) => {
// --> Validate user access here <--
const token = jwt.sign({ data: 'foobar' }, gitbookSignKey, { expiresIn: '1h' });
const redirectURL = `https://mycompany.gitbook.io/myspace/?jwt_token=${token}`;
res.redirect(redirectURL);
});
app.listen(port, () => {
console.log(`Example app listening at http://localhost:${port}`)
});

Step 3: configure a fallback URL

Finally, on the "Visitor authentication" settings in the Share panel of your GitBook space, you can configure a "fallback URL".

When someone directly accesses your space without the necessary token, GitBook uses the fallback URL to redirect the visitor to a custom URL so that you can authenticate them.