OpenFIT SAML Integration with Microsoft Entra ID

Created by Enda Madden, Modified on Wed, 17 Sep at 1:17 PM by Enda Madden

Introduction

This guide provides step-by-step instructions to configure SAML-based Single Sign-On (SSO) integration between Microsoft Entra ID (Azure AD) and OpenFIT. This setup ensures secure authentication and role-based access control for users accessing OpenFIT.

Prerequisites

Before you begin, ensure you have:

Access to Microsoft Entra ID (Azure AD) with sufficient permissions to create Enterprise Applications
OpenFIT Federation Metadata endpoints access
Understanding of OpenFIT roles information (provided in the application setup)

OpenFIT Federation Metadata Endpoints

Test Sandbox:

https://of-internal-ids.azurewebsites.net/FederationMetadata/2007-06/FederationMetaData.xml

Production:

https://ids.openfit.care/FederationMetadata/2007-06/FederationMetaData.xml

Step 1: Create the Enterprise Application in Entra ID

Login to the Azure portal
Navigate to Microsoft Entra ID > Manage > Enterprise Applications
Click 'New Application' > 'Browse Microsoft Entra Gallery'
Select 'Create your own application'
Enter the application name (e.g., OpenFIT)
Choose 'Integrate any other application you don't find in the gallery (Non-gallery)'
Click 'Create'

Step 2: Configure SAML-based Single Sign-On

Open the newly created Enterprise Application
Go to Manage > Single Sign-On
Select 'SAML' as the sign-on method
Fill in the following configuration details:

SAML Configuration Details

Field	Value	Required
Identifier (Entity ID)	`https://ids.openfit.care`	Yes
Reply URL (Assertion Consumer Service URL)	`https://ids.openfit.care/api/SAML/AssertionConsumerService`	Yes
Logout URL	`https://ids.openfit.care/api/SAML/LogoutConsumerService`	Optional
Sign-on URL	Optional	No
Relay State	Optional	No

Important: For testing environments, replace https://ids.openfit.care with https://of-internal-ids.azurewebsites.net in all URLs above.

Step 3: Configure Attributes & Claims

Ensure the following attributes and claims are configured correctly:

Required Claims Configuration

Claim Name	Source Attribute	Description
`givenname`	`user.givenname`	User's first name
`surname`	`user.surname`	User's last name
`emailaddress`	`user.mail`	User's email address
`name`	`user.userprincipalname`	Username in OpenFIT
`role`	`user.assignedroles`	OpenFIT role assignment
`Unique User Identifier`	`user.userprincipalname`	Unique identifier
`groups`	`user.groups`	User group memberships

Critical: Ensure the token injects the group (role) name and not the ID. This is a common mistake that will cause authentication failures.

Step 4: Upload and Manage SAML Certificates

In the SAML Certificates section, download the Federation Metadata XML
Provide the 'App Federation Metadata URL' to OpenFIT support for registering the application
Ensure the certificate is valid (renew before expiration to avoid outages)

Step 5: Configure App Roles in OpenFIT

Navigate to Microsoft Entra ID > Manage > App registrations > OpenFIT > Manage > App roles
Add the following roles as defined by OpenFIT:

Required OpenFIT Roles

Role Name	Description	Permissions Level
`OpenFitAdministrator`	Full system administrator	Highest
`OpenFitLocalAdmin`	Local administrator	High
`OpenFitClinicianSupervisor`	Clinical supervisor role	Medium
`OpenFitClinician`	Standard clinician access	Standard

Ensure that each role is assigned to the appropriate users or groups as required.

Step 6: Assign Users and Roles

Navigate to the Enterprise Application > Manage > Users and groups
Assign the users or groups to the appropriate roles
Validate that role assignments are correctly reflected in the SAML token

Step 7: Testing the Integration

Testing Checklist:

Use the 'Test' button in the SAML Single Sign-On configuration to validate the setup
Ensure that the login redirects to the OpenFIT sign-in page
Verify that user attributes and roles are passed correctly
Confirm that users can access OpenFIT with the assigned roles

Troubleshooting

Common Issues

Role Claims Not Working:

Verify App Roles are created in App registrations (not Enterprise Applications)
Check that users are assigned to roles in Enterprise Applications > Users and groups
Ensure the role claim is mapped to user.assignedroles

URL Mismatch Errors:

Verify the Reply URL includes /api/ in the path
Use test environment URLs for initial testing
Check Entity ID matches exactly

Certificate Issues:

Download and provide the correct Federation Metadata XML to OpenFIT support
Monitor certificate expiration dates
Test after certificate renewal

Next Steps

After completing this configuration:

Contact OpenFIT support with your Federation Metadata URL
Wait for OpenFIT to provision your organization
Conduct end-to-end testing with actual users
Plan for certificate renewal schedules
Document any organization-specific customizations

Need Help? If you encounter issues during configuration, contact OpenFIT support support@openfit.care with:

Your Federation Metadata XML file
Screenshots of your SAML configuration
Specific error messages
Details about which step is failing