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 Okta and ZenQMS.
Okta OAuth 2.0 Connection
You will need to create an OIDC Web Application in your Okta Admin Console before configuring this section.
Steps to prepare in Okta:
Log into the Okta Admin Console (e.g., https://your-domain.okta.com/admin)
Navigate to Applications → Applications → Create App Integration
Select OIDC - OpenID Connect as the sign-in method
Select Web Application as the application type and click Next
Configure the application:
App integration name: Enter a descriptive name (e.g., "ZenQMS Integration")
Grant type: Ensure Authorization Code and Refresh Token are selected
Sign-in redirect URIs: Add the OAuth callback URL provided during setup
Click Save
Navigate to the Okta API Scopes tab and grant the following scopes:
okta.users.read - Required for reading user profiles
okta.eventHooks.manage - Required for webhook management
okta.groups.read - Required for group-to-role mapping
Copy the Client ID and Client Secret from the General tab
What you will enter in the configuration wizard:
Okta Domain URL: Your Okta organization URL (e.g., your-domain.okta.com)
Client ID: From the application you created above
Client Secret: From the application 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: OFF
When OFF (Standard Mode): The initial sync will only link existing ZenQMS users to their Okta accounts by matching on email and setting the external_id. No new users are created and no profile data is updated.
When ON (Full Sync Mode): The initial sync will create new users in ZenQMS for any unmatched Okta users, update profile data for all matched users, and sync roles if group-to-role mapping is configured.
Choose Full Sync Mode if this is a fresh setup and you want all Okta users provisioned into ZenQMS. Choose Standard 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 Okta groups to ZenQMS roles. When configured:
Users added to a mapped Okta group will automatically receive the corresponding ZenQMS role(s)
Users removed from a mapped Okta group will have the corresponding ZenQMS role(s) removed
One Okta group can be mapped to multiple ZenQMS roles
The configuration wizard will display a form showing your available Okta 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 Okta. If you delete a role in ZenQMS that is mapped, you must update or remove the mapping configuration for that role.