Configure application login
Configure the Account service before users follow first login. Application login proves identity. Mailbox connection and provider access remain separate.
Before you start
Use a prepared root configuration from first installation. Keep the deployment tenant identifier, existing database, and auth secret when you move existing users. Register the exact Account origin, including its HTTPS port.
The unified setup calculates ACCOUNT_PUBLIC_URL, MAILGEN_PUBLIC_URL, and the matching Better Auth URLs. BETTER_AUTH_URL and NEXT_PUBLIC_BETTER_AUTH_URL point to Account. The Account service requires a database URL, BETTER_AUTH_SECRET, and ECAS_DEPLOYMENT_TENANT_ID.
Bootstrap the administrator
Set ECAS_BOOTSTRAP_ADMIN_EMAIL and ECAS_BOOTSTRAP_ADMIN_PASSWORD in the root configuration before first setup. The bootstrap password must contain 32–64 characters. Keep both populated for Compose resolution after bootstrap. These are application credentials, separate from the database, Kafka UI, proxy, and provider secrets.
Normal initialization prepares authorization data and the administrator. An existing bootstrap user must retain the bootstrap role and match the configured password. Otherwise bootstrap stops with BOOTSTRAP_EMAIL_ALREADY_REGISTERED or BOOTSTRAP_SECRET_MISMATCH. New accounts require the deployment's zero group. If that group is absent or ambiguous, account creation stops. A login restriction can also reject a new session.
Open the Account /login page with the configured administrator account after setup. Check access to the permitted administration area. Do not infer administrator access from a provider email address alone.
Microsoft application login
Supply the complete root set:
| Setting | Meaning |
|---|---|
BFF_MICROSOFT_CLIENT_ID | Entra login application client ID |
BFF_MICROSOFT_CLIENT_SECRET | Login application's secret value |
BFF_MICROSOFT_TENANT_ID | Login tenant ID |
In the login application's Authentication → Web → Redirect URIs, register the exact Account callback. For example: https://account.devbox.ecas.local:8443/api/auth/callback/microsoft.
The provider configuration requires all three values. It can read legacy MICROSOFT_* names outside the root mapping. Use the canonical root names for unified deployment.
Backend BACKEND_* credentials serve app-only Graph calls. They do not replace these login credentials. Prepare permissions and mailbox access through Microsoft Graph setup.
Microsoft identity binding checks the signed identity and tenant, then binds it to the authorization actor. Binding does not create a mailbox. Conflicting bindings fail instead of silently switching actors.
Google application login
Follow Google Cloud setup for a separate Web OAuth login client and public callback. Set GOOGLE_APP_LOGIN_ENABLED=true and the complete BFF_GOOGLE_LOGIN_CLIENT_ID / BFF_GOOGLE_LOGIN_CLIENT_SECRET pair.
The login flow requests identity scopes only: openid, email, and profile. The mailbox client and its Gmail consent are separate. A partial login override does not combine with a legacy secret.
Session and security behavior
Email/password login is enabled. Password length is 8–64 characters. Email verification is not required for ordinary email/password login. Session lifetime is seven days, with a one-day update interval. Cookie caching is disabled.
Account trusts the configured Account and MailGen origins. Its ecas-shared cookie prefix separates the shared session from older BFF cookies. For a suitable account. hostname, the cookie domain covers that deployment's sibling hosts.
Return destinations must belong to MailGen or the Account administration path. Invalid destinations return to MailGen. Non-localhost destinations require HTTPS. Social account linking has additional identity and verification rules. Do not use a shared email address as proof of mailbox ownership.
Check the result
Sign in at Account and open the configured BFF URL. Check the current user's permitted actions. Then check mailbox access independently.
If LOGIN_PROVIDER_DISABLED appears, check the selected connector and its complete credentials. For callback or cookie failures, check the exact host, port, certificate trust, and public origins. Apply configuration through an ordinary restart. Quick start does not reload it. See execution modes.