Microsoft Entra ID authentication

The published docs site uses the same client-side Entra ID (Azure AD) SPA flow as calab-handbook (docs/ENTRA_AUTH.md in that repo): MSAL.js v3, tenant-scoped sign-in, user assignment required.

On GitHub Pages this is UI-level gating. It does not stop someone from fetching raw HTML or JSON if they know the URL. That is the same limitation as the handbook. For server-enforced access, put the site behind a reverse proxy.

App registration (reuse handbook)

This site reuses the handbook SPA app calab-handbook-auth. Public IDs live in docs-site.config.json under auth (same values already published by the handbook SPA):

  • Display name: calab-handbook-auth
  • Client ID and tenant ID: see docs-site.config.json auth

Users already assigned to that Enterprise Application can sign in here once these SPA redirect URIs are merged onto the existing list (do not replace the handbook URIs):

  • https://mocks.calab.ai/
  • http://localhost:4173/
  • http://127.0.0.1:4173/

Do not run scripts/auth/setup-entra-auth.mjs against the handbook app. That script writes a full spa.redirectUris set and clears web.redirectUris, which would drop handbook.calab.ai. Merge with Azure CLI instead:

az login --tenant cb4a0c04-778e-42be-afbe-92a1ab7eb03a
APP_ID=fa71292f-eb7c-4ba2-92b1-4cc835e53820
# Inspect current SPA URIs, then PATCH a merged list that keeps handbook + mocks + localhost.
az ad app show --id "$APP_ID" --query "spa.redirectUris"

Only create a separate calab-mocks-docs-auth app if that merge fails:

az login
node scripts/auth/setup-entra-auth.mjs

Optional: store ENTRA_CLIENT_ID and ENTRA_TENANT_ID as GitHub Actions repository secrets to override the config-file IDs at export time. The first main deploy of .github/workflows/docs-site-pages.yml already reads docs-site.config.json auth when those secrets are empty.

Assign users

User assignment is already required on the handbook Enterprise Application. People already assigned there can sign in to this site after the mocks redirect URI is present. Do not turn assignment off.

If you created a separate calab-mocks-docs-auth app instead:

Azure Portal: Enterprise Applications → calab-mocks-docs-auth → Users and groups → Add

Build behaviour

Source Result
Env and docs-site.config.json auth both unset / placeholders Auth is skipped (CI dry-run without IDs)
Valid GUIDs in env or docs-site.config.json auth Overlay + MSAL injected into every exported page
Set but not valid GUIDs Export and the local server fail closed

Env vars win over the config file. After the first authenticated deploy succeeds, set GitHub Pages visibility to public.

Architecture

  1. Page load sets data-auth-state="loading" and hides the body.
  2. MSAL.js loads from a pinned jsDelivr HTTPS URL (SRI hash).
  3. Cached token or redirect response is checked.
  4. Token from the configured tenant → overlay removed, user chip shown.
  5. No token → redirect to Microsoft login. Return path is restored from sessionStorage.

Client ID and tenant ID are serialized with JSON.stringify (HTML-escaped) and validated as GUIDs at build time.