Microsoft Entra ID SSO

Self-hosted LightMesh supports Microsoft Entra ID (Azure AD) login. You choose one Azure AD type (secret or certificate). You can turn it on from the UI, from environment variables, or migrate from env to the UI later.

Azure AD type (pick one)

LightMesh configuration (UI preferred; env still supported)

Before you enable Microsoft login: set INVITE_ONLY=true (recommended), or understand what happens without it. With invite-only off, LightMesh creates every first-time Microsoft user as an admin and links them to the primary organization as Owner. Restrict who can authenticate in Entra (single tenant + assignment required) and keep invite-only on unless you intentionally want that auto-provisioning.

SaaS: Personal Microsoft linking on SaaS is different — see Sign-in Methods → Microsoft. This page is self-hosted organization-wide Azure AD only.

Azure AD type: secret-based

1. Register the app (single tenant)

Sign in to portal.azure.com. Open Microsoft Entra ID → App registrations → New registration (same path as certificate mode).

When you register:

1. Supported account types: choose Accounts in this organizational directory only (Single tenant). Do not use multi-tenant or personal Microsoft accounts for self-hosted LightMesh.
2. Add a Web redirect URI (next step), then create the app.

2. Redirect URI

Add a Web redirect URI:

https://<your-lightmesh-api-host>/auth/microsoft/callback

Local example: http://localhost:3001/auth/microsoft/callback

3. Client secret

Certificates & secrets → Client secrets → New client secret. Copy the Value immediately (Azure shows it once).

4. Application (client) ID and Directory (tenant) ID

From Overview, copy both IDs. Always use your Directory (tenant) ID GUID (or verified domain) in LightMesh — never common, organizations, or consumers.

5. Who can sign in (required)

1. Open Enterprise applications → (your app) → Properties, and set Assignment required? to Yes.
2. Open Users and groups, then assign only the users or groups that should use LightMesh.

6. API permissions

Secret mode only needs the default delegated Microsoft Graph permission User.Read. You do not need application permissions or admin consent for LightMesh sign-in.

Then configure LightMesh with either the UI or environment variables (secret columns).

Azure AD type: certificate-based

1. App registration (single tenant)

Register with Accounts in this organizational directory only (Single tenant).

2. Client ID and Tenant ID

3. Redirect URI

Add a Web redirect URI (certificate / MSAL flow — not the secret callback):

https://<your-lightmesh-client-host>/auth/redirect

Local example: http://localhost:3000/auth/redirect

You can register both redirect URIs on the same Azure app. LightMesh only enables one type at a time — if secret is already saved and enabled, remove that saved config before enabling certificate (and the other way around).

4. Upload the public certificate

Upload the public cert under Certificates & secrets → Certificates. Keep the private key only on the LightMesh host.

5. Thumbprint

Copy the certificate thumbprint (SHA-1).

• UI: paste as shown (with or without colons). LightMesh strips colons, spaces, and hyphens on paste.
• Environment variable (AZURE_THUMBPRINT): store the value without colons.

6. Private key for LightMesh

# Create key + cert if you do not already have them
# -nodes writes an unencrypted key (quick start). Prefer encrypting the key and
# setting AZURE_PASSPHRASE / the UI passphrase field, then delete key.pem after
# you base64 it into LightMesh.
openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out cert.pem

# Optional: encrypt the private key instead of -nodes
# openssl genrsa -aes256 -out key.pem 2048
# openssl req -new -x509 -key key.pem -out cert.pem -days 365

# Thumbprint (UI strips colons on paste; for AZURE_THUMBPRINT remove colons)
openssl x509 -in cert.pem -fingerprint -sha1 -noout

# Base64-encode the private key for LightMesh
base64 < key.pem | tr -d '\n'

Upload only cert.pem to Azure. Store the base64 private key in LightMesh (UI or AZURE_CERT_KEY). Delete local key.pem after you have stored the base64 value securely.

7. Who can sign in and API permissions

Same as secret mode: on the enterprise application Properties, set Assignment required? to Yes; in Users and groups, assign only the groups that should use LightMesh; keep API permissions minimal. Certificate mode requests OIDC scopes openid profile email offline_access at sign-in — no application permissions or admin consent are required for LightMesh.

8. Authority URL (workforce vs External ID)

LightMesh needs the correct authority:

