← Dashboard

Microsoft SSO Setup

Choose between OpenID Connect (recommended) or SAML 2.0 (advanced).

👤 Manage Users STORE_USERS=false — user records not persisted
⚠ This app uses OIDC, not SAML. If you configured SSO under Enterprise applications → Single sign-on → SAML, that is the wrong protocol. Follow the steps below which use App registrations with a Web Redirect URI — no SAML configuration needed. The Enterprise Application is only used for user/group assignment, not for protocol configuration.
⚠ SSO not yet configured. App is running in demo mode. Follow the steps below.
1
Create an App Registration (not Enterprise Application)
▾
⚠ Do not use Enterprise Applications → Single sign-on → SAML. Go to App registrations instead. The Enterprise Application is created automatically when you register the app — you only use it later for user assignment.

In Azure Portal go to Microsoft Entra ID → App registrations → New registration.

  1. Set a Name (e.g. uptime-saas)
  2. Under Supported account types choose Accounts in this organizational directory only
  3. Under Redirect URI select platform Web and enter your callback URL:
https://yourdomain.com/auth/callback
ℹ The Redirect URI must be Web platform (not SPA, not Mobile). It must exactly match AZURE_REDIRECT_URI in your .env — including https:// vs http:// and no trailing slash.
  1. Click Register
  2. On the Overview page, copy both the Application (client) ID and the Directory (tenant) ID
✓ Application (client) ID → this is your AZURE_CLIENT_ID
Directory (tenant) ID → this is your AZURE_TENANT_ID
These are different values. Do not mix them up.
2
Create a Client Secret
▾

In your App Registration go to Certificates & secrets → Client secrets → New client secret.

  1. Add a description (e.g. uptime-saas 2026) and choose an expiry
  2. Click Add
  3. Immediately copy the Value column — it is only shown once
⚠ Copy the Value, not the Secret ID. The Value is the long string like abc~defGH.... If you lose it, delete the secret and create a new one.
3
Configure API Permissions
▾

In your App Registration go to API permissions → Add a permission → Microsoft Graph → Delegated permissions.

  1. Search and add: openid, profile, email, User.Read
  2. Click Add permissions
  3. Click Grant admin consent for [your org] and confirm — the status column should show green checkmarks
4
User Assignment via Enterprise Application (optional)
▾

Azure automatically creates an Enterprise Application entry when you register the app. Use it only for controlling who can sign in — not for protocol configuration.

  1. Go to Microsoft Entra ID → Enterprise applications and find your app
  2. Click Properties → set Assignment required to Yes to restrict access to specific users/groups
  3. Go to Users and groups → Add user/group to grant access
⚠ Do not touch the Single sign-on section in the Enterprise Application. Leave it as-is or set to OIDC if prompted. Configuring SAML here will NOT affect this app and will only cause confusion.
ℹ With Assignment required = No (default), any user in your tenant can sign in.
5
Configure Your .env File
▾

Copy .env.example to .env and fill in your values:

# From Azure Portal → App Registration → Overview AZURE_TENANT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx # Directory (tenant) ID AZURE_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx # Application (client) ID # From Certificates & secrets → Client secrets → Value column AZURE_CLIENT_SECRET=your~client~secret~value # Must exactly match the Redirect URI registered in Azure (Web platform) AZURE_REDIRECT_URI=https://uptime.dmsk.duckdns.org/auth/callback # Strong random string for session encryption SESSION_SECRET=replace-with-64-random-chars
  1. Save as .env in the project root
  2. Restart: npm start
  3. Check server console — it should print [auth] OIDC client ready
6
Test & Diagnose
▾

After restarting the server:

  1. Visit /auth/debug — confirms config is loaded correctly without exposing secrets
  2. Open /login and click Sign in with Microsoft
  3. Sign in with your enterprise credentials
  4. On success you are redirected to the dashboard
ℹ If you see a "Token key validation failed" error, it usually means:
  • The SAML SSO was configured on the Enterprise App — ignore it, it doesn't affect OIDC
  • AZURE_TENANT_ID is set to the Application ID instead of the Directory ID
  • The Redirect URI in Azure doesn't exactly match AZURE_REDIRECT_URI in .env
✓ First-time sign-in creates a user record. Subsequent logins reuse it.
⚠ SAML not configured. Set SAML_* env vars to enable SAML 2.0 mode.
ℹ OIDC is recommended for most deployments — it is simpler, more secure, and requires only an App Registration. Use SAML only if your organisation requires it for policy or compatibility reasons. SAML requires npm install passport passport-saml.
1
Create an Enterprise Application with SAML SSO
▾

Go to Azure Portal → Microsoft Entra ID → Enterprise applications → New application → Create your own application.

  1. Name it (e.g. uptime-saas-saml), select Integrate any other application you don't find in the gallery
  2. Click Create
  3. Go to Single sign-on → SAML
ℹ Unlike OIDC which uses App Registrations, SAML is configured directly on the Enterprise Application.
2
Configure Basic SAML Settings
▾

In Basic SAML Configuration set:

https://yourdomain.com/auth/saml/metadata
Must exactly match SAML_ISSUER in .env
https://yourdomain.com/auth/saml/callback
Must exactly match SAML_CALLBACK_URL in .env
⚠ The Reply URL is a POST endpoint — Azure will POST the SAML assertion to it. This is different from OIDC which uses a GET redirect.
3
Download the Certificate and Copy Login URL
▾

In SAML Certificates:

  1. Click Download next to Certificate (Base64) — save the .cer file
  2. Open it in a text editor — copy everything between -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- (the Base64 block only)
  3. Paste this as SAML_CERT in your .env (the app strips headers automatically)

In Set up [your app] (step 4 in Azure's UI):

  1. Copy the Login URL → set as SAML_ENTRY_POINT
4
Configure .env for SAML
▾
# SAML 2.0 mode — use INSTEAD of AZURE_CLIENT_ID/SECRET/TENANT_ID SAML_ENTRY_POINT=https://login.microsoftonline.com/{tenant-id}/saml2 SAML_ISSUER=https://yourdomain.com/auth/saml/metadata SAML_CALLBACK_URL=https://yourdomain.com/auth/saml/callback SAML_CERT=MIIxxxxx...base64cert...xxxxx= # Required: install SAML packages # npm install passport passport-saml
ℹ Do not set AZURE_CLIENT_ID when using SAML — the app detects which mode to use based on which env vars are present. If both are set, OIDC takes precedence.
5
Assign Users and Test
▾
  1. In the Enterprise Application → Users and groups → Add user/group to grant access
  2. Set Properties → Assignment required → Yes to restrict to assigned users only
  3. Restart the server: npm start
  4. Visit /login → click Sign in with Microsoft (SAML)
  5. Verify metadata is served at /auth/saml/metadata
✓ First-time sign-in creates a local user record (unless STORE_USERS=false). Subsequent logins reuse the existing record.