Introduction
The Okta integration for ZenQMS provides automated, one-way user provisioning and lifecycle management from Okta to ZenQMS. By connecting your Okta organization to ZenQMS, user accounts are automatically created, updated, and deactivated in ZenQMS as changes occur in Okta. This eliminates the need for manual user administration in ZenQMS and ensures your quality management system always reflects your current workforce.
When the integration is first deployed, it performs an initial synchronization of all users from Okta into ZenQMS. After that, the integration listens for real-time events from Okta via webhooks, so any user lifecycle change (new hire, profile update, suspension, or offboarding) is reflected in ZenQMS within seconds. Optionally, you can configure group-to-role mapping so that Okta group memberships automatically drive ZenQMS role assignments.
This integration is designed for organizations that use Okta as their authoritative identity provider and want to keep ZenQMS user records in sync without manual intervention. Okta remains the single source of truth for all user data.
What It Does
This is a one-way sync: data flows from Okta to ZenQMS only. Changes made directly in ZenQMS are not sent back to Okta.
Data in Scope
The following user profile fields are mapped from Okta to ZenQMS
Okta Field | ZenQMS Field | Notes |
|---|---|---|
User ID | external_id | Used to link the Okta user to the ZenQMS user |
profile.email | Required. Used for matching if external_id is not yet set | |
profile.firstName | first_name | Required |
profile.lastName | last_name | Required |
profile.title | title | Required |
status | is_active | See status mapping below |
Okta Status to ZenQMS Active/Inactive Mapping
Okta Status | ZenQMS is_active | Reasoning |
|---|---|---|
ACTIVE | Active | Fully active user |
PROVISIONED | Active | Provisioned but not yet activated |
STAGED | Active | Created but pending activation |
RECOVERY | Active | In password recovery |
PASSWORD_EXPIRED | Active | Needs password change but still valid |
LOCKED_OUT | Active | Temporarily locked, can be unlocked |
SUSPENDED | Inactive | Administratively suspended |
DEPROVISIONED | Inactive | Offboarded / deprovisioned |
Group-to-Role Mapping (Optional)
When configured, Okta group memberships are mapped to ZenQMS roles:
One Okta group can map to one or more ZenQMS roles
Roles are automatically added when a user joins a mapped Okta group
Roles are automatically removed when a user leaves a mapped Okta group
Roles marked as "default" in ZenQMS are never removed by the integration
Roles that are not part of any mapping are never touched by the integration
User Matching Logic
When syncing a user, the integration determines whether to create or update a ZenQMS user using this priority:
Match by external_id (Okta User ID) — if the user has been previously linked
Match by email — if the user exists in ZenQMS but has not yet been linked to Okta
No match found — a new user is created in ZenQMS (in applicable sync modes)
How Data Flows Between Systems
Two initial sync modes are available:
Enable Initial Sync = OFF: Only links existing ZenQMS users to their Okta accounts by setting the external_id. Does not create new users or update profile data.
Enable Initial Sync = ON: Creates new users in ZenQMS for any Okta user without a match, updates profile data for existing users, and syncs roles if group-to-role mapping is configured.
Real-Time Webhook Sync (ongoing after deployment):
The following Okta events trigger a real-time sync.
Okta Event | What Happens in ZenQMS |
|---|---|
user.lifecycle.create | New user account created |
user.lifecycle.activate | User account activated |
user.lifecycle.deactivate | User account deactivated |
user.lifecycle.reactivate | User account reactivated |
user.lifecycle.suspend | User account deactivated |
user.lifecycle.unsuspend | User account reactivated |
user.account.update_profile | User profile fields updated |
group.user_membership.add | Roles added (if group mapping configured) |
group.user_membership.remove | Roles removed (if group mapping configured) |
Cleanup (runs when integration is removed):
When the integration instance is deleted, all external_id values that were set by the integration are cleared from ZenQMS user records. This unlinks the Okta users from ZenQMS so the integration can be cleanly re-deployed in the future if needed.
Limitations
One-way sync only. Changes made to user profiles directly in ZenQMS will not sync back to Okta. If the same user is later updated in Okta, the Okta data will overwrite the ZenQMS changes for mapped fields.
Initial sync syncs all users. The initial sync retrieves users in all Okta, regardless of type, status. This could result in users that are not ZenQMS users being synced.
No password sync. Passwords are not synced. Users authenticate through Okta (SSO) or through ZenQMS's own authentication, depending on your setup.
Required fields. Users in Okta must have an email, first name, and last name to be synced. Users missing any of these fields will be skipped.
No custom field sync. Only the fields listed in the data mapping table above are synced. Custom Okta profile attributes are not supported.
Users are not sent invitations. You would still need to manually invite users to ZenQMS.