Local Development

Portal/ is a static SPA. Any HTTP server that can serve static files works. Below is the simplest path to a working dev loop.

Prerequisites

• A modern Node.js install (only used for npx http-server or your favorite static server). The portal itself has no Node dependencies.
• A browser. Chromium-based browsers and Firefox both work for daily development; test in WebKit / Safari before merging UI changes.

Clone and serve

git clone https://github.com/Noble-Effeciency13/PIMActivation-Portal.git
cd PIMActivation-Portal\Portal
npx http-server -p 5500 -c-1

-c-1 disables caching so changes show up on refresh. Open http://localhost:5500.

If you prefer a different static server (Python's http.server, serve, live-server, the VS Code Live Preview extension), they all work equally well.

Create a development app registration

The portal needs an app registration with http://localhost:5500 (or whatever URL you serve from) as a SPA redirect URI. The fastest path:

1. In the Microsoft Entra admin center, create a new single-tenant app registration.
2. Authentication → Add a platform → Single-page application → add http://localhost:5500 (no trailing slash).
3. API permissions → add the delegated scopes from Permissions Reference.
4. Copy the Application (client) ID.

You can reuse this dev app registration for as long as you keep the localhost URL stable.

Inject your IDs locally

Portal/js/msal-config.js ships with placeholders that the deployment scripts replace at deploy time:

clientId:  '__PORTAL_CLIENT_ID__',
authority: 'https://login.microsoftonline.com/__PORTAL_TENANT_ID__',

For local development, replace them temporarily:

clientId:  '00000000-0000-0000-0000-000000000000',  // your dev app id
authority: 'https://login.microsoftonline.com/<your-tenant-id>',

Do not commit those edits. The CI pipelines fail-fast if any placeholder is missing, so an accidental commit is caught quickly — but the cleanest workflow is to keep the file dirty in your working tree and git checkout it before pushing.

A small .gitignore entry for a personal Portal/js/msal-config.local.js and a tiny dev-only swap is also fine.

Sign in locally

Reload the page. MSAL.js will redirect you through login.microsoftonline.com, you'll consent (only the first time), and the portal will render with your real eligibilities.

If your tenant requires admin consent, an admin needs to pre-consent the dev app registration before sign-in works.

Debugging tips

• DevTools Network tab shows every Graph and ARM request, including $batch requests. Click into a $batch POST to see the inner request bodies and per-sub-request status codes.
• Console logs MSAL warnings via console.warn('[MSAL]', ...). Bump logLevel to Verbose in msal-config.js if you need more.
• Application tab shows sessionStorage, localStorage, and IndexedDB. Clear them to simulate a fresh user.
• Conditional Access claims challenges appear as 401s with WWW-Authenticate: insufficient_claims. Inspect the header to see exactly which acrs value is being requested.

CSP relaxations to avoid in production

Local development sometimes tempts you to loosen the CSP — for example, to load a hot-reload script or an inline debug stylesheet. The Static Web App config (Portal/staticwebapp.config.json) ships with the production CSP. Do not commit relaxed values. If you need to test a new origin (e.g. a different MSAL CDN), update the production CSP intentionally and call it out in your PR description.

Pre-PR checks

Before opening a pull request:

• Revert any local edits to Portal/js/msal-config.js.

• Verify the staticwebapp.config.json CSP is unchanged (or, if intentionally changed, justified in the PR description).

• If you modified the Bicep, regenerate Portal/deploy/azuredeploy.json:

  az bicep build --file Portal/deploy/bicep/portal-selfhosted.bicep --outfile Portal/deploy/azuredeploy.json

  The Sync Deployment Templates workflow will re-run the same build on main and fail your PR if the artifact drifts.

• Update CHANGELOG.md under ## [Unreleased].

See Contributing for the full PR checklist.