Visitor Authentication

Use JWT token to authorize anonymous access to private content.

BETA: This feature is currently accessible to authorised customers. Contact us at support@gitbook.com for more information.

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 support@gitbook.com 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.