Docusaurus is a fantastic way to build a developer portal or internal docs site. It builds to a folder of static files, which is exactly what makes the next step awkward: that folder is happy to be served to anyone, and you need it served only to your company.

The usual answers are all heavier than the problem:

  • Run an authenticating reverse proxy (oauth2-proxy, Pomerium) in front of it. Now you operate a security-critical service for a docs site.
  • Drop it behind a VPN. Clunky for partners and contractors, and a poor fit for something that’s “just a website.”
  • Move the whole thing into a managed docs platform, and give up Docusaurus.

Here’s a lighter path: keep Docusaurus, and put the built output behind your identity provider.

Step 1: build your site

Nothing changes about how you build. From your Docusaurus project:

npm run build       # outputs to ./build

You now have a build/ directory of static HTML, CSS, and JS.

Step 2: deploy the build

Publish the folder to BehindGate. From CI, or locally:

bg-deploy ./build

Each deploy is an immutable release. Publishing flips a pointer atomically, so there’s no half-deployed state, and you can roll back to a previous release in seconds if a docs change goes wrong.

To wire this into CI, add the deploy step after your build step, for example as the last job in your GitHub Actions workflow on main. Re-running it on every merge keeps the portal current with zero servers to babysit.

Step 3: map your domain

Point a single CNAME at BehindGate:

developers.acme.com  CNAME  →  behindgate

TLS is provisioned automatically. You don’t migrate nameservers and you don’t touch the rest of your DNS zone.

Step 4: gate it with your IdP

Go live immediately with email one-time codes (the owner’s email domain is allowed automatically, so you can view the site right after deploying). When you’re ready for workforce-grade control, connect your identity provider against the custom domain:

  • Microsoft Entra ID: scope access to a group; MFA and Conditional Access apply automatically.
  • Google Workspace: allow your domain (hd) with near-zero admin setup.

(Any custom OIDC provider works the same way.)

Once SSO is on, the email fallback is disabled, so there’s no weak-link bypass via an old mailbox. Your IdP is the single source of truth for who can read the docs.

What you end up with

  • developers.acme.com serving your Docusaurus portal over HTTPS.
  • Access limited to the exact people in your Entra or Google group.
  • A deploy step you can run from CI on every merge.
  • No proxy to operate, no VPN, no nameserver migration, and no per-seat bill: viewers are unlimited.

The same flow works for any static docs generator — Starlight, MkDocs, Redoc, Scalar — because BehindGate gates the output, not the tool that produced it.