If you leave Authority empty on a workforce tenant, LightMesh defaults to the CIAM-style URL and OpenID discovery will fail.

Then configure LightMesh with either the UI or environment variables (certificate columns).

LightMesh: from the UI

Requirement: Azure AD is not how you create the first admin. Create (or keep) an organization Owner / Administrator that can sign in without Azure AD — typically email/password. Sign in with that account, then enable Azure AD. Prefer INVITE_ONLY=true before you turn Microsoft login on (see the note at the top of this page).

1. Open Account → Sign-in Methods. You should see the Microsoft / Azure AD row (Disabled until you save and enable — or Enabled if environment variables already drive login).

2. Click Configure.
3. Choose Secret or Certificate (must match what you set up in Azure). LightMesh allows only one mode enabled at a time. If the other mode is already saved and enabled, the modal warns you to Remove saved config before enabling the new mode.
4. Paste the Azure values. The modal shows the redirect URI to register in Azure if you have not already. Env values are not prefilled — re-enter them when migrating from environment variables.
5. Click Test connection to check tenant/authority reachability (and that a certificate private key loads) before you turn login on. See Test connection.
6. Click Save and enable.

When the config is already enabled, the same modal shows Save changes, Test connection, Disable, and Remove saved config.

UI — secret-based

Auth mode Secret. Enter Application (client) ID, client secret, and your Directory (tenant) ID GUID or domain — never common / organizations / consumers. Redirect URI is {API_URL}/auth/microsoft/callback. Use Test connection, then Save and enable.

UI — certificate-based

Auth mode Certificate. Enter Application (client) ID, Azure tenant subdomain, thumbprint, and base64 private key. Redirect URI is {CLIENT_URL}/auth/redirect. Paste the thumbprint with or without colons — the UI normalizes it.

Authority URL:

• Workforce Entra: set https://login.microsoftonline.com/<Directory-tenant-ID>/.
• Entra External ID (CIAM): leave blank or paste https://<subdomain>.ciamlogin.com/<subdomain>.onmicrosoft.com/.

Use Test connection (and Save changes when already enabled).

Test connection

Test connection does not fully validate credentials:

• Secret mode: checks that the tenant’s OpenID discovery URL answers. The client secret is verified only on the first real sign-in.
• Certificate mode: checks that the private key loads and the authority’s OpenID discovery answers. The thumbprint match is verified when a user signs in.

Fix any error it returns, then Save and enable (or Save changes if already enabled).

No restart after a successful save — LightMesh reloads the auth config.

Moving from environment variables to the UI

Existing installs that already use env vars keep working. LightMesh does not copy those values into Sign-in Methods automatically.

1. Sign in as Owner/Admin (email/password or another non–Azure AD method).
2. Open Account → Sign-in Methods. The Microsoft / Azure AD row shows Enabled with copy that login is driven by environment variables.

3. Click Configure. Fields start empty. A blue notice explains that env vars are in use and that Save and enable takes precedence over them (no restart).

4. Enter the same Azure values (secret or certificate), run Test connection, then Save and enable.
5. Confirm status becomes enabled from saved deployment settings. Env vars are ignored for credentials while that UI config stays enabled.
6. After a successful login test, remove the old env vars and restart when convenient so you are not maintaining two sources of truth.

Caution: an enabled but incomplete UI config fails closed — LightMesh does not fall back to env. Fix or Remove saved config if login breaks after a partial save.

LightMesh: from environment variables

Use when you prefer env-based config, or before any UI admin exists that can reach Sign-in Methods. Restart LightMesh after changes.

If an in-app config is enabled, it takes precedence over env for that mode. Env-only installs do not need the UI. To manage the same setup in-app later, see Moving from environment variables to the UI.

Also set INVITE_ONLY=true unless you intentionally want first-time Microsoft users auto-created as Owner/admin (see the note at the top of this page).

Secret-based

Certificate-based

Verify

1. Login page shows the Microsoft and/or Azure AD button for the type you enabled.
2. Sign in and confirm you land in the app.
3. On failure, check: redirect URI exact match (http/https, host, path); secret vs certificate type matches Azure and LightMesh; for certificate, workforce vs CIAM authority is correct; invite-only and Entra assignment match your access policy.

Troubleshooting

Related

• Self-hosted authentication overview
• SaaS Sign-in Methods — Microsoft (personal linking)