Authentication Integration

Choose the Login Path

MUI Boilerplate uses different login paths for local development and deployed builds. Prepare the matching identity and backend configuration before starting the application.

Environment	Login path	Configuration
npm run dev on localhost:9001	Authorization Code with PKCE	.env: backend origin, authcode mode and registered public client ID.
Deployed static build	Portal shared-cookie login	Portal and backend configuration, HTTPS and gateway routing. The development auth variables do not select the deployed login mode.

The identity client ID identifies the browser application's sign-in client. It is separate from the WEDA Client Credential feature for programmatic access. The public browser client described here has no client secret.

Prepare a Local Development Client

Ask your identity administrator to register a public Authorization Code + PKCE client for the WEDA identity server at <VITE_ORIGIN>/identity.

Provide the following values exactly, including the port, path and trailing slash:

Registration field	Value
clientType	public
domain	http://localhost:9001
redirectUris	http://localhost:9001/auth/callback
postLogoutRedirectUris	http://localhost:9001/
Allowed scopes	openid, profile, email

You also need a user account for the same identity environment. Ask your WEDA administrator to confirm that the backend token endpoint, POST /{tenant}/weda/api/v1/auth/tokens, accepts the identity server's access token as a Bearer token.

Check the result: You have a registered public client ID, matching callback URLs, a user account and a compatible WEDA token exchange endpoint.

This identity registration prepares browser sign-in. It does not grant access to an organization's resources by itself.

Sign In During Local Development

Browser -> Identity server: sign in
Identity server -> http://localhost:9001/auth/callback
Local frontend -> WEDA backend: exchange identity access token
Local frontend -> WEDA APIs: use the WEDA token

The local application signs in through your identity server before obtaining its WEDA token.

1. In the project root, set .env:

   VITE_ORIGIN=https://weda.example.com/
   VITE_AUTH_MODE=authcode
   VITE_AUTH_CLIENT_ID=your-registered-public-client-id

2. Replace the example origin and client ID with the values prepared for your environment.

3. Run npm run dev and open http://localhost:9001.

4. Sign in and confirm that the browser returns to the local application.

Check the result: The application opens after sign-in. With an organization available, the documented example returns to /central/weda; an account without one opens Organizations.

The development server proxies /platform, /central/portal/api, /central/weda/api and /api to VITE_ORIGIN. In authcode mode, it also proxies /identity/connect/token.

Note: Local Cookie mode

The project also accepts VITE_AUTH_MODE=cookie during development. A Portal cookie set on the backend domain does not reach localhost; this mode only works when the required cookie is available there through other means. Use the PKCE path above for this guide's local setup.

Understand Login After Deployment

Browser -> /{tenant}/portal/login: sign in through Portal
Portal -> Browser: set session cookie on the backend domain
Frontend -> WEDA token endpoint: send request with credentials
Frontend -> WEDA APIs: use the WEDA token

A deployed build uses Portal's shared-cookie login. Setting VITE_AUTH_MODE=authcode does not change that production behavior.

An unauthenticated user is sent to /{tenant}/portal/login. After sign-in, the frontend exchanges the session cookie for a WEDA token at POST /{tenant}/weda/api/v1/auth/tokens, sending the request with withCredentials: true.

Prepare the environment with your WEDA and identity administrators:

• HTTPS: Serve the deployed environment over HTTPS.
• Login return path: Configure sign-in to return to the deployed frontend's callback.
• Credentialed requests: If frontend and backend use different origins, configure the backend to allow requests with credentials from the frontend origin.
• Backend routes: Configure the gateway to forward the application's backend API paths to the intended WEDA environment.

Agree on the deployed frontend's callback URL with your identity administrator. The localhost registration above applies to local development; prepare the callback registration for the deployed address separately.

Keep Development and Runtime Configuration Separate

Setting	When it applies	What it controls
.env: VITE_ORIGIN	Local development in this project	Backend target for the development proxy and localhost requests that reach the backend directly.
.env: VITE_AUTH_MODE, VITE_AUTH_CLIENT_ID	Local development in this project	Local sign-in mode and public client identity. Deployed builds ignore these auth settings.
public/runtime-config.js: tenantType	Deployment runtime	singleTenant or saas, defaulting to singleTenant.
First URL segment: /:tenant/weda/...	Application routing	The tenant path, such as central. This is separate from tenantType.

The runtime configuration is loaded before the application script. In application code, read it through src/shared/config/runtimeEnv.ts instead of accessing window.__ENV__ directly.

The route structure is defined in src/shared/lib/appRoute.ts. Changing tenantType does not rename routes or select a different tenant path.

Prepare the Static Deployment

/central/weda/api/...       -> WEDA backend
/central/weda/assets/app.js -> Static host: /assets/app.js

The gateway routes API requests to WEDA and removes the /{tenant}/weda prefix from frontend requests before forwarding them to the static host. The paths above use tenant central as an example.

1. Run the project's verification command:

   npm run verify

2. Publish the generated dist/ files to your static host.

3. Configure the host to serve index.html for unmatched application routes, so direct navigation to a client-side route can load the application.

4. Provide the environment's runtime configuration file. The source file is public/runtime-config.js; the deployed host must serve the corresponding runtime-config.js asset.

5. Configure the gateway routing:

   • Forward backend API requests to the WEDA environment. For the documented central setup, these paths include /platform, /central/portal/api, /central/weda/api and /api.
   • For the remaining frontend requests, strip the /{tenant}/weda prefix before forwarding them to the static host. For example, /central/weda/assets/app.js must reach that host as /assets/app.js.

6. Configure Portal login for the deployed frontend, then check sign-in and a page that reads WEDA data.

Check the result: A direct application URL loads, sign-in returns to the deployed frontend, and the application can display WEDA data for the selected organization.

Confirm the backend routes and tenant path needed by your environment. The repository provides neither the gateway nor a backend-for-frontend. See the source release's deployment requirements.

Caution: Local production preview

npm run preview does not strip the /{tenant}/weda prefix. Application pages remain blank without that routing, so the preview command alone is not a complete deployment check.

Troubleshooting

Symptom	What to check
Development server stops because the backend origin is missing	Set VITE_ORIGIN in the project root's .env.
Development server cannot use port 9001	Free the port. The identity client's registered URLs must match the development address.
Sign-in reports a client or redirect mismatch	Compare the client ID, domain, callback and post-logout URLs with the registration table, including trailing slashes.
Identity sign-in succeeds, but WEDA access fails	Confirm backend token-exchange compatibility, the intended tenant and the user's organization access.
Local sign-in works, but deployed sign-in fails	Check Portal login, the deployed callback, HTTPS, credentialed requests and gateway routes. The local auth variables do not configure production login.
A deployed page works through navigation but fails when opened directly	Check the static host's fallback to index.html for application routes.
Deployed pages or application pages in npm run preview are blank	Check that frontend requests reach the static host after the gateway strips /{tenant}/weda. The preview server does not perform this rewrite.