Single sign-on with Microsoft Entra ID

Single sign-on lets your staff sign in to FSM Navigator with their Microsoft work account, so there is one password to manage and one place to remove access when someone leaves. FSM Navigator connects to Microsoft Entra ID (formerly Azure Active Directory) using SAML for sign-in and SCIM to create, update and deactivate accounts from your Entra groups.

Before you start

You need:

• an FSM Navigator Enterprise account, signed in as an Owner or Administrator;
• a Microsoft Entra ID tenant in the commercial Microsoft cloud, and permission to create an enterprise application in it;
• access to your domain's DNS, to add one TXT record per domain;
• a distribution list or shared mailbox on your company's domain for the emergency administrator (step 2).

What is not supported

• Guest (external B2B) accounts. We don't support external B2B accounts through single sign-on. Guest accounts sign in with an onmicrosoft.com address, and onmicrosoft.com addresses aren't allowed for sign-in. Don't assign guest users to the FSM Navigator enterprise app. If a guest is assigned anyway, provisioning refuses that person and the reason shows in the Entra provisioning logs.
• Microsoft Entra US Government and Microsoft Entra China (21Vianet) clouds. Only the commercial cloud is accepted; metadata from other clouds is refused when you upload it.
• Identity providers other than Microsoft Entra ID.
• Sign-in names that end in onmicrosoft.com. Give everyone who uses FSM Navigator a sign-in name on one of your own domains.

Step 1: Verify your domains

Start here. People whose email is on a verified domain are sent to Microsoft when they sign in, and Validate SSO (step 5) only works when the domain of your Microsoft sign-in name is verified. You can add and verify domains before the emergency administrator exists.

1. Under 1. Your domains, enter your domain (for example yourcompany.com) and select Add domain.
2. Add the TXT record shown to your DNS: a record named _fsm-sso.yourcompany.com with the value FSM Navigator gives you.
3. Select Verify. DNS changes can take up to an hour to appear.

A domain you already verified for email sending is added and verified automatically. Verifying yourcompany.com also covers its subdomains, such as eu.yourcompany.com.

Step 2: Add the emergency administrator

Setup starts with an emergency administrator account. It signs in with a passkey, or with a password and an authenticator app, never through Microsoft and never with an emailed code, so you can always get back in if Microsoft sign-in stops working: for example, after a signing certificate expires or someone changes the Entra app by mistake.

1. Go to Settings → Single sign-on.
2. Under 2. Emergency administrator, enter an address on your company's domain and a strong password.
3. Scan the QR code with an authenticator app, and keep the recovery codes with your emergency instructions.
4. Enter the code we emailed to that address and a code from the authenticator app, then select Verify.

Once it is verified, sign in as the emergency administrator and add a passkey under Profile > Passkeys, for example on a security key kept with your emergency instructions. A passkey is the quickest way back in; the password with the authenticator code, and the recovery codes, keep working as the fallback. The set-up code email sent to the emergency administrator's address says the same.

To sign in with it later, select Sign in with a passkey, or enter the emergency administrator's email address on the normal sign-in page. Even when your company requires Microsoft sign-in, that address shows the usual password field, and you then enter the password and the authenticator code.

The emergency administrator can reset its password from Forgot password once it is verified; every reset is emailed to all Owners and Administrators, and signing in afterwards still needs the authenticator code, a recovery code or a passkey. Before it is verified, a reset request sends nothing.

Replacing the emergency administrator

To move the emergency administrator to a different mailbox, or after its authenticator app and recovery codes are lost, select Replace emergency administrator in the same section. Enter the new address and a password, scan the new QR code, then enter the emailed code and an authenticator code and select Verify. The current account keeps working until the new one is verified; then it is turned off and signed out. A replacement that is not verified within a day is cancelled, and you can also cancel it yourself. Every step is emailed to all Owners and Administrators.

Step 3: Create the Entra enterprise app

1. In Settings → Single sign-on, under 3. FSM Navigator details for Microsoft Entra, select Download metadata file.
2. In the Microsoft Entra portal, go to Enterprise applications → New application → Create your own application, name it "FSM Navigator" and choose Integrate any other application you don't find in the gallery (Non-gallery).
3. Open Single sign-on → SAML and select Upload metadata file. Choose the file you downloaded and save.
4. Leave Sign on URL blank, so the tile in My Apps keeps working.
5. Make sure everyone who will sign in has First name and Last name filled in on their Entra user (Users → the person → Properties). The default claims send these as the given name and surname. Microsoft leaves a claim out when the field is empty, and FSM Navigator refuses a sign-in without a first and last name.

