Getting started
Accounts
Features
Integrations
Hosting
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 accessible to anyone.
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.
When redirecting to the fallback URL, GitBook is passing a
location query parameter, it can be used to redirect to the original location of the user:1
// Route handler for the fallback url
2
app.get('/', (req, res) => {
3
// --> Validate user access here <--
4
5
const token = jwt.sign({ data: 'foobar' }, gitbookSignKey, { expiresIn: '1h' });
6
const redirectURL = `https://mycompany.gitbook.io/myspace/${req.query.location || ''}?jwt_token=${token}`;
7
8
res.redirect(redirectURL);
9
Copied!
Last modified 25d ago