Comment on page
Implement Visitor Authentication using Next.js and Clerk
Visitor Authentication in GitBook is a powerful way to further control who has access to the information you're publishing. By setting up a custom login screen, you can customize the experience for private materials you might have on GitBook.
In order to use Visitor Authentication, you'll need to configure a few tools first—Including setting up a server to handle the sign-in flow your users will go through.
To get started, you'll need to clone the repository we're following in this guide. It requires a few pieces to be configured (which we'll cover in the following steps).
To clone, you can run the following command in your terminal:
After cloning the repository, you can
cdinto the root of the project, and install it's dependencies using
In order to use a custom sign-in page for users, we'll need to publish a GitBook space with Visitor Authentication.
Keep in mind, this feature is only available for Pro and Enterprise plans.
In the space you would like to use, head to the Share Modal in the upper right corner, and choose "Publish with visitor authentication" in the Share to an audience section.
Enable Visitor Authentication
After enabling this option, you'll see a Private Key available for you to use. We'll need this later in our configuration, so leave this page open to grab this key later.
You'll also see your published space's url. This is the link users can access your published content—But since it's protected with Visitor Authentication, it'll return an error for anyone visiting this link without signing in first. We'll need this value in our configuration at a later point as well.
Next, we'll need to configure our Clerk account.
Once you have an account, you're able to create a free application, and configure the login experience for your users. You can choose from a large list of providers, or allow them to create a new account via email or phone number!
After you've customized your sign up/in screen you'll need to grab our API keys for this project.
Head to the API Keys section in the left side navigation to find keys specific for this project. We're using Next.js for the framework of this app, so you should see the following information at the top:
Clerk API key dashboard
We'll need these in order to run the project. In your local project, you'll find an example
.env.examplefile that we'll use for our environment variables.
Rename this file to
.env, and replace the
CLERK_SECRET_KEYkeys with the copied values from your Clerk dashboard.
.envfile, you'll also see another key called
NEXT_PUBLIC_GITBOOK_URL. This is the URL that your site is published under, which can be found when you Publish your GitBook Site with Visitor Authentication.
At this point, your
.envfile should look like this:
# Replace this with the public URL of the GitBook space you're protecting using Visitor Authentication.
# Copy these from the API keys sections in your Clerk application dashboard, by choosing "Next.js"
Finally, we'll need to configure one more section to complete the set up.
In the Clerk dashboard, head to the JWT Templates section in the left side navigation. You'll need to create a new template for your app to use.
- 1.Go to your Clerk dashboard.
- 2.In your Clerk application, go to JWT templates.
- 3.Create a new template using the "Blank" template.
- 4.Give your template a name (this demo uses
'). If you use a different name, make sure your template name matches the one set in
pages/api/visitor-auth.tsin your local project.
- 1.Enable the "Custom signing key" and select the HS256 algorithm.
- 2.Paste your private key in Clerk's JWT template Signing key field.
Lastly, we'll need to define a custom template for our sign in. Copy and paste the following code template into the "Claims" section.
Finally, click "Apply changes" to save your configuration.
Now that we have our configuration completed, we can run and test the Visitor Authentication flow. If you try to visit your published GitBook site direclty, you'll be met with a 401 screen—But if we go through the Visitor Authentication flow, we'll be able to access the site without a problem.
In the root of your project, run
npm run devin the terminal. Then, navigate to the url your app is running on (by default, it should be
Visitor Authentication demo
Here, you can sign up for an account.
Visitor Authentication demo sign in page
After we sign in successfully, we'll then be able to navigate to our published site without any problems.
Visitor Authentication allows you to protect published GitBook sites behind a sign-in flow that you control.
Not only is it customizable, but it also opens up the door for many more possibilities in the future around the way you want to work in GitBook. Make sure to head to the Visitor Authentication docs to learn more.
Interested in hearing more? Sign up for our newsletter below:
Last modified 1mo ago