Skip to main content

Deploying Platform Docs to Cloudflare Pages with Entra Authentication

This document walks through the end-to-end deployment of the sparqd/platform-docs Docusaurus site to Cloudflare Pages, including Microsoft Entra ID authentication via MSAL.

Part 1: Deploy to Cloudflare Pages​

1.1 Create the Pages Application​

  1. Go to the Cloudflare dashboard → Build → Compute → Workers & Pages.
  2. Click Create Application.
  3. Under the Pages section, click Get started (next to "Looking to deploy Pages?").
  4. Select Import an existing Git repository → Get started.

1.2 Connect the GitHub Repository​

  1. Click Connect GitHub.
  2. Select the sparqd organization.
  3. Choose Only select repositories → select sparqd/platform-docs.
  4. Click Install and authorize.

1.3 Configure Build Settings​

Click Begin setup and enter the following:

SettingValue
Project nameplatform-docs
Production branchmain
Framework presetDocusaurus
Build commandnpm run build
Build output directory/build

Click Save and deploy.

Cloudflare will assign a preview URL such as https://platform-docs-4fl.pages.dev/ once the first build completes.

Part 2: Register the App in Microsoft Entra ID​

2.1 Create the App Registration​

  1. Go to https://entra.microsoft.com/.

  2. Navigate to App registrations → New registration.

  3. Fill in the form:

    FieldValue
    NamePlatform Docs
    Supported account typesSingle tenant only — Quant-Data
    Redirect URI (Platform)Single-page application
    Redirect URI (URL)https://platform-docs-4fl.pages.dev/

  4. Click Register.

2.2 Configure Redirect URIs​

  1. In the left navigation, go to Authentication → Redirect URI configuration tab.

  2. Add the following URIs (all as Single-page application type):

    EnvironmentURI
    Local developmenthttp://localhost:9000
    Cloudflare previewhttps://platform-docs-4fl.pages.dev/

    Add additional URIs (e.g. custom production domain) as needed.

  3. Click Save.

2.3 Retrieve Credentials​

  1. In the left navigation, go to Overview.
  2. Copy:
    • Application (client) ID → this is your MSAL_CLIENT_ID
    • Directory (tenant) ID → this is your MSAL_TENANT_ID

Part 3: Configure Environment Variables​

3.1 Local Development​

Add to your .env file (do not commit to version control):

# Microsoft Entra ID (Azure AD) app registration
MSAL_CLIENT_ID=your-application-client-id
MSAL_TENANT_ID=your-directory-tenant-id

3.2 Cloudflare Pages Secrets​

  1. Go to Workers & Pages → platform-docs → Settings tab.

  2. Scroll to Variables and Secrets.

  3. Add the following:

    TypeVariable NameValue
    SecretMSAL_CLIENT_IDYour Application (client) ID
    SecretMSAL_TENANT_IDYour Directory (tenant) ID

  4. Click Save.

These secrets will be available from the next deployment onwards. Trigger a re-deploy if the site was already live before adding them.

Part 4: Verify​

  • Visit https://platform-docs-4fl.pages.dev/ and confirm the site loads.
  • Attempt login — you should be redirected to the Microsoft login page and back.
  • Check the Deployments tab in Cloudflare Pages for build logs if anything fails.

Reference Commits​

  • Initial Entra auth integration: c867c324

Part 5: Set Up a Custom Domain​

  1. Go to Workers & Pages → platform-docs → Custom domains tab.
  2. Click Set up a custom domain and enter the subdomain (e.g. platform-docs.internal.cogrion.com).
  3. Cloudflare will automatically add the required CNAME record to the cogrion.com zone (since it is managed in the same Cloudflare account). Confirm when prompted.
  4. Wait for DNS propagation and SSL provisioning — status will show Active with SSL enabled once complete.
  5. Add the new domain as a redirect URI in the Entra app registration (see Part 2.2).

If the domain is managed in a different Cloudflare account, manually add a CNAME record pointing to platform-docs.pages.dev in that zone instead.