Microsoft Entra SSO

Connect Microsoft Entra ID (formerly Azure AD) so employees sign in to your workspace with their corporate Microsoft account. This is an OAuth integration: it carries identity, not group claims. To map Entra groups to OnTrackio roles, configure Entra as a SAML identity provider instead — see the SAML SSO guide.

:::note Before you begin You need:

• Microsoft Entra admin access on an active Entra directory (tenant). A personal Microsoft account without a directory cannot register an app — see If you do not have a directory.
• OnTrackio super-admin access on your workspace (<slug>.app.ontrackio.com).
• Your workspace subdomain, in the form <slug>.app.ontrackio.com. Each subdomain needs its own redirect URI.

Allow 15–20 minutes. :::

What you get

OnTrackio signs users in through the azure OAuth provider and reads basic profile fields. It does not pull groups, photos, or directory attributes.

Capability	Supported	Notes
Sign in with a corporate Microsoft account	Yes	Adds a Continue with Microsoft button to /login
First name, last name, email from the Entra profile	Yes	Cached on the OnTrackio user record
Just-in-time user provisioning	Yes	A new email creates a user with the employee role
Single-directory pinning	Yes	Set Directory (tenant) ID to a GUID, or common for any directory
Email-domain allowlist	Yes	The security boundary when the directory is common
External-collaborator bypass	Yes	Users flagged external skip the domain check
Avatar / profile photo	No	Microsoft Graph does not return a usable photo URL; users upload one under My → Profile
Group-based role assignment	No	OAuth carries no groups — use SAML SSO

If you do not have a directory

Entra app registrations require an active directory. A consumer Microsoft account on its own shows "These applications are associated with the account but are not contained within any directory" and blocks + New registration. Get a directory one of three ways:

Path	When to use it	Notes
Use an existing Entra/Azure tenant	Your organization already runs Microsoft 365	Ask an admin to add you, or grant you the Application Developer role. The simplest path.
Sign up for Azure	New setups	Start at the Azure free tier. The Entra Free tier is permanent and covers everything OnTrackio needs. Sign-up takes ~10 minutes and asks for a card (no charge until you upgrade).
Microsoft 365 Developer Program	You already hold an M365 subscription	The free sandbox tenant (25 test users) is now reserved for accounts with an existing M365 subscription. If you do not qualify, use one of the paths above.

Step 1 — Register the app in Microsoft Entra

1. Sign in to the Microsoft Entra admin center with an account that has admin access to a directory.

2. Go to Identity → Applications → App registrations → New registration.

3. Set Name to OnTrackio ITAM (add your workspace slug if you run more than one workspace).

4. Choose Supported account types:

   Account type	Choose when	Pair with
   Accounts in this organizational directory only (single tenant)	Only users in your directory sign in	A GUID in Directory (tenant) ID
   Accounts in any organizational directory (any tenant)	Partners or customers in other directories also sign in	common in Directory (tenant) ID plus an email-domain allowlist
   Personal Microsoft accounts	Rarely — only for consumer Outlook/Hotmail logins	Not recommended

5. Under Redirect URI, select the Web platform and add:

   https://<slug>.app.ontrackio.com/auth/microsoft/callback

6. Select Register.

7. On the Overview page, copy the Application (client) ID and the Directory (tenant) ID. You paste both into OnTrackio in step 5.

Step 2 — Add a redirect URI for each workspace

Microsoft Entra does not support wildcard redirect URIs. Every workspace subdomain that offers Microsoft sign-in needs its own entry.

1. Open the app → Authentication → Platform configurations → Web.

2. Add one redirect URI per workspace:

   https://workspace-a.app.ontrackio.com/auth/microsoft/callback
   https://workspace-b.app.ontrackio.com/auth/microsoft/callback

3. Under Implicit grant and hybrid flows, leave every option cleared. OnTrackio uses the authorization-code flow.

4. Under Advanced settings → Allow public client flows, leave No. OnTrackio is a confidential client.

5. Select Save.

Step 3 — Create a client secret

1. Open the app → Certificates & secrets → Client secrets → New client secret.
2. Set Description to OnTrackio ITAM client secret.
3. Set Expires to a fixed term — 24 months is a reasonable default, then rotate. Microsoft no longer offers a "never" option.
4. Select Add.
5. Copy the secret Value (not the secret ID) immediately. Entra hides it once you leave the page.

warning

Client secrets always expire. When one lapses, sign-in fails with AADSTS7000222. Set a calendar reminder before the expiry date and rotate — see Troubleshooting.

Step 4 — Grant the required permissions

