Microsoft Entra (SAML) SSO Setup
Configure SAML 2.0 Single Sign-On between a Xelon HQ organization and Microsoft Entra ID.
Overview
In this integration Xelon HQ is the Service Provider (SP) and Microsoft Entra ID is the Identity Provider (IdP). Setup is a two-sided exchange: Entra needs four URLs from Xelon HQ (the SP metadata), and Xelon HQ needs three URLs plus a signing certificate from Entra (the IdP metadata). You then verify your email domain(s), map Entra groups to Xelon HQ permissions, create at least one emergency password account, and finally switch SSO on.
When you turn on Enable SSO, every user whose email is on a verified SSO domain is switched to Microsoft-only login immediately. If the configuration is wrong, the only accounts that can still sign in are the breaking-glass users. Create those first.
Where SSO is configured
SSO settings live on the organization detail page:
Open the organization
In the sidebar, open Manage My Organization for your own organization, or Manage All Organizations and select an organization you administer.
Find the Microsoft Authentication card
Scroll to the Microsoft Authentication card. It shows the current SSO status (Enabled / Disabled), the number of Domains and Permission Bundles, and — when Graph sync is on — the Last Microsoft Graph sync time with a Sync now link.
Click Edit
Click Edit to open the Microsoft Authentication dialog, where all of the sections below appear on a single scrolling page.
The dialog has no single "Save" button. Every section (Attribute Claims, Identity Provider, each certificate, each domain, each bundle, each breaking-glass user, and the Enable SSO / Graph toggles) is saved by its own button and takes effect as soon as you save it.
Prerequisites
- A Microsoft Entra ID tenant, with a role that can create enterprise applications and grant admin consent (Global Administrator or Application Administrator; Global Administrator is required for the optional Graph sync consent).
- Access to the public DNS zone for each email domain you will use for SSO (for the ownership TXT record).
- The Microsoft Authentication card visible on your organization page. Visibility requires the
allow_manage_microsoft_authenticationpermission — a special permission that is not part of the standard permission picker. If the card is missing, contact Xelon to have it granted. (Breaking-glass users can also edit SSO for their own organization.)
The Microsoft Authentication dialog
The dialog contains these sections, top to bottom:
| Section | Purpose | Required |
|---|---|---|
| Status | The Enable SSO toggle and Password Login Exceptions (Breaking glass users). | Breaking-glass user required to enable SSO |
| Attribute Claims | The SAML attribute names Entra sends (email, first name, last name, group). | Yes (defaults are pre-filled) |
| Service Provider (SP) | Read-only. The four URLs you paste into Entra. | — |
| Identity Provider (IdP) | The three URLs you copy from Entra. | Yes |
| X.509 Certificate | The public certificate Entra signs assertions with. | Yes (at least one non-expired) |
| SSO Domains | Email domains that trigger Microsoft sign-in, verified by DNS TXT. | Yes (at least one verified) |
| Group → Permission Bundles | Maps Entra group Object IDs to sets of Xelon HQ permissions. | Yes, in practice — see note below |
| Lifecycle Sync (Microsoft Graph) | Optional background reconciliation of users against Entra via Graph. | Optional |
The toggle itself is blocked only until you have (1) at least one verified SSO domain and (2) at least one breaking-glass user. Everything else (IdP URLs, claims, an active certificate, a permission bundle) is enforced at login instead: a "SSO is enabled but not ready" banner lists whatever is still missing, and users cannot sign in until it clears. Treat all of the "Required" rows above as hard prerequisites.
Step 1 — Create the Entra enterprise application
In the Microsoft Entra admin center (or the Azure portal):
Go to Enterprise applications
Open Entra ID → Enterprise applications.
Create your own application
Click New application, then Create your own application. Give it a name (for example Xelon HQ SSO), choose Integrate any other application you don't find in the gallery (Non-gallery), and click Create.
Open the SAML setup
In the new application, open Single sign-on and choose SAML.
Menu labels inside the Microsoft Entra admin center are Microsoft's and can change without notice. The Xelon HQ field names in this guide are the authoritative reference; match them to the equivalent Entra fields.
Step 2 — Paste the SP URLs into Entra
In the Xelon HQ dialog, open the Service Provider (SP) section. It shows four read-only fields, each with a Copy button. These values contain your organization's unique identifier and are different for every organization — never reuse them between organizations.
| Xelon HQ field | Entra field (Basic SAML Configuration) |
|---|---|
| SP Entity ID (Identifier) | Identifier (Entity ID) |
| Reply URL (ACS URL) | Reply URL (Assertion Consumer Service URL) |
| Sign-on URL | Sign on URL |
| Logout URL (SLS URL) | Logout URL |
If the Logout URL is not configured in Entra, SAML Single Logout (SLS) will not work, but SSO login still functions normally.
Step 3 — Configure attribute claims
Xelon HQ maps four SAML attributes to user data. The defaults in the Attribute Claims section match a standard out-of-the-box Entra configuration — only change them if your tenant uses custom claim names.
| Field | Default value |
|---|---|
| Email claim | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress |
| First name claim | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname |
| Last name claim | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname |
| Group claim | http://schemas.microsoft.com/ws/2008/06/identity/claims/groups |
Click Save in this section after any change.
Unlike the other three claims, Entra does not emit a groups attribute unless you add it. In the Entra application, go to Attributes & Claims, choose Add a group claim, select Security groups (not All groups — this avoids token-size problems), and set the source attribute to Group ID (the group Object ID, a UUID). If the assertion arrives with no group values, the login is rejected.
Step 4 — Download the signing certificate from Entra
Entra signs every assertion with a private key; Xelon HQ verifies the signature with the matching public certificate.
Open SAML Certificates
In the Entra application's Single sign-on page, find the SAML Certificates section and the certificate row marked Active.
Download Certificate (Base64)
Download the Certificate (Base64) — a .cer file. Do not download "Certificate (Raw)" or "Federation Metadata XML"; Xelon HQ expects a Base64-encoded X.509 PEM certificate.
Note the expiry date
Entra signing certificates expire (typically after 1–3 years). Set a reminder at least 30 days before expiry so you can rotate without downtime — see Certificate rotation.
Step 5 — Enter the IdP URLs in Xelon HQ
In the Entra application's Single sign-on page, the "Set up" section (labelled section 4 in Entra's numbered layout) lists three values. Copy them into the Identity Provider (IdP) section of the Xelon HQ dialog:
| Entra value | Xelon HQ field |
|---|---|
| Login URL | Login URL (IdP SSO URL) |
| Microsoft Entra Identifier | Microsoft Entra Identifier |
| Logout URL | Logout URL (IdP SLS URL) |
All three are required. Click Save in the section.
Xelon HQ re-checks that the Issuer in every assertion equals the stored Microsoft Entra Identifier, character for character. A trailing slash or a copy-paste error here causes an "Issuer binding failed" rejection at login.
Step 6 — Upload the certificate in Xelon HQ
Open the X.509 Certificate section
Scroll to X.509 Certificate and the Add certificate box.
Drop the file
Drag the file onto the dropzone, or click it to browse. Accepted file types are .cer, .crt, .pem, and .txt, as long as the contents are a Base64-encoded X.509 PEM certificate (starting with -----BEGIN CERTIFICATE-----, or raw Base64).
Add it
Click Add certificate. The expiry date is read from the file automatically, and the certificate appears in the list with an Active badge. You can expand a row to view the PEM body, or use the trash icon to remove it.
Xelon HQ accepts more than one active certificate at a time and tries each until one validates the assertion. This is what makes zero-downtime rotation possible.
Step 7 — Add and verify SSO domains
A user only sees the Microsoft option if their email address belongs to a verified domain. Unverified domains are ignored.
Add the domain
In SSO Domains, type your email domain (for example example.com) and press Enter. It appears with a Pending verification badge. Domains are stored lower-case.
Create the DNS TXT record
Each pending domain shows three copy fields — Record type (TXT), Host / Name, and Value (a unique token). Add exactly that record at your DNS provider, matching the case of the token.
Verify
After DNS has propagated (a few minutes to several hours), click Verify now. When the token resolves, the badge changes to Verified. Pending domains are also re-checked automatically once an hour, so a domain can flip to Verified on its own if you don't return to the page.
If your organization uses the Allowed Email Domains registration whitelist, a domain is added to that list automatically once it is verified here. When you later remove an SSO domain, Xelon HQ asks whether to also remove it from Allowed Email Domains (and keeps it there if active users still have an email on that domain).
Step 8 — Map Entra groups to permission bundles
Permission Bundles are the authorization layer. Each bundle links one Entra group Object ID to a set of Xelon HQ permissions. On every login, Xelon HQ reads the user's group IDs from the assertion and grants the union of all matching bundles' permissions; permissions from bundles that no longer match are revoked.
Find the group Object ID in Entra
Entra admin center → Groups → your group → Overview → Object ID. It is a UUID (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx), not the display name.
Add a bundle
In Group → Permission Bundles, click Add bundle. Enter a Name (for example "Admins"), an optional Description, and paste the group's Entra Group Object ID.
Pick permissions
Click … permissions selected to open the Edit Permissions picker. Permissions are grouped by category with search and "Select all" per category. Click Apply, then Create.
Existing bundles are edited inline in the table and saved per row; the trash icon deletes a bundle (which revokes its SSO-granted permissions on the members' next login).
If a user is not a member of any Entra group that has a bundle, their login is rejected with a permission error. Create at least one bundle before you enable SSO.
Step 9 — Create breaking-glass users
Breaking-glass users are local accounts that can always sign in with a password, even while SSO is enabled. They are your recovery path if Entra is unavailable or the configuration is wrong.
Open Password Login Exceptions
In the Status section, find Password Login Exceptions (Breaking glass users) and the Create breaking-glass user box.
Fill in the account
First name and Surname are pre-filled with "Breaking glass" / "user" — change them to something meaningful. Enter a unique Email (must pass an MX/DNS check and not already exist), an optional Phone, and a Password with confirmation.
Generate and store the password
Generate password creates a 10-character random password with numbers and symbols. Record the email and password in your password manager or vault now — then click Create user.
Each breaking-glass account is created with a fixed set of permissions so it can run an incident from start to finish:
allow_manage_microsoft_authentication— repair or disable SSOallow_manage_organization_security— organization security settings (2FA, allowed domains)allow_view_organizationsallow_manage_users
A single breaking-glass account is a single point of failure. Keep at least two, with credentials held by different people (for example one with IT, one with a trusted executive). You cannot remove the last breaking-glass user while SSO is enabled — add another first, or disable SSO. The permissions of a breaking-glass account cannot be edited afterwards.
Step 10 — Enable SSO
Run the pre-flight check
Confirm: IdP URLs saved; at least one active certificate; at least one verified domain; at least one permission bundle with a valid group Object ID; attribute claims correct (especially the group claim); at least one breaking-glass user with credentials stored. Optionally use Entra's own Test button on the Single sign-on page.
Toggle Enable SSO
In the Status section, switch Enable SSO on. A confirmation dialog (Enable Microsoft SSO) explains the impact; read it and click Enable SSO.
Verify in a private window
Open an incognito window, go to the Xelon HQ login page, enter an email on a verified domain, click Next, then Continue with Microsoft. Complete the Entra login and confirm the user lands in Xelon HQ with the expected permissions.
Every user whose email is on a verified SSO domain is switched to Microsoft-only login immediately — password login stops working for them. Breaking-glass users are the only exception. An administrator can still revert an individual user to password login afterwards.
If two-factor authentication is not enabled for the organization, Xelon HQ shows a security warning when SSO is on. Enabling organization-level 2FA means breaking-glass logins are protected by more than a password. See Two-Factor Authentication.
Step 11 — (Optional) Microsoft Graph lifecycle sync
Lifecycle Sync is an optional background feature. When on, Xelon HQ periodically re-checks every active SSO user against the Microsoft Graph API: users disabled or removed in Entra are signed out and deactivated in Xelon HQ, and changed group membership re-syncs permissions.
Graph sync uses an Entra App registration with application permissions — not the enterprise application used for SAML.
Create the App registration
Entra admin center → App registrations → New registration. Name it (for example "Xelon HQ Graph Sync"), choose single-tenant, no redirect URI, and register. From Overview, note the Application (client) ID and Directory (tenant) ID.
Add API permissions and grant consent
API permissions → Add a permission → Microsoft Graph → Application permissions. Add GroupMember.Read.All and User.Read.All — nothing broader. Then click Grant admin consent (Global Administrator only). Without consent, sync fails with an insufficient-permissions error.
Create a client secret
Certificates & secrets → New client secret. Set a description and expiry (up to 24 months). Immediately copy the Value — not the Secret ID — because Azure only shows it once.
Configure it in Xelon HQ
In Lifecycle Sync (Microsoft Graph), turn on Enable Microsoft Graph lifecycle sync, then fill in Directory (Tenant) ID, Application (Client) ID and Client Secret (Value). Click Test connection to validate, then Save. The secret is stored encrypted and never shown again (the field displays a masked placeholder once saved).
Sync behaviour:
- A scheduled task runs every 5 minutes while SSO is enabled. Individual users are only re-checked when they are online (the check piggybacks on the browser's stay-alive heartbeat), so there is no polling load when nobody is active.
- Sync now on the Microsoft Authentication card triggers an immediate run and reports how many users were processed, created, restored, and disabled.
- The card shows Last Microsoft Graph sync with a relative timestamp. A failed badge means bad credentials or missing admin consent; a re-syncing badge means the delta token expired and the next run does a full re-scan (normal after a long idle period).
- Client secrets expire after up to 24 months. If sync stops working unexpectedly, generate a new secret in Entra and paste it into Xelon HQ.
Certificate rotation (zero-downtime)
Because Xelon HQ accepts multiple active certificates at once, you can rotate an expiring Entra certificate without any SSO outage. The order matters: Xelon HQ must have the new certificate before Entra starts signing with it.
Create the new certificate in Entra
Single sign-on → SAML Certificates → New certificate. Save it, but do not make it active yet.
Download it (Base64)
Download the new certificate in Base64 format.
Upload it to Xelon HQ
Add the new certificate in the X.509 Certificate section. Both the old and new certificates are now active in Xelon HQ.
Activate the new certificate in Entra
Make the new certificate active in Entra. Entra now signs assertions with the new key, which Xelon HQ already trusts.
Test, then remove the old one
Perform a test SSO login. Once it succeeds, delete the old certificate from the Xelon HQ list with the trash icon.
If you activate the new certificate in Entra before uploading it to Xelon HQ, every SSO login fails with a signature-validation error during the gap.
The end-user login experience
Xelon HQ uses an email-first login flow:
- The user enters their email address and clicks Next.
- Xelon HQ checks the email's domain. If it is a verified SSO domain, the form shows a Continue with Microsoft button; otherwise the user is asked for a password as usual.
- Clicking Continue with Microsoft redirects to Entra. After authenticating, the user is returned to Xelon HQ and signed in.
If Microsoft sign-in fails, the user is sent back to the login page with a short message shown as a notification. The specific technical cause is written to the organization's logs, not shown in the browser. See Troubleshooting.
Security checklist
Review these after every SSO configuration change:
- Signature algorithm — Entra must sign with SHA-256 or stronger. Xelon HQ rejects SHA-1 (RSA-SHA256/384/512 are accepted).
- Certificate expiry monitoring — set a reminder 30 days before the Entra certificate expires; an expired certificate with no replacement is an immediate SSO outage.
- Breaking-glass credentials — stored in a vault, and test-logged-in periodically.
- At least two breaking-glass users, held by different people.
- Organization 2FA enabled — so breaking-glass logins are not password-only.
- Graph secret rotation — track the client secret's expiry and rotate before it lapses.
- Minimal Graph consent — the App registration needs only
GroupMember.Read.AllandUser.Read.All. - Test after any Entra change — a new certificate or claim change should be verified in a private browser window.