OpenID Connect (OIDC) Login

OpenID Connect login lets a user authenticate with an external Identity Provider (Microsoft Entra ID/Azure AD) instead of supplying a username/password directly to Monitor. It uses the Authorization Code flow with PKCE.

For classic (credential) login see Authentication. (Monitor internal MFA is not used with OIDC; rely on your Identity Provider's MFA policies.)

Availability: OIDC login is supported in Monitor version 25.8 and newer. Earlier versions do not expose the /login/oidc endpoints.

Prerequisites

Before you can use OIDC login:

  1. App registration in Microsoft Entra ID: note the Tenant (Directory) ID and the Application (Client) ID.
  2. Redirect URI (web) added in the app (e.g. https://app.example.com/auth/callback). This must match the redirectUrl query value you send.
  3. User account linkage: The user's Entra ID primary email must be stored in the Monitor user profile OIDC email field (one‑time linkage on first successful login).
  4. User authentication mode: The user's Authentication Mode in Monitor must be set to OIDC (otherwise password login is expected and OIDC will be rejected).
  5. (Optional) Permissions/Admin Consent for any Microsoft APIs your solution requires.
  6. Accurate server time (NTP) to avoid token validation failures.
  7. HTTPS for both the Monitor API endpoint and your redirect URL.

If any prerequisite is missing the flow may fail with a 400/401 after redirect.

Endpoints

Purpose Method & Path
Initiate OIDC flow POST /{languageCode}/{companyNumber}/login/oidc?redirectUrl={url}
Complete callback GET /{languageCode}/{companyNumber}/login/oidc/callback?code=...&state=...

Both endpoints allow anonymous access and rely on a session cookie to bind the state parameter.

Flow Summary

  1. Client calls Initiate with a (possibly minimal) LoginRequest body and a required redirectUrl query parameter.
  2. Server returns a plain text Authorization URL that already contains client_id, scope, state, code_challenge, etc.
  3. Client redirects the user agent to that URL.
  4. Identity Provider authenticates the user (and any MFA enforced at the IdP side) and redirects back with code + state.
  5. Client/browser calls the Callback endpoint. Server validates state, exchanges code using stored PKCE verifier, and creates a Monitor session.
  6. Response returns a LoginResponse (with SessionId). Cookies for session/refresh may also be set.

Initiate Request

POST /{languageCode}/{companyNumber}/login/oidc?redirectUrl=https%3A%2F%2Fapp.example.com%2Fauth%2Fcallback HTTP/1.1
Host: {host}:8001
Content-Type: application/json
Accept: application/json

{
  "ForceRelogin": false,
}
  • Body is a standard LoginRequest; Username/Password should be omitted for OIDC.
  • Successful response body (200) is plain text containing the full Authorization URL. Example:
https://login.microsoftonline.com/<tenant>/oauth2/v2.0/authorize?...&state=eyJ...&code_challenge=...

Navigate the user agent to this URL.

Possible Errors

Status Reason
400 Missing or empty redirectUrl
400 Generated Authorization URL missing state (configuration issue)

Callback Request

GET /{languageCode}/{companyNumber}/login/oidc/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=eyJhbGciOi... HTTP/1.1
Host: {host}:8001
Accept: application/json
Cookie: (same cookie jar as initiate)

The server:

  1. Validates code and state are present.
  2. Compares state with session value to prevent CSRF/session mix-up.
  3. Retrieves and consumes the cached LoginRequest + PKCE verifier (one-time use).
  4. Exchanges code for tokens and creates/updates the Monitor session.
  5. Returns a LoginResponse JSON structure.

Successful Response (example excerpt)

HTTP/1.1 200 OK
Content-Type: application/json
Set-Cookie: (auth cookies)

{
  "SessionId": "d497f3b1-a91a-4436-9ccd-45dc8c2eba79",
  "MfaToken": null
}

MfaToken is expected to be null for OIDC logins; MFA should be enforced at the Identity Provider.

Possible Errors

Status Reason
400 Missing code or state
400 Invalid state or missing PKCE verifier (stale/incorrect session)
401 Downstream auth failed
403 Access denied (policy)
410 Flow expired
429 Too many attempts

MFA

Monitor's own MFA flow is bypassed for OIDC logins. Enforce multi-factor requirements in your Identity Provider configuration (e.g. Conditional Access in Entra ID). The MfaToken field can be ignored.

Troubleshooting

Symptom Cause Action
400 Invalid state Session cookie lost Ensure cookies preserved (same domain/proxy)
Repeated 400 on callback Redirect URL mismatch Verify exact redirect URL in Entra ID & request
Unexpected 401 User not linked Add OIDC email to user profile and retry
Flow restarts often User reloads initiate page Debounce or suppress duplicate initiate requests