Summary
Planhat’s SCIM integration with Okta automates user provisioning, deprovisioning, and Role management, ensuring access stays accurate and secure without manual updates
Admins can manage access by assigning Users or groups to the Planhat app in Okta, with R
oles automatically mapped and synced between systems
Once configured, Okta handles ongoing User and group synchronization automatically through the SCIM 2.0 standard
Who is this article for?
For Planhat administrators responsible for managing User Provisioning and Roles access through Okta
Series
This article is part of a series on SCIM:
How to set up the SCIM integration in Okta ⬅️ You are here
📌 Important to note
This is part 2 of setting up the SCIM integration. Once the setup in Planhat is done, continue with these steps for setup in Okta
SCIM-supported features
How provisioning works between Okta and Planhat
User provisioning between Okta and Planhat works in two main ways:
By assigning a User directly to the Planhat app, in this case, the user will be provisioned into Planhat and assigned the Default Role configured in your Planhat setup
By assigning a Group to the Planhat app, in this case, the User’s Role in Planhat will be determined by the mapped Group(s) they belong to
If a User is removed from a Group in Okta, Planhat automatically adjusts their access as follows:
If the User no longer belongs to any mapped Group, they will be deactivated in Planhat
If the User still belongs to other mapped Groups, they will retain the Roles associated with those remaining Groups
If a User is assigned directly (not through a Group), they will receive the Default Role defined in the Planhat SCIM configuration
Syncing data from Planhat to your Okta
Provisioning also supports communication in the opposite direction - importing Users from Planhat into Okta. This is allowing Okta admins to view and manage Users that exist in Planhat within the Okta interface.
Push Groups and mappings
For Group management, Okta supports Push Groups, which let you synchronize Group memberships between Okta and Planhat.
You can either:
Map a Group in Planhat and map it to a corresponding Group in Okta (recommended), or
Push a Group from Okta into Planhat and then define its Role Mapping in the Planhat SCIM configuration
Once linked, Okta will maintain Group memberships automatically, ensuring that User Roles in Planhat stay in sync with the Groups they belong to in Okta.
Supported SCIM attributes
Planhat supports the following SCIM attributes for synchronization with Okta:
userName, emails, externalId, name.givenName, name.familyName, displayName, and active.
📌 Important to note
The emails attribute is read-only in Planhat. Since the userName field uses the User’s email address as its value, Planhat returns that same email address automatically in response to SCIM requests.
How to set it up
In Okta, go to Applications → Browse App Catalog
Find and select Planhat
Go to Provisioning → Integration and check Enable API integration
Go back to Planhat → Global Tool Settings → User Provisioning → Generate a new Bearer Token in Planhat
In Okta, paste following URL to SCIM 2.0 Base URL
https://api.planhat.com/integrations/scim/v2Paste the newly generated Bearer Token to OAuth Bearer Token
Click "Test API Credentials" to make sure they work
Click the image to view it enlarged
8. In Okta, go to Push Groups and add desired groups to sync
9. Go to Assignments and assign the Planhat app to the desired groups or Users
Once set up, User Provisioning and Role Management will happen automatically based on your Okta group assignments.
Essential considerations/troubleshooting
Default Role vs. Mapped Role
SCIM Group Mappings are evaluated first and should be considered the primary way to assign roles based on Okta group membership. The Default User Role is only applied in the following case:
The user was individually assigned to the Okta SCIM application (not via group assignment).
This means that users manually assigned to the SCIM app in Okta without group membership will receive the Default User Role. To ensure consistent provisioning behavior, Planhat enforces validation that prevents the Default User Role from being the same as any role used in Group Mappings.
User Type & SCIM Role Assignment (Important Limitation)
By default, all users provisioned via SCIM are now created as User Type = CORE, regardless of the role mapped through SCIM Group Assignments.
However, there is a significant limitation to be aware of:
If SCIM is enabled after some users were already created manually as VIEW users, these existing VIEW users cannot be assigned roles that require CORE user type even if the SCIM group mapping is valid. This results in a silent failure: the SCIM group-role mapping will match, but the role assignment will be ignored because the user type is incompatible. Troubleshooting Tip:
Check the User Type of any affected user in Planhat. If it's set to VIEW, and the SCIM role mapping requires CORE, you must manually upgrade the user type to CORE in Planhat before SCIM can assign the role.
Using “Push Now” in Okta
Okta is the authoritative source for role assignments when SCIM Group Mappings are enabled. Using the “Push Now” action in Okta performs a full overwrite of the group membership, making Okta the master for that group. This means that when a group is pushed, all existing members of the corresponding role in Planhat are first removed and then replaced with the users currently assigned to the group in Okta. As a result, users who were manually assigned to a role in Planhat but are not part of the Okta group will lose access. This behavior is expected and safe only when SCIM is the sole source of user and role management. If role assignments are partially managed outside Okta, using “Push Now” can result in unexpected role removals and access loss.
If you are having trouble setting up the integration, please don't hesitate to reach out to our Support team.