Microsoft SSO Setup Guide

Microsoft Entra SAML 2.0 Authentication Setup

Table of Contents

  1. Overview
  2. Prerequisites
  3. Step 1 — Create an Enterprise Application in Microsoft Entra
  4. Step 2 — Configure Basic SAML Settings (SP URLs)
  5. Step 3 — Configure Attribute Claims
  6. Step 4 — Download the X.509 Certificate
  7. Step 5 — Configure Identity Provider (IdP) URLs in HQ
  8. Step 6 — Upload Certificate in HQ
  9. Step 7 — Add and Verify SSO Domains
  10. Step 8 — Configure Group → Permission Bundles
  11. Step 9 — Create Breaking Glass Users
  12. Step 10 — Enable SSO
  13. Step 11 — (Optional) Microsoft Graph Lifecycle Sync
  14. Certificate Rotation (Zero-Downtime)
  15. Troubleshooting
  16. Security Checklist

1. Overview

Xelon HQ supports Microsoft Single Sign-On (SSO) via the SAML 2.0 protocol. HQ acts as the Service Provider (SP), and Microsoft Entra ID (formerly Azure Active Directory) acts as the Identity Provider (IdP). Users sign in once with their Microsoft credentials, and HQ trusts the assertion that Entra returns.

Key characteristics of the SAML flow:

  • Protocol: SAML 2.0 (not OAuth/OIDC).
  • JIT provisioning: users are created automatically on first login — no pre-import needed.
  • Group-based permissions: access rights come from Entra group membership (mapped to HQ Permission Bundles).
  • When enabled, password login is blocked for all users except "Breaking Glass" accounts.
  • A SHA-256 or stronger signature algorithm is required; SHA-1 is rejected.

🚫 IMPORTANT: Do not enable SSO until you have completed ALL configuration steps and created at least one Breaking Glass user. An incomplete setup combined with enabled SSO can lock all users out of the organization.

2. Prerequisites

Before starting, ensure you have:

  • An active Microsoft Entra ID (Azure AD) tenant with Global Administrator or Application Administrator role.
  • Access to the DNS zone for your organization's email domain (e.g., Company.com) — needed for domain verification.
  • Permission allow_manage_microsoft_authentication in HQ.
  • The "Microsoft Authentication" card visible in Xelon HQ → Manage My Organization (or Manage All Organizations → select your organization).

3. Step 1 — Create an Enterprise Application in Microsoft Entra

You must create a dedicated Enterprise Application in Entra that represents HQ as a SAML Service Provider.

Navigation path in Entra

Microsoft Entra admin center → Enterprise applications → + New application → + Create your own application

Steps

  1. Open Microsoft Azure and navigate to Microsoft Entra ID → Enterprise applications.
  2. Click + New application, then + Create your own application.
  3. Enter a descriptive name, e.g. Xelon HQ SSO.
  4. Select "Integrate any other application you don't find in the gallery (Non-gallery)" and click Create.
  5. After the app is created, go to Single sign-on → SAML.

4. Step 2 — Configure Basic SAML Settings (SP URLs)

HQ generates four SP URLs that must be pasted into Entra. These URLs are available in the "Microsoft Authentication" modal → "Service Provider (SP)" section.

Where to find SP URLs in HQ

HQ → Manage My Organization (or Manage All Organizations → [your org]) → Microsoft Authentication card → Edit → "Service Provider (SP)" section. Each field has a Copy button.

Where to paste them in Entra

Enterprise Applications → [your app] → Single sign-on → Basic SAML Configuration (Section 1) → Edit

SP Entity ID (Identifier) Paste into "Identifier (Entity ID)"
Reply URL (ACS URL) Paste into "Reply URL (Assertion Consumer Service URL)"
Sign-on URL Paste into "Sign on URL"
Logout URL (SLS URL) Paste into "Logout Url (Optional)"

ℹ️ All four fields are required. If "Logout URL" is not configured, single-logout (SLS) will not work, but SSO login will still function.

⚠️ The SP URLs contain the tenant's unique identifier. They are different for every organization — do not reuse URLs from one organization's config in another.

5. Step 3 — Configure Attribute Claims

SAML attribute claims are the pieces of user data that Entra sends with each login assertion. HQ maps these claims to user fields (email, first name, last name) and to group membership.

