Visitor Authentication

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 space or collection, hit Publish, and select "Visitor Authentication". If you're not on an enterprise plan, you'll be prompted to upgrade.
Once enabled, you'll have access to a private signing key for this space. Each space has a unique signing key. You should keep this key secret - make sure not to commit it into your source control repository. We recommend referencing it through a production secrets system in your deployed backend.
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 private key using the library jsonwebtoken for Node JS.
1
const jwt = require('jsonwebtoken');
2
​
3
const gitbookSignKey = '<key copied from GitBook>'
4
​
5
const token = jwt.sign({ data: 'foobar' }, gitbookSignKey, { expiresIn: '1h' });
6
const redirectURL = `https://mycompany.gitbook.io/myspace/?jwt_token=${token}`;
Copied!
Once you've created the key, you need to include it as the value of a query parameter named jwt_token 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:
1
const express = require('express');
2
const jwt = require('jsonwebtoken');
3
const app = express();
4
const port = 3000;
5
​
6
const gitbookSignKey = '<key copied from GitBook>'
7
​
8
app.get('/', (req, res) => {
9
 // --> Validate user access here <--
10
​
11
  const token = jwt.sign({ data: 'foobar' }, gitbookSignKey, { expiresIn: '1h' });
12
  const redirectURL = `https://mycompany.gitbook.io/myspace/?jwt_token=${token}`;
13
​
14
  res.redirect(redirectURL);
15
});
16
​
17
app.listen(port, () => {
18
  console.log(`Example app listening at http://localhost:${port}`)
19
});
Copied!
Step 3: configure a fallback URL
Finally, on the "Link and domain settings" in the Publish panel of your GitBook space or collection, 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.

Features - Previous

Share links

Next - Features

SAML single sign-on

Last modified 15d ago

Export as PDF

Copy link

Contents

How does it work?

Setup Guide

Step 1: enable "Visitor Authentication"

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

Step 3: configure a fallback URL