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".

Visitor Authentication can't be enabled on a space if the Shareable Links feature is enabled.

To enable Visitor Authentication in such case, you will need to de-activate the Shareable Links first. But note that de-activating it will revoke the current shareable link.

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.