1. Open the app → API permissions.
2. Confirm Microsoft Graph User.Read is present (it usually is by default). If it is missing, select Add a permission → Microsoft Graph → Delegated permissions and add openid, profile, email, and User.Read.
3. If your directory requires admin consent for these scopes (most do not for basic profile), select Grant admin consent for <your-org>.

OnTrackio requests exactly these four scopes during sign-in. No other Graph permission is needed.

Step 5 — Configure Microsoft Entra in OnTrackio

Paste the credentials from Entra into the Microsoft Entra ID settings card. Saving the card turns sign-in on: the Continue with Microsoft button appears on /login as soon as a client ID is stored and Enable Microsoft SSO is on.

1. Sign in to OnTrackio as a super-admin.

2. Go to Admin → Settings → Integrations and select the Microsoft Entra ID card.

3. Fill in the fields below.

   Field	Required	Default	Value
   Enable Microsoft SSO	Yes	Off	Turn on to show the Continue with Microsoft button on /login. Turning it off hides the button without clearing the credentials.
   Directory (tenant) ID	Yes	common	The Directory (tenant) ID from step 1, or common to allow any directory and rely on the domain allowlist.
   Application (client) ID	Yes	—	The Application (client) ID from step 1.
   Client secret value	Yes	—	The secret Value from step 3, not its ID. Encrypted at rest.
   Redirect URI	No	https://<slug>.app.ontrackio.com/auth/microsoft/callback	Override only if needed. Must match what you registered in Entra.
   Allowed email domains	Conditional	Any account	Comma-separated, for example acme.com, acme.co.uk. Required when Directory (tenant) ID is common; optional otherwise. This list is shared with Google sign-in — the boundary is the email domain, not the provider.

4. Select Save. The Continue with Microsoft button appears on /login immediately.

tip

When the directory is common, the email-domain allowlist is your only boundary against unintended sign-ins. Always set Allowed email domains in that case.

:::note Configuring by environment variable instead You can set the credentials with the AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID, AZURE_REDIRECT_URI, and AZURE_ALLOWED_DOMAINS server variables instead of the settings card. The card takes precedence when both are set, so prefer it. :::

Step 6 — Test the round-trip

1. Open a private browsing window.
2. Go to https://<slug>.app.ontrackio.com/login.
3. Select Continue with Microsoft.
4. Choose the Microsoft account to sign in with.
5. On success, OnTrackio:
   • provisions a first-time user with the employee role and lands them on My → Dashboard;
   • updates last-login time and IP for a returning user and lands them on Admin → Dashboard (admins) or My → Dashboard;
   • records User signed in with Microsoft SSO in the audit log.

How sign-in maps to OnTrackio

Behaviour	Detail
Account match	By Entra object ID first (durable across email changes), then by email
New users	Provisioned with the employee role and a verified email
Domain check	Applied to the email domain, even when the directory is common; an empty allowlist means no restriction
External collaborators	Users flagged external bypass the domain check — the explicit way to admit contractors, vendors, or auditors outside your domains
Email source	Read from the Entra profile, falling back to userPrincipalName or preferred_username
Conditional Access	Honoured automatically on the Microsoft side; if a policy requires MFA, the user clears it with Microsoft before OnTrackio sees them signed in

Troubleshooting

Symptom	What to do
AADSTS50011: The redirect URI does not match	Confirm https://<slug>.app.ontrackio.com/auth/microsoft/callback is registered under Authentication → Web. Use https://, match the path exactly, and add a separate entry per workspace — Entra has no wildcards.
AADSTS50020: User account from identity provider does not exist in tenant	You chose single-tenant but the user is in a different directory. Switch to any organizational directory with an email-domain allowlist, or have the user sign in from your directory.
"Microsoft did not return an email address. Ensure the User.Read scope is granted."	The User.Read scope was dropped or consent revoked. Re-add it under API permissions and grant admin consent.
Continue with Microsoft button missing on /login	Microsoft sign-in is off, or the client ID is blank. Confirm Enable Microsoft SSO is on and Application (client) ID is filled, then save.
"Session expired. Please try again."	A cookie-domain mismatch or expired session cookie. Confirm the workspace session cookie domain matches your subdomain, then retry.
AADSTS7000222: client secret keys are expired	Rotate: create a new secret in Entra → Certificates & secrets, copy its Value, paste it into Client secret value, save, then delete the old secret after a brief overlap.
"Access restricted. Ask your workspace admin to invite you first."	The email domain is outside the allowlist. Add the domain to Allowed email domains, or flag the user as an external collaborator.

Related

SAML SSOMap Entra groups to roles by configuring SAML instead.Read →Google Workspace SSOSet up Google sign-in with the same domain-allowlist model.Read →SCIM provisioningAutomate joiner, mover, and leaver lifecycle from your identity provider.Read →Audit logReview every sign-in and admin action for evidence.Read →