Navigation in Entra

Enterprise Applications → [your app] → Single sign-on → Attributes & Claims (Section 2) → Edit

Default claim values (standard Entra setup)

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

Adding the Group Claim (mandatory, not default)

🚫 The group claim is NOT sent by default. You must explicitly add it, otherwise group-based permission bundles will never receive group data and all SSO logins will be rejected.

To add the group claim:

  1. In Attributes & Claims, click "Add a group claim".
  2. Select "Security groups" (not "All groups" — this avoids token size issues).
  3. Under "Source attribute", select "Group ID" (this is the Object ID — a UUID, not a display name).
  4. Save.

⚠️ If the group claim is missing from the SAML assertion, the user will be rejected at login.

Custom claim names

If your Entra tenant uses custom claim URIs (e.g., you renamed "emailaddress" to something else), update the corresponding fields in HQ → Microsoft Authentication → Attribute Claims section. The HQ defaults match a standard out-of-the-box Entra configuration.

6. Step 4 — Download the X.509 Certificate

Entra signs every SAML assertion with a private key. HQ validates the signature using the corresponding public certificate. You must download the certificate from Entra and upload it to HQ.

Navigation in Entra

Enterprise Applications → [your app] → Single sign-on → SAML Certificates (Section 3)

Download steps:

  1. Find the row with Status = "Active".
  2. Click "Download Certificate (Base64)" — this gives you a .cer file.
  3. Keep this file — you will upload it to HQ in Step 6.

⚠️ Always download "Certificate (Base64)" — NOT "Certificate (Raw)" or "Federation Metadata XML". HQ expects the Base64-encoded X.509 PEM format.

ℹ️ Note the certificate expiry date! Entra certificates expire every 1–3 years. Set a calendar reminder at least 30 days before expiry so you have time to rotate without downtime. See Section 14 for rotation procedure.

7. Step 5 — Configure Identity Provider (IdP) URLs in HQ

You need to copy three URLs from Entra into the HQ "Identity Provider (IdP)" section.

Where to find IdP URLs in Entra

Enterprise Applications → [your app] → Single sign-on → Set up [app name] (Section 4)

Login URL Copy from Entra "Section 4 → Login URL" → paste into HQ "Login URL (IdP SSO URL)"
Microsoft Entra Identifier Copy from Entra "Section 4 → Microsoft Entra Identifier" → paste into HQ "Microsoft Entra Identifier"
Logout URL Copy from Entra "Section 4 → Logout URL" → paste into HQ "Logout URL (IdP SLS URL)"

8. Step 6 — Upload Certificate in HQ

Upload the Base64 certificate file downloaded in Step 4 to the "X.509 Certificate" section in HQ.

Upload procedure

  1. In the Microsoft Authentication modal, scroll to "X.509 Certificate".
  2. Drag and drop the .cer file onto the dropzone, or click the dropzone to browse.
  3. The filename appears, and the expiry date is automatically read from the certificate file.
  4. Click "Add certificate". It will appear in the certificate list with status "Active".

✅ HQ supports multiple active certificates simultaneously. This allows zero-downtime rotation (add new cert → switch Entra → remove old cert). See Section 14.

ℹ️ Accepted file types: .cer, .pem, .crt, .txt — as long as the content is Base64-encoded X.509 PEM. The file must start with -----BEGIN CERTIFICATE----- (or raw Base64).

9. Step 7 — Add and Verify SSO Domains

SSO domains determine which users see the "Sign in with Microsoft" button. A user whose email belongs to a verified domain will be redirected to Entra. Unverified domains are ignored.

Add a domain

  1. In the "SSO Domains" section, type your email domain (e.g., Company.com) and press Enter.
  2. The domain appears with status "Pending verification".

Verify domain ownership via DNS TXT record

HQ generates a unique DNS TXT record. You must add it at your DNS provider to prove domain ownership.

Record type TXT
Host / Name The value shown in HQ (often the domain itself, e.g., Company.com)
Value A unique token provided by HQ — copy it exactly, including case
  1. Copy the three values (Record type, Host, Value) from HQ using the "Copy" buttons.
  2. Log in to your DNS provider (Cloudflare, GoDaddy, Route53, etc.) and add a new TXT record.
  3. Wait for DNS propagation — this can take from a few minutes to several hours.
  4. Return to HQ and click "Verify now". If the TXT record resolves, the domain becomes "Verified".

