Guides
Set up SCIM with Okta
Connect an Okta app integration to SqlOS, provision users, push groups, and prove deactivation before rollout.
Okta is the SCIM client and source of lifecycle changes. SqlOS receives the user and group operations, keeps them inside one organization, and mirrors pushed groups into FGA.
The safest first proof uses one directly assigned test user and a separate small group for Group Push.
Complete steps 1 and 2 of the SCIM directory sync guide:
/sqlos/admin/auth/, select the target organization, and open SCIM.Do not append /Users, /Groups, or an organization ID to the Base URL. Okta builds resource URLs beneath the connector base, and the token selects the organization.
For the common combined SSO and provisioning setup, create a private SAML 2.0 app integration in the Okta App Integration Wizard. Okta's custom integration workflow can add SCIM provisioning to SAML or SWA integrations; it does not add SCIM provisioning to a custom OIDC integration.
After creating the app:
| Okta field | Value |
|---|---|
| SCIM connector base URL | The SqlOS Base URL, such as https://identity.example.com/sqlos/scim/v2 |
| Unique identifier field for users | userName |
| Supported provisioning actions | Push New Users, Push Profile Updates, and Push Groups |
| Authentication Mode | HTTP Header |
| Authorization | The one-time SqlOS bearer token |
Choose Test API Credentials, then save.
Paste the token value returned by SqlOS into Okta's HTTP Header authorization field. SqlOS cannot recover the plaintext later. Rotating the token immediately invalidates the value currently stored in Okta.
If the SCIM option is absent, confirm that provisioning is enabled for the Okta org and that the integration type supports it. For a provisioning-only development test, an Okta SCIM 2.0 header-auth test template can be used instead of attaching provisioning to the production SSO integration.
Open Provisioning > To App > Edit and enable:
Without these switches, valid API credentials are not enough: assigning a new person can fail because Okta is allowed to search but not create the missing user.
Review the profile mappings and keep the first rollout centered on SqlOS core attributes:
| Okta profile value | SCIM target |
|---|---|
| Username, normally the work email | userName |
| Primary work email | emails[type eq "work"].value |
| First name | name.givenName |
| Last name | name.familyName |
| Display name or a first/last-name expression | displayName |
| Okta-managed source identifier | externalId |
| Okta user status | active |
Use the same stable work email for userName, the primary work email, and the SAML email assertion if this app also provides SSO. Preserve Okta's externalId value and casing across retries.
Verify SqlOS:
Change the test user's display name in Okta and confirm it updates the same SqlOS resource instead of creating another user.
Okta app assignment and Okta Group Push are related but different controls. Use separate groups for them.
Okta does not support using the same group for app assignment and Group Push. Create one group that assigns people to the app and a second group whose name and membership are pushed downstream. Every pushed-group member must already be assigned and provisioned to the app.
To test Group Push:
SqlOS-Test-Readers.The group is mirrored but has no product permission by default. Add a SCIM group mapping when the group should grant a known FGA role on a known resource.
Remove and re-add one member. Verify the mirrored membership and any inherited mapped access disappear and return without touching manual or unrelated FGA state.
Unassign the test user from the app or deactivate the user in Okta. SqlOS should:
Reassign or reactivate the user and verify Okta reuses the existing SCIM identity. A user shared with another SqlOS organization remains active there, and manual grants or non-SCIM groups are not deleted.
When the same Okta app handles SAML and SCIM, give each protocol one job:
Follow Pair SCIM provisioning with SAML sign-in for the two linking-policy choices and a complete rollout test.
| Okta result | Likely cause | Resolution |
|---|---|---|
Test API Credentials returns 401 | Token is wrong, rotated, or the SqlOS connection is disabled | Rotate or recopy the token and update Okta |
Test API Credentials returns 404 | Connector base URL is wrong or SCIM is disabled | Use the exact Base URL from SqlOS and confirm EnableScim |
| Assignment says matching user not found | Create Users is disabled under To App | Enable Create Users, Update User Attributes, and Deactivate Users |
| User conflicts on create | Username, work email, or external ID collides with another connection resource | Correct the Okta profile values instead of retrying with a new identity |
| Group appears without members | Members were not individually assigned/provisioned, or the assignment group was reused | Provision members first and use a separate Group Push group |
| A pushed group reports an error | Target state was edited directly or the push mapping is stale | Inspect the Push Groups error details, correct the source/push mapping, and retry from Okta |
Okta's System Log and task details explain the outgoing attempt. SqlOS SCIM activity explains persisted operations and reconciliation failures. SqlOS Audit Logs explain the resulting security state.