Recommended claim and certificate settings

• Add the amr optional claim (authentication methods) under Attributes & Claims, so each sign-in carries how Microsoft verified the person.
• Set the SAML signing certificate's Notification Email to a distribution list or the emergency administrator mailbox, not to one person. Microsoft sends certificate renewal reminders to that address.

Step 4: Upload your federation metadata

1. In the Entra app's SAML Certificates card, download Federation Metadata XML.
2. In FSM Navigator, under 4. Microsoft Entra federation metadata, choose that file and select Upload metadata.

FSM Navigator shows your Entra tenant ID and the date the signing certificate expires.

Step 5: Validate

Under 5. Validate SSO, select Validate SSO and sign in with your own Microsoft account. This proves the connection works and links your FSM Navigator account to that Microsoft account, so you can sign in with Microsoft from then on. It does not sign you in or change anyone else's access.

The domain of your Microsoft sign-in name must be verified first (step 1). After validation, your FSM Navigator sign-in email becomes your Microsoft sign-in name. If another FSM Navigator account already uses that address, validation stops and nothing changes. When the address changes, FSM Navigator emails the user at both the old and the new address to say their sign-in email changed because of single sign-on. A Microsoft account that is already linked to someone else, or a second Microsoft account for you, is refused. The emergency administrator can't be linked.

When you return to FSM Navigator, a message under step 5 tells you whether validation worked. If it did not, the message says what to check, and you can select Validate SSO again.

Step 6: Turn on single sign-on

Under 6. Turn on, choose who asks for multi-factor authentication after a Microsoft sign-in:

• FSM Navigator asks for its own second factor or passkey. People confirm their sign-in with FSM Navigator after Microsoft.
• Microsoft Entra Conditional Access controls it. FSM Navigator trusts Microsoft and does not ask again. Choose this only if you have a Conditional Access policy for this app that requires multi-factor authentication or passkeys and sets the sign-in frequency; you are asked to confirm that.

Select Turn on single sign-on. While sign-in is Optional, people on your verified domains are offered "Sign in with your company's Microsoft account" and can still use their password. Use this to roll out gradually.

Step 7: Set your sign-in policy

These controls are under 7. Sign-in policy.

Require Microsoft sign-in

Choose Required and select Save sign-in requirement. You are asked to confirm, because:

• everyone on your verified domains must sign in with Microsoft;
• their current password sessions end right away, including yours if you signed in with a password;
• the emergency administrator is not affected.

You can only switch to Required after your own account is linked to Microsoft, so you can't lock yourself out. If it isn't linked yet, select Validate SSO (step 5) and sign in with your own Microsoft account once, then save Required again. The same applies when you turn single sign-on back on while Required is saved.

Re-check intervals

FSM Navigator sends people back to Microsoft to confirm their sign-in after a set time. If their Microsoft session is still valid, this is quick and usually needs no password. A change applies right away, counted from each person's last Microsoft sign-in.

If you use Conditional Access sign-in frequency for this app, set the web interval to the same value so people are asked once rather than twice. Don't set the sign-in frequency to "Every time" for FSM Navigator: each re-check then becomes a full sign-in. The mobile app can't go below 8 hours, so technicians aren't interrupted on site.

Sign-in from My Apps

Allow sign-in from Microsoft My Apps is on by default, so people can open FSM Navigator from its tile at myapps.microsoft.com. Turn it off if you want everyone to start from the FSM Navigator sign-in page; they are still sent to Microsoft from there. The mobile app always starts from its own sign-in screen.

Step 8: Set up user provisioning (SCIM)

Provisioning lets Entra create, update and deactivate FSM Navigator accounts. Accounts are only created by provisioning: someone who signs in with Microsoft before they are provisioned is refused.

People who already have an FSM Navigator account are linked, not duplicated. When Entra provisions a user whose sign-in name, or work email, is the email of an active or inactive account in your company, that account is linked to the Entra user and keeps its roles. An inactive account becomes active only under the usual group and seat rules. Its sign-in email becomes the Entra sign-in name, and FSM Navigator emails the user at the old and the new address to say so. Both addresses must be on your verified domains (step 1); otherwise provisioning refuses the user and the reason shows in the Entra provisioning logs. The emergency administrator is never linked.

1. In FSM Navigator, under 8. User provisioning (SCIM), select Create token. Copy the token right away; it is shown only once and lasts one year. Creating a new token stops the old one.
2. In the Entra app, open Provisioning, set Provisioning Mode to Automatic, and paste the Tenant URL and Secret token from FSM Navigator. If Entra asks for an authentication method, choose Bearer authentication; OAuth is not used. Select Test Connection.
3. Under Mappings → Provision Microsoft Entra ID Users, select the externalId row and change its source attribute to objectId. Entra maps mailNickname to externalId by default, and FSM Navigator refuses those users with "externalId must be the Entra object ID (a GUID)". Leave userName mapped to userPrincipalName: that is how existing accounts are matched.
4. Under Users and groups, assign groups to the app, such as "FSM Navigator - Owners", "FSM Navigator - Technicians" and "FSM Navigator - Office staff". Assign groups rather than individual people: roles come from groups.
5. Turn provisioning on and wait for the first cycle, or use Provision on demand to provision one person straight away.

Check who Entra can match

Before you turn provisioning on, look at People Microsoft Entra cannot match at the top of the section. It lists active people whose sign-in email is not on a verified domain from step 1. Entra cannot match them to their existing account, so provisioning would create a second account for each. Select Change sign-in email next to a person to open the same dialog as on the Users page, and change their sign-in email to their Microsoft work address. The emergency administrator, accounts that are already linked and platform staff are not listed. The list is empty until you verify a domain.

Give each group its roles

After the first cycle, your groups appear in FSM Navigator under Groups and roles. Tick the roles for each group and select Save roles.

• A group can carry several roles, and a person in several groups gets every role from all of them.
• A person in no mapped group is created Inactive, uses no seat, and is listed for you to review.
• When someone is removed from all their groups in Entra, they are deactivated and their seat is freed. Their work history stays.
• If your seats are full, up to 10 extra people wait as Inactive and are activated, oldest first, as seats free up.
• Roles from a group show on the Users page as From Entra group and can only be changed in Entra. Roles you give a person on the Users page are kept when groups change.

If Entra suddenly creates an unusual number of accounts, new accounts are paused and Owners and Administrators are alerted. Check the app assignment in Entra, then select Resume provisioning.

When a user's email changes in Entra

If you change a user's sign-in name in Entra and the user has a mailbox, their FSM Navigator sign-in email changes to match. No confirmation code is sent, but FSM Navigator emails the user at the old and the new address to say it changed. The new address must be on one of your verified domains (step 1) and must not already be used by another account. Otherwise the user keeps their old email, and a clash shows in the Entra provisioning logs. Users without a mailbox don't have an FSM Navigator email, so they get no emails.

Moving to a new Microsoft tenant

If your company moves to a different Microsoft Entra tenant (for example after a merger or a tenant consolidation), every person gets a new Microsoft identity, so their existing links to FSM Navigator no longer match. FSM Navigator treats this as a move, and only an Owner can confirm it.

1. Create the FSM Navigator app in the new tenant (step 3) and upload its Federation Metadata XML in step 4. Step 5 then says the metadata is from a different Microsoft Entra tenant.
2. An Owner selects Validate SSO and confirms Move and validate, then signs in with their Microsoft account in the new tenant. Administrators see the warning but cannot confirm the move.
3. When validation succeeds:
   • every existing Microsoft link is removed. People keep their FSM Navigator accounts, roles and history;
   • the Owner who validated is linked to the new tenant;
   • the sign-in policy is set to Optional, so nobody is locked out while people are matched again;
   • the user provisioning token stops working, so the old tenant can no longer provision people;
   • all Owners and Administrators are emailed.
4. In step 8, create a new token and paste it, with the Tenant URL, into the new tenant's app. When provisioning runs, people are matched to their existing accounts by sign-in name or work email, on your verified domains.
5. Check the list in step 8 for anyone who could not be matched, then set the sign-in policy back to Required if you use it.

Group-to-role mappings belong to the old tenant's groups. Map the new tenant's groups in step 8 once they appear.

Troubleshooting

Certificate renewal

To renew: create a new certificate in the Entra app, make it active, download the new Federation Metadata XML, upload it in step 4, and run Validate SSO. Sign-in keeps using the current metadata until the new one is validated.

Related pages

• Multi-Factor Authentication
• Passkeys
• Roles & Access Control
• Enterprise Plan Guide