⚠️ DNS propagation is not instant. If "Verify now" says the record was not found, wait 5–30 minutes and try again. Use a tool like DNS Checker - DNS Check Propagation Tool to monitor propagation globally before retrying.

ℹ️ If your organization uses "Allowed Email Domains" (registration whitelist), HQ automatically adds verified SSO domains to that list. When you later remove an SSO domain, HQ will ask whether to also remove it from Allowed Email Domains.

10. Step 8 — Configure Group → Permission Bundles

Permission Bundles are the authorization layer of the SAML integration. They map Entra group Object IDs to sets of HQ permissions. On every login, HQ reads the user's group membership from the SAML assertion and grants or revokes permissions accordingly.

🚫 At least one bundle is required before SSO can be enabled. Without a bundle, every SSO login will fail because the user will have no group to be matched against.

Finding the Entra Group Object ID

Navigation in Entra: Microsoft Entra admin center → Groups → [your group] → Overview → Object ID

The Object ID is a UUID in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. This is NOT the group display name — it must be the actual UUID.

Creating a bundle in HQ

  1. Scroll to "Group → Permission Bundles" and click "Add bundle".
  2. Enter a descriptive Name (e.g., "Admins" or "Read-only users").
  3. Optionally enter a Description.
  4. Paste the Entra Group Object ID (UUID of the Entra security group).
  5. Click "permissions selected" to open the Permission Picker and choose which HQ permissions this group gets.
  6. Click "Create".

Bundle behavior at login

  • User logs in via Microsoft → HQ receives their Entra group IDs in the SAML assertion.
  • HQ compares the group IDs to all configured bundles.
  • Permissions from ALL matching bundles are granted (union).
  • Permissions from previously-granted bundles that no longer match are revoked.
  • If the user belongs to NO configured group → login is rejected with a permission error.

ℹ️ Group-based permissions are re-evaluated on every SSO login. If you remove a user from an Entra group, they lose the corresponding HQ permissions on their next login.

11. Step 9 — Create Breaking Glass Users

Breaking Glass users are local accounts that can log in with a password even when SSO is enabled. They are the emergency fallback if Microsoft Entra becomes unavailable or is misconfigured.

🚫 You MUST create at least one Breaking Glass user BEFORE enabling SSO. Without it, a misconfigured Entra setup will lock every admin out of the organization with no way to recover without contacting Xelon support.

Default permissions granted to Breaking Glass users

  • allow_manage_microsoft_authentication
  • allow_manage_organization_security
  • allow_view_organizations
  • allow_manage_users

These permissions allow the account to repair the SSO configuration, disable SSO if needed, and manage organization security settings.

Creating a Breaking Glass user

  1. Go to "Password Login Exceptions (Breaking glass users)" inside the Status section.
  2. Fill in First name, Surname, and Email. Default values "Breaking glass" / "user" are pre-filled — change them to something meaningful.
  3. Use "Generate password" for a strong random password (10+ chars, numbers, symbols).
  4. IMMEDIATELY record the email and password in your organization's password manager or secure vault.
  5. Click "Create user".

⚠️ Recommended: create TWO Breaking Glass users — store one credential with the IT team and one with a trusted executive. This prevents a single point of failure.

ℹ️ You cannot remove the last Breaking Glass user while SSO is enabled. To remove all, disable SSO first.

12. Step 10 — Enable SSO

Once all previous steps are complete and verified, you can enable SSO.

Pre-enable checklist

  • ☐ IdP URLs (Login, Identifier, Logout) are saved.
  • ☐ At least one Active X.509 certificate is uploaded.
  • ☐ At least one SSO domain is Verified.
  • ☐ At least one Permission Bundle is configured with a valid Entra Group Object ID.
  • ☐ Attribute Claims are correct (especially group claim).
  • ☐ At least one Breaking Glass user is created and credentials stored securely.
  • ☐ Test SSO login in Entra by clicking "Test" on the Single sign-on page.

⚠️ HQ shows a banner "SSO is enabled but not ready" if required fields are still missing. Do not enable SSO until this banner is gone.

