SSO & Entra ID

Monozu Cloud integrates with Microsoft Entra ID (formerly Azure AD) for single sign-on. There are two distinct integration modes: a platform-level integration for Cloud SPA users, and a per-tenant OIDC configuration that tenants can set up in Settings.

Platform SSO (Cloud Backend)

The Cloud Backend registers a single multi-tenant Entra ID app (/common endpoint) for the “Sign in with Microsoft” button on the login page.

Flow:

sequenceDiagram
    participant Browser
    participant SPA as Cloud SPA
    participant API as Cloud Backend
    participant Entra as Microsoft Entra ID

    Browser->>SPA: Click "Sign in with Microsoft"
    SPA->>API: GET /api/v1/auth/microsoft/login
    API-->>Browser: 302 Redirect to Entra authorization URL
    Browser->>Entra: Authorization request (PKCE)
    Entra-->>Browser: Redirect to {API_PUBLIC_URL}/api/v1/auth/microsoft/callback?code=...
    Browser->>API: GET /api/v1/auth/microsoft/callback?code=...
    API->>Entra: Token exchange (code → ID token + access token)
    Entra-->>API: ID token { email, name, oid }
    API->>API: Find or create user by email, issue JWT pair
    API-->>Browser: Redirect to {APP_BASE_URL}/auth/callback?token=<access_token>
    Browser->>SPA: /auth/callback — store access_token

Required env vars (Cloud Backend):

Variable	Description
`MS_CLIENT_ID`	Entra ID application (client) ID
`MS_CLIENT_SECRET`	Client secret
`API_PUBLIC_URL`	Must match the redirect URI registered in Entra

The redirect URI registered in Entra must be exactly:

{API_PUBLIC_URL}/api/v1/auth/microsoft/callback

Per-tenant OIDC

Each tenant can configure their own Entra ID app registration in Settings → SSO. This allows tenant users to log in with their corporate identity.

The per-tenant configuration is stored in the tenant_oidc_config table (or equivalent) and loaded at login time based on the user’s email domain.

Required tenant configuration (stored in DB, managed via Settings UI):

Client ID
Client Secret
Tenant ID (Entra Directory ID)
Redirect URI (same {API_PUBLIC_URL}/api/v1/auth/microsoft/callback pattern)

Auth policy interaction

`AUTH_POLICY`	Email/password	Platform SSO	Per-tenant OIDC
`standard`	✓	✓	✓
`restricted`	✗	✓	✓

Under restricted policy, the AUTH_ALLOWED_EMAIL_DOMAINS env var must be set. Users with non-matching email domains are rejected at the OIDC callback.

Management Backend OIDC

The Management Backend has its own independent Entra ID app registration, used for management staff authentication. Its env vars follow the same pattern:

Variable	Description
`MS_CLIENT_ID`	Management app registration client ID
`MS_CLIENT_SECRET`	Client secret
`MS_TENANT_ID`	The Entra tenant hosting the management app
`API_PUBLIC_URL`	Management Backend public URL (for redirect URI)

The redirect URI for Management must match:

{API_PUBLIC_URL}/api/v1/auth/microsoft/callback

Note that this is the Management backend URL, not the Management SPA URL.

HTTP buffer size note

Microsoft and Entra ID redirects include large Cookie headers. The default Fiber/fasthttp read buffer of 4096 bytes can trigger HTTP 431 Request Header Fields Too Large. The Cloud Backend defaults to 65536 bytes:

HTTP_READ_BUFFER_BYTES=65536
HTTP_WRITE_BUFFER_BYTES=65536

Do not reduce these values below ~16384 in production.