How To Configure
The integration configuration wizard has two pages. You will complete each page in order during setup.
Page 1: Connections
This page collects the credentials needed to connect to both Microsoft Entra ID and ZenQMS.
Microsoft Entra ID OAuth 2.0 Connection
You will need to create an App Registration in your Microsoft Entra Admin Center before configuring this section.
Steps to prepare in Microsoft Entra:
Log into the Microsoft Entra Admin Center or Microsoft Azure Portal
Navigate to App Registrations → New registration
Configure the application settings:
Name: Enter a descriptive name (e.g., "ZenQMS Integration")
Supported account types: Select Accounts in this organizational directory only
Redirect URI: Select Web platform and enter the OAuth callback URL provided during setup
Click Register to complete the app creation
Navigate to Certificates & secrets → New client secret
Create a new client secret and copy/save the Value immediately (it will not be shown again)
Navigate to the Overview section and copy the Application (client) ID
Navigate to API Permissions → Add a permission → Microsoft Graph
Select Application permissions and grant the following:
Group.Read.All— Required for group synchronizationGroupMember.Read.All— Required for group membershipUser.Read.All— Required for user synchronization
Click Grant admin consent to approve the permissions for your organization
What you will enter in the configuration wizard:
Authorize URL: Replace the
{tenant}placeholder with your Microsoft Entra tenant IDToken URL: Replace the
{tenant}placeholder with your Microsoft Entra tenant IDClient ID: The Application (client) ID from the app registration
Client Secret: The client secret value you created above
You will then be prompted to authorize the connection via OAuth
ZenQMS API Connection
Log in to your ZenQMS environment
Navigate to Settings → API Settings
Generate a new API token (we recommend creating a dedicated token for this integration)
Ensure the proper token access is granted and the token is activated
Copy the API key
What you will enter in the configuration wizard:
API Key: The token you generated above
Base URL: Your ZenQMS environment URL
Page 2: Sync Settings
This page controls how the integration behaves during the initial sync and whether role mapping is enabled.
Enable Initial Sync
Default: ON
When ON (Full Sync Mode): The initial sync will create new users in ZenQMS for any unmatched Entra ID users, update profile data for all matched users, and sync roles if group-to-role mapping is configured.
When OFF (Link-Only Mode): The initial sync will only link existing ZenQMS users to their Entra ID accounts by matching on email and setting the external_id. No new users are created and no profile data is updated.
Choose Full Sync Mode if this is a fresh setup and you want all Entra ID users provisioned into ZenQMS. Choose Link-Only Mode if your ZenQMS users already exist and you just want to establish the link between systems.
Role Sync (Group-to-Role Mapping)
This optional configuration lets you map Entra ID groups to ZenQMS roles. When configured:
Users who are members of a mapped Entra ID group will automatically receive the corresponding ZenQMS role(s)
Users removed from a mapped Entra ID group will have the corresponding ZenQMS role(s) removed
One Entra ID group can be mapped to multiple ZenQMS roles
One ZenQMS role can be mapped to multiple Entra ID groups (the role is only removed when the user is not in any of the mapped groups)
The configuration wizard will display a form showing your available Entra ID groups and ZenQMS roles for you to create the mappings.
Important: When group-to-role mapping is enabled, any manual role assignment changes made in ZenQMS for mapped roles may be overwritten by the integration. To avoid unexpected changes, manage group membership in Microsoft Entra ID. If you delete a role in ZenQMS that is mapped, you must update or remove the mapping configuration for that role.