Enabling SSO

  1. Toggle the "Enable SSO" switch to ON.
  2. A confirmation dialog appears explaining the impact. Read it carefully.
  3. Click "Enable SSO" in the dialog to confirm.

🚫 Effect of enabling SSO: All users whose email belongs to a verified SSO domain are immediately switched to Microsoft-only login. Password login stops working for them. Breaking Glass users are the only exception.

⚠️ If 2FA is not configured for the organization, HQ will show a security warning. It is strongly recommended to enable organization-level 2FA before activating SSO, so that Breaking Glass emergency logins are also protected.

Post-enable verification

  1. Open a private / incognito browser window.
  2. Navigate to the HQ login page and enter an email from a verified SSO domain.
  3. You should see the "Sign in with Microsoft" button. Click it and complete Entra login.
  4. Verify that the user is logged in and has the expected permissions.

13. Step 11 — (Optional) Microsoft Graph Lifecycle Sync

Lifecycle Sync is an optional background feature. When enabled, HQ periodically checks every active SSO user against Microsoft Graph API. If a user was disabled or removed in Entra, HQ deactivates them and signs them out. If group membership changes, permissions are re-synced.

⚠️ This feature requires a SEPARATE App Registration (not the Enterprise Application used for SAML). It uses Application-level permissions (not delegated) and requires admin consent.

Create a separate App Registration for Graph

  1. Go to Microsoft Entra admin center → App registrations → + New registration.
  2. Name: e.g. "Xelon HQ Graph Sync". Account types: "Accounts in this organizational directory only".
  3. No Redirect URI needed. Click Register.
  4. Note down: Overview → Application (client) ID and Directory (tenant) ID.

Configure API Permissions

  1. Go to API permissions → + Add a permission → Microsoft Graph → Application permissions.
  2. Add the following permissions:
    • GroupMember.Read.All — to read group membership
    • User.Read.All — to check if users are still active/enabled
  3. Click "Grant admin consent for [your tenant]" and confirm.

🚫 Admin consent is REQUIRED for Application-level permissions. Only a Global Administrator can grant it. Without admin consent, the Graph sync will fail with an "insufficient permissions" error.

Create a Client Secret

  1. Go to Certificates & secrets → Client secrets → + New client secret.
  2. Set a description and expiry (up to 24 months). Click Add.
  3. IMMEDIATELY copy the "Value" column (NOT the "Secret ID"). The value is only shown once.

🚫 Important: copy the "Value" field immediately. After you navigate away from this page, Azure will only show you the "Secret ID" (a different UUID), not the actual secret value. If you lose the value, you must create a new secret.

Configure Graph sync in HQ

  1. In the Microsoft Authentication modal, scroll to "Lifecycle Sync (Microsoft Graph)".
  2. Toggle "Enable Microsoft Graph lifecycle sync" to ON.
  3. Fill in:
    Directory (Tenant) ID From App registration → Overview → Directory (tenant) ID
    Application (Client) ID From App registration → Overview → Application (client) ID
    Client Secret (Value) The secret Value you copied (NOT the Secret ID)
  4. Click "Test connection" to validate credentials before saving.
  5. Click "Save".

Sync behavior

  • Automatic sync runs every 5 minutes for every organization that has SSO enabled and Microsoft Graph lifecycle sync configured.
  • "Sync now" button triggers an immediate sync without waiting for the scheduled tick.
  • Sync results are shown in the Microsoft Authentication card: "Last Microsoft Graph sync" timestamp and status.
  • Status "failed" — check Graph credentials and admin consent.
  • Status "re-syncing" — delta token expired, a full re-sync is in progress (normal after long idle).

⚠️ Client secrets expire after up to 24 months. If Graph sync stops working unexpectedly, the secret has likely expired. Generate a new secret in Entra and paste it into HQ.

14. Certificate Rotation (Zero-Downtime)

Entra certificates expire. Rotation must be done carefully to avoid even a brief SSO outage.

✅ HQ accepts multiple certificates simultaneously. ALWAYS add the new certificate first, BEFORE switching Entra to use it. This ensures old assertions remain valid during the transition.

Rotation procedure

  1. [In Entra] Go to Single sign-on → SAML Certificates → + New certificate. Set the expiry and click Save (but do NOT make it "Active" yet).
  2. [In Entra] Download the new certificate (Base64).
  3. [In HQ] Upload the NEW certificate in the "X.509 Certificate" section. Click "Add certificate". Both old and new are now active in HQ.
  4. [In Entra] Make the new certificate Active (click the "..." → "Make certificate active"). Entra now signs assertions with the new key.
  5. [Test] Perform an SSO login to confirm the new certificate works.
  6. [In HQ] Remove the old (expired/inactive) certificate by clicking the trash icon.

🚫 Step 3 is critical: HQ must have the new certificate BEFORE Entra starts using it. If you reverse the order (activate in Entra first, then upload to HQ), all SSO logins will fail with a signature validation error during the gap.

15. Troubleshooting

"Sign in with Microsoft" button does not appear

  • The user's email domain is not in the SSO domains list, or the domain is not yet verified.
  • Solution: Add and verify the domain in HQ → Microsoft Authentication → SSO Domains.

Login fails with "Invalid signature"

  • The certificate in HQ does not match the one Entra is currently using to sign assertions.
  • Solution: Download the active certificate from Entra → SAML Certificates and re-upload to HQ.
  • Also check: SHA-1 signatures are rejected. Ensure Entra uses SHA-256.

Login fails with "Issuer mismatch"

  • The Microsoft Entra Identifier in HQ does not match what Entra actually sends.
  • Solution: Copy the exact value from Entra → Section 4 → Microsoft Entra Identifier and paste into HQ.

Login fails with "User not authorized" or "No matching group"

  • The user is not a member of any Entra group that is configured as a Permission Bundle in HQ.
  • Solution: Add the user to the appropriate Entra group, or create a Bundle for their group.
  • Also check: Group claim is added in Entra → Attributes & Claims → Group claim → Security groups → Group ID.

Login fails with "Replay attack detected"

  • The same SAML assertion was used twice (e.g., the user reloaded the ACS URL). This is a security guard.
  • Solution: The user should start the login flow fresh from the HQ login page.

Login fails with "Timestamp outside valid range"

  • The server clock is out of sync. HQ allows a configurable clock_skew, but large differences are rejected.
  • Solution: Ensure the HQ server clock is synchronized via NTP.

Graph sync shows "failed"

  • Graph credentials are wrong, or admin consent was not granted.
  • Solution: Use "Test connection" in HQ to get a specific error. Common causes:
  • Secret expired — generate a new one in Entra.
  • Admin consent not granted — go to API permissions → Grant admin consent.
  • Wrong App registration — confirm Tenant ID and Client ID are from the GRAPH app (not the SAML app).

Breaking Glass user cannot log in

  • Ensure the user's email is exactly as registered (case-sensitive match).
  • Ensure SSO is enabled — Breaking Glass bypass only works when SSO is active.
  • If the password was forgotten, it must be reset by another admin with allow_manage_users permission.

16. Security Checklist

Review these security points after every SSO configuration change:

  • ☐ SHA-256 certificate algorithm: Ensure Entra is configured to sign with SHA-256. HQ rejects SHA-1 and weaker algorithms.
  • ☐ Certificate expiry monitoring: Add a calendar reminder 30 days before certificate expiry. Expired certs cause immediate SSO outage.
  • ☐ Breaking Glass credentials secured: Store Breaking Glass email/password in a secure vault. Test login quarterly.
  • ☐ Minimum two Breaking Glass users: One Breaking Glass account is a single point of failure. Maintain at least two from different people.
  • ☐ 2FA for the organization: Enable organization-level 2FA. Without it, Breaking Glass accounts are protected by password only.
  • ☐ Graph secret rotation: Graph client secrets expire. Track expiry dates and rotate before they expire.
  • ☐ Admin consent scope: Graph app only needs GroupMember.Read.All and User.Read.All. Do not grant broader permissions.
  • ☐ Test SSO after any Entra change: Any change to the Entra app (new cert, claim change) should be tested in a private browser window.
  • ☐ SSO domain verification: Only verified domains trigger SSO. Unverified domains are harmless but do not grant SSO access.

✅ This document covers the complete SSO setup as implemented in Xelon HQ. If you encounter issues not listed in the troubleshooting section, contact Xelon support with the error message visible in the HQ login redirect URL.