Migrating Existing OpenFIT Accounts to Entra ID SSO

Created by Enda Madden, Modified on Fri, 19 Sep at 12:07 PM by Enda Madden

This guide addresses the specific challenges when migrating existing OpenFIT accounts to Microsoft Entra ID Single Sign-On (SSO). If you're setting up SSO for a new OpenFIT instance, refer to the standard SAML EntraID configuration guide instead.

When do you need this guide?

Your organization already has OpenFIT accounts created with email addresses as usernames
You're implementing Entra ID SSO for the first time
Your Entra ID UPNs don't match your existing OpenFIT email usernames

Understanding the Identity Mismatch Challenge

Most existing OpenFIT accounts use email addresses as usernames (e.g., john.smith@company.com). However, many organizations use numeric employee IDs or different formats for their Entra ID UPNs (e.g., 12345@company.com).

Example Identity Mismatch

User	Existing OpenFIT Username	Entra ID UPN	Status
Amy Kendall	`amy.kendallk@company.com`	`6566509@company.com`	❌ Mismatch
John Smith	`john.smith@company.com`	`john.smith@company.com`	✅ Match

Why OpenFIT Uses UPN as Primary Identifier

OpenFITs SAML configuration uses user.userprincipalname rather than user.mail for technical and security reasons:

UPN vs Email Comparison

Aspect	UPN (user.userprincipalname)	Email (user.mail)
Stability	Immutable - doesn't change	Changes with name changes, reorganizations
Uniqueness	Guaranteed unique across directory	Potential conflicts in complex orgs
Microsoft Guidance	Recommended for SAML NameID	Acceptable but less stable
Long-term Support	Reduces broken account links	May require re-linking after changes

Pre-Migration Assessment

Before implementing SSO, you need to identify which users have UPN/email mismatches:

Export your existing OpenFIT user list (contact support if needed)
Export your Entra ID user list with UPNs and email addresses
Compare the two lists to identify mismatches

Critical Check: If more than 10% of your users have UPN/email mismatches, consider the account mapping approach (Option 2) to maintain UPN best practices.

Migration Options

When you have UPN/email mismatches, you have two approaches:

Option 1: Modify SAML Claims Configuration

Process

In your Entra ID SAML configuration, change these claims:

Claim Name	Change From	Change To
`name`	`user.userprincipalname`	`user.mail`
`Unique User Identifier`	`user.userprincipalname`	`user.mail`

Pros

Quick implementation - no data migration required
Works immediately with existing usernames
No coordination with OpenFIT support needed

Cons

Uses email as identifier (less stable long-term)
May require account re-linking if email addresses change
Deviates from Microsoft's recommended identity practices

Option 2: Account Mapping and Conversion (Recommended)

Process

Create a mapping spreadsheet with existing usernames and their corresponding UPNs
Send the mapping to OpenFIT support@openfit.care
- Schedule a conversion window (typically during off-hours)
OpenFIT converts existing accounts to use UPN as username
- All user data, cases, and settings are preserved
New accounts use UPN format as username
- Users can immediately use SSO with their Entra ID credentials

Mapping Spreadsheet Format

Current OpenFIT Username	Entra ID UPN	User Full Name
`amy.kendrick@company.com`	`656809@company.com`	Amy Kendrick
`maree.reser@company.com`	`631012@company.com`	Maree Reser

Pros

Maintains UPN-based identity management best practices
Long-term stability and reduced support burden
Follows Microsoft's recommended approach
All user data and case history preserved

Cons

Requires coordination with OpenFIT support
Short-term disruption during account conversion

Troubleshooting Common Issues

Users Can't See Their Cases After SSO Login:

This indicates duplicate accounts were created for a user due to UPN/email mismatch
Contact OpenFIT support@openfit.care to confirm and to merge the duplicate accounts
Consider completing the full account mapping process to prevent future duplicates

Users Report "Can't Login" After Conversion:

Verify they're using the SSO link, not trying the old web login with email
If using web login, confirm they're using the UPN format username
Check that their Entra ID account is properly assigned to the OpenFIT enterprise application

Need Help Deciding? Contact OpenFIT support@openfit.care to discuss your specific situation. We can review your user data and recommend the best approach for your organization.