Configure SCIM 2.0 provisioning with Okta
The Contrast SCIM 2.0 API supports user and group provisioning from Okta. This topic covers connecting Okta to Contrast, configuring attribute mappings, and understanding current limitations.
This topic is for organization administrators configuring identity provisioning on a Contrast SaaS organization, on either the Classic or Northstar platform. It does not cover Microsoft Entra ID SCIM setup, which is documented in Configure SCIM 2.0 provisioning with Microsoft Entra ID or general SSO/SAML configuration.
Note
SCIM provisioning must be enabled for your organization before you begin. Contact your Contrast Customer Success representative or Support if you have not set this up yet.
Before you begin
SCIM provisioning is available for Contrast SaaS organizations only (Classic and Northstar platforms). It is not available for on-premises TeamServer deployments.
You need the organization administrator role in Contrast.
Your organization must have RBAC enforced. SCIM-provisioned users are created with an RBAC-controlled role, so organizations without RBAC enabled cannot provision users through SCIM.
Users created through SCIM don't receive an invitation email. They authenticate through the SSO connection configured with your identity provider, so make sure SSO is already set up before you provision users.
Supported operations
Resource | Supported operations |
|---|---|
Users | Create, search, get, update, deactivate, full replace |
Groups | Create, search, get, rename, add/remove members, full replace, delete |
Schema discovery | Read-only, used by Okta to validate the connection |
Register an OAuth2 client with an extended token lifetime
Register a client for your organization using the Contrast API. Include tokenTtlMinutes so the token you generate for Okta doesn't expire after the default 60 minutes.
A successful request returns 201 Created. tokenTtlMinutes accepts up to 388800 (9 months). If you omit it, tokens expire after 60 minutes, which is too short for Okta's static-token setup.
curl
--request POST \
--url https://<your-contrast-host>/api/v4/organizations/{organizationUuid}/oauth2/configuration \
--header 'Api-Key: <api_key>' \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data '{
"clientId": "my-scim-client",
"clientSecret": "mySecretValue123!",
"clientName": "Okta SCIM Provisioning",
"tokenTtlMinutes": 388800
}'A successful request returns 201 Created. tokenTtlMinutes accepts up to 388800 (9 months). If you omit it, tokens expire after 60 minutes, which is too short for Okta's static-token setup.
Note
You can register up to three OAuth2 clients per organization. Registering a fourth returns 409 Conflict. You will also get 409 Conflict if the clientId you chose is already registered, either to your organization or to another one. Choose a unique client ID and retry.
Generate an access token
curl --request POST \ --url https://<your-contrast-host>/scim/oauth2/token \ --header 'Authorization: Basic <base64(clientId:clientSecret)>' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data 'grant_type=client_credentials&scope=read write'
A successful request returns 200 OK with an access_token valid for the lifetime you set in the step above. Copy this token. You will paste it into Okta in Configure the API integration.
Add the SCIM app from the Okta catalog
In the Okta admin console, go to Applications > Applications.
Select Browse App Catalog.
Search for SCIM 2.0 Test App (OAuth Bearer Token).
Select Add Integration.
On General Settings, enter a name, such as Contrast Security SCIM Provisioning.
Select Next.
On Sign-On Options, select SWA (Secure Web Authentication).
Select Done.
Configure the API integration
In the app you created, go to the Provisioning tab.
Select Configure API Integration.
Check Enable API Integration.
Enter the following:
Table 2.Field
Value
SCIM connector base URL
https://<your-contrast-host>/scim/v2OAuth Bearer Token
The access token you generated in Generate an access token
Select Test API Credentials to verify connectivity. Okta sends a request to the Users endpoint to confirm the connection.
Select Save.
Enable provisioning features
On the Provisioning tab, select To App in the left sidebar, then Edit.
Enable the features you want:
Feature | What it does | Recommendation |
|---|---|---|
Create Users | Creates the user in Contrast when assigned in Okta. Skipped if the userName already exists. | Enable |
Update User Attributes | Syncs profile changes (name, email) from Okta to Contrast. | Enable |
Deactivate Users | Deactivates the user in Contrast when unassigned or deactivated in Okta. Does not delete the account. | Enable |
Sync Password | Not applicable to SCIM/SAML integrations. | Leave unchecked |
Select Save.
Configure attribute mappings
Go to Provisioning > To App and review the Attribute Mappings section. The defaults work for most deployments.
Okta profile attribute | SCIM attribute | Notes |
|---|---|---|
|
| Primary mapping. Must match the user's login email in Contrast. |
|
| |
|
| |
|
| |
|
|
The userName mapping matters most. Contrast uses it to search for existing users. If a user's login in Okta does not match their login email in Contrast, the search returns no results and Okta creates a new account instead of matching the existing one.
Note
Okta sends a placeholder password field during user creation. Contrast ignores it. SCIM-created users authenticate through SSO, not with a password stored in Contrast.
Assign users
Go to the Assignments tab in the Okta app.
Select Assign > Assign to People or Assign to Groups.
Choose the users or groups to provision, then select Save and Go Back.
Okta starts provisioning immediately. It searches for each user by email before creating a new account, so existing Contrast users are matched rather than duplicated.
Configure Push Groups (optional)
Push Groups syncs Okta group membership to Contrast as User Access Groups.
Go to the Push Groups tab in the Okta app.
Select Push Groups.
Choose Find groups by name to select specific groups, or Find groups by rule to push any group matching a name pattern.
Note
Okta is the source of truth for pushed group membership. Changes made directly in a pushed group in Contrast are overwritten on the next sync. A group cannot be used for both direct app assignment and Push Groups at the same time.
Known limitations
Bearer tokens do not auto-refresh. Rotate the token before it expires (up to 9 months out), or provisioning stops silently. Recovery requires generating a new token, pasting it into Okta's configuration, and running Provisioning > To App > Force Sync.
SCIM-provisioned groups have no default role assignments. Users added to a group created through Push Groups won't have permissions in Contrast until an admin assigns roles to the group manually. This applies to Okta and Entra.
Okta deactivates, but does not delete. Unassigning a user from the Okta app sets the account to inactive in Contrast. It doesn't remove the account.
A stale token can break user matching. If a token expires mid-sync, failed requests can disrupt Okta's internal record of which Contrast user maps to which Okta user. Subsequent retries may search using Okta's internal ID instead of email, which Contrast won't recognize, until you generate a new token and force a resync.
Troubleshoot
Symptom | Cause | Resolution |
|---|---|---|
Provisioning fails after working for a while | Bearer token expired | Generate a new token, paste it into the app's Provisioning config, and run Force Sync. Consider registering a client with a longer |
Okta cannot match an existing Contrast user, creates a duplicate instead |
| Check your attribute mapping. |
| Your organization already has 3 registered OAuth2 clients, or the client ID you chose is already registered (to this org or another) | Delete an unused client, or choose a different client ID, then retry. |
User provisioning fails | RBAC is not enforced for your organization | Enable RBAC for your organization, then retry. |
Retries fail even after generating a new token | A previous token expiration broke Okta's internal user mapping | Run Provisioning > To App > Force Sync after updating the token. |