Background Engineering teams frequently have centralized documentation websites that tie together all the different teams, projects, and workflows supported internally by the company. , and why it’s important to present internal documentation in an easy-to-read, easy-to-search manner. I have spoken about the importance of quality documentation before In that post, I talked about how my team ended up writing our documentation using , a React- & Markdown-driven static site generator. It suited our needs well, looked great, and was easy to write customized documentation and components using the features. We hosted this documentation site internally, with no authentication required since viewing it needed a user to be on already. Docusaurus very MDX the company VPN I wanted to bring this same documentation style over to other companies, but they did not enforce the same VPN restrictions as Bloomberg. With this constraint, we needed a way to force authentication to our Docusaurus site before showing content to users. Authentication & private content was a few times on the project repository but this issue was ultimately rejected since that is outside the scope of a static-site generator. already discussed So what can we do? Solution Let's walk through how to deploy Docusaurus behind an OAuth proxy which will force users to log in with a 3rd party provider before viewing our documentation. Tools & Concepts Our documentation will be generated using the static-site generator Docusaurus The site will be protected using GitHub sign-in by fronting it with Oauth2 Proxy The site will be hosted on for ease, but you can change this for your specific project. Heroku What is Oauth? ( pen orization) is an authorization protocol that allows a user to authenticate and access one service by allowing another service to provide your basic account details. OAuth allows for password-less logins - which are inherently safer - and requires users to maintain fewer accounts & credentials across services. Oauth O Auth An example of Oauth is when a website allows you to log in with your Google, Twitter, or GitHub credentials. The site has preconfigured routes, configurations, and protocols to interact with those 3rd party providers, so you can easily log in without needing credentials. Our example will allow users to log in with their GitHub account to view the documentation. The Process This was performed on Docusaurus 2.0.0-beta.21 With some background on what we are doing, let's dive into setting up the project. This will walk through the individual steps, but you can view if you want to just get something deployed. the complete starter project Creating the Docusaurus Project To start, we will create a basic Docusaurus project. This guide assumes you already have Node 16.x and installed on your machine, but you can use tool to configure these if needed. npm the nvm Create a new Docusaurus site with the (default) template. classic npx create-docusaurus@latest oauth-gated-docusaurus classic directory. Assume that the rest of the steps are run inside this newly created oauth-gated-docusaurus Blog-Only Mode Since this will be internal documentation only, I usually delete the & homepage and clean up the to match. blog docusaurus.config.js rm -rf blog src/pages src/components/* Next, replace the key in the file with the following: presets docusaurus.config.js presets: [
    [
      'classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
          routeBasePath: '/', // Serve the docs at the site's root
          // Please change this to your repo.
          // Remove this to remove the "edit this page" links.
          editUrl:
            'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
        },
        blog: false,
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      }),
    ],
  ], Make sure to update the GitHub URL(s) to point to your repository instead. Finally, create a landing page for your blog site. The denotes this file as the root URL. It is the only file that should have the key defined. slug: / slug cat <<EOT >> docs/index.md
---
sidebar_position: 1
sidebar_label: Homepage
slug: /
---

# Welcome to Our Documentation

Hello world!

EOT At this point, you should be able to the server and open up the URL Docusaurus shows in the immediate output. npm start If you try to run , you may encounter a few build errors due to invalid URLs. This is left to an exercise for the user, but the example repository already has the fixes. It comes down to removing the and replacing with to get the project to build nicely. npm run build to: blog /docs/intro /intro If you do not want to fix these issues, you can also set if you like. See the documentation here. onBrokenLinks: 'warn' onBrokenLinks Deploy Basic Version to Heroku Before adding in the authentication and authorization components, we will get the basic site up on , so we have a URL to redirect back to when configuring our OAuth application later. Heroku Create the Heroku app. Create a and as needed. Heroku account install the Heroku CLI heroku create Add the buildpack which will run automatically before deployment nodejs npm build heroku buildpacks:add heroku/nodejs Add a to run Docusaurus in a web process Procfile cat <<EOT >> Procfile
web: npm run serve -- -p \$PORT
EOT Commit the changes and push them to GitHub & Heroku git add . && git commit -m "prepare for heroku deployment"
git push heroku main && git push origin main With the following command, you should be able to view your documentation in the browser, but there's one issue...it's still public! So let's fix that with some OAuth and a proxy. heroku open Creating the GitHub OAuth Credentials With Docusaurus configured and running locally, we can begin creating an OAuth application. We will be using GitHub as an application provider, meaning users will log in via it, redirecting them back to our documentation. I chose GitHub because I assume people reading this article have a GitHub account, and any GitHub user can create OAuth applications without paying. most Visit and provide the required details. the page to register a new app : Application Name Docusaurus OAuth Example : Whatever opened in your browser Homepage URL heroku open : Authorization callback URL <Homepage URL >/oauth2/callback Once the OAuth application is registered, note the , which should be a random-looking string of 16-24 characters. Save this to Heroku to be used later with the following command. Client ID heroku config:set OAUTH2_PROXY_CLIENT_ID=<value from GitHub> Generate a Client Secret Finally, you will need to generate a client secret for the OAuth application. Under the section, click the button, which will reload the page with a newly minted client secret key. Client secrets Generate a new client secret Make sure to copy it manually or by clicking the Copy icon because you cannot retrieve this key again! Save this to the Heroku app to be used later. heroku config:set OAUTH2_PROXY_CLIENT_SECRET=<value from GitHub> Adding OAuth Proxy to Docusaurus Finally, all of the pieces are in place to run our documentation site behind an OAuth2 Proxy. A Proxy is a middleman between users trying to access the website and the web process hosting the content. Its job is to either show the website content to authorized users or redirect those not authorized to GitHub. Begin by adding community buildpack to your application. the heroku-buildpack-oauth2-proxy heroku buildpacks:add cfra/oauth2-proxy We added the GitHub OAuth client and secret keys in the last step, but we need to tell our proxy to use GitHub for authentication. We can do this with the following: heroku config:set OAUTH2_PROXY_PROVIDER=github The last step is to generate a secret key to sign all authentication cookies. This string can be random, so we are using Python for this step. You may need to switch for in the command, if you get a Python error. python python3 heroku config:set OAUTH2_PROXY_COOKIE_SECRET=$(python -c \
    'from secrets import token_urlsafe; print(token_urlsafe(32)[:32])' \
) To see the change, you will need to place the oauth2-proxy script of our command from earlier. Then, update the Procfile to the following. in front npm serve ... web: /app/bin/start_with_oauth2_proxy.sh npm run serve -- -p 8080 Notice how the server is now running on instead of looking at the variable. This change is because runs listening on and it expects our gated web server to listen on . 8080 $PORT oauth2_proxy $PORT, 8080 Testing Login View your documentation in the browser again, and you should be greeted with the OAuth2 Proxy landing page. Try to sign in with GitHub now! If all worked, you should be able to view your documentation again! We have successfully gated our documentation behind an OAuth Provider. Suppose you would like to change the OAuth provider being used. In that case, you will need to update the , , and the variables on the app reading documentation for the associated provider type. OAUTH2_PROXY_PROVIDER OAUTH2_PROXY_CLIENT_ID OAUTH2_PROXY_CLIENT_SECRET after the oauth2-proxy Bonus: Restricting to a GitHub Organization Cool, our documentation now has OAuth in front of it, meaning people have to log into their GitHub accounts before viewing it. That's great, but we said this was for internal company documentation; we don't want just GitHub user seeing our documentation. any Reading through GitHub Provider documentation, we can see that the provider can implement more strict access controls at the organization, team, repository, token, or user level. Let's restrict this to a single team by adding a configuration argument. the oauth2-proxy heroku config:set OAUTH2_PROXY_ARGS="-github-org='my-cool-org'" And update the to read the configuration variable. Procfile OAUTH2_PROXY_ARGS web: /app/bin/start_with_oauth2_proxy.sh $OAUTH2_PROXY_ARGS npm run serve -- -p 8080 This means that changing who can access the documentation at different abstraction levels boils down to just updating the configuration variable, which can be done via the CLI or dashboard under the app settings. Tinkering with this config var is left as a final exercise to the user. OAUTH2_PROXY_ARGS heroku Conclusion With this setup, engineering (and non-engineering teams too!) can write easy-to-manage, easier-to-view documentation sites powered by Docusaurus while ensuring that only appropriate individuals can view them. This detail is usually critical for internal company documentation. Much more configuration and OAuth settings can be included by reading through documentation. the oauth2-proxy Thank you for reading this post! I hope it helps you and your teams as much as figuring out how to make this work helped mine. Also Published Here

Facebook

Fetch

Google

Heroku

Twitter

Managing Django Media & Static Files on Heroku with Bucketeer

Follow me on dev.to

Newsletter

Nominated for 2022 - HackerNoon Contributor of the Year - Css

Nominated for 2022 - HackerNoon Contributor of the Year - Html

Too Long; Didn't Read

Make resilience your competitive advantage

Using OAuth Authentication to Serve Static Internal Documentation 

Using OAuth Authentication to Serve Static Internal Documentation

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Untitled Story

Managing Django Media & Static Files on Heroku with Bucketeer

161 Stories To Learn About Authentication

3 Reasons for B2C Enterprises to Implement Single Sign-on Authentication

4 Dangers of Sticking with Outdated MFA Methods

The Noonification: Tailwindcss? Ill Pass (8/27/2023)

Managing Django Media & Static Files on Heroku with Bucketeer

161 Stories To Learn About Authentication

3 Reasons for B2C Enterprises to Implement Single Sign-on Authentication

4 Dangers of Sticking with Outdated MFA Methods

The Noonification: Tailwindcss? Ill Pass (8/27/2023)

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps