Provision users and groups from Okta
Okta pushes users, groups, and memberships into a Gravitino metalake over SCIM 2.0. This page covers what Okta needs and where its behavior differs from the protocol description in SCIM provisioning, which is worth reading first.
Quick Start
1. Mint a SCIM token for the metalake Okta will populate, as described in SCIM provisioning.
2. Create an application integration in Okta that supports SCIM provisioning, and enable provisioning to the application.
3. Supply the connector settings.
| Setting | Value |
|---|---|
| SCIM connector base URL | https://{scim_host}/scim/v2/metalakes/{metalake_name} |
| Unique identifier field for users | userName |
| Authentication mode | HTTP Header |
| Authorization | Bearer {token_value} |
Supported provisioning actions to enable: push new users, push profile updates, and push groups.
4. Assign a user and confirm they appear in the metalake before assigning everyone.
5. Push groups separately. Assigning users does not push their groups. Group push is configured on its own and each group is selected explicitly.
Base URL
Okta appends /Users and /Groups to the base URL itself, so the base URL stops at the metalake.
Including the resource path produces requests against /Users/Users, which fail with a 404 that
looks like a wrong metalake name.
Unlike Entra, Okta needs no compatibility query parameter. The aadOptscim062020 parameter is
specific to Entra's provisioning job and has no effect here.
Attribute Mappings
Okta's default user mappings work against Gravitino with one requirement: userName must map to a
value that is stable and unique, since it is the matching attribute. Okta's user.login is the
usual choice. Mapping it to an email address that changes when someone's name changes will produce
a duplicate user rather than an update.
Leave the unique identifier field set to userName. Changing it to email or a custom attribute
means Okta correlates on something Gravitino does not filter on, and every cycle creates users
rather than matching existing ones.
Attributes beyond userName, displayName, name, active, and emails are accepted and stored
but are not used for access control. The manager attribute requires the SCIM enterprise user
extension and is not needed.
Deprovisioning
Okta soft deletes. Unassigning a user from the application, deactivating them in the directory, or
suspending them all send a PATCH setting active to false rather than a DELETE. The user stays
in the metalake marked inactive.
This is the behavior to expect and to test for. An operator watching for the user to disappear entirely will conclude deprovisioning failed when it worked.
If your policy requires the record to be removed rather than deactivated, that is a deliberate follow-up action in Gravitino, not something Okta will do for you.
Group Push
Group push is separate from user assignment, and this is the most common source of confusion during setup. A group that exists in Okta and contains assigned users still does not reach Gravitino until that specific group is selected for push.
Pushed groups arrive as groups in the metalake with their memberships. Grant Gravitino roles to those groups to connect directory membership to access.
Removing a group from push stops synchronizing it. Whether the group is deleted in Gravitino or left in place depends on how the push entry is removed, so confirm the behavior on a test group before doing it to a real one.
Troubleshooting
Okta reports provisioning failures per user with the response body from the endpoint, which is the fastest place to see what Gravitino rejected.
A user created on every cycle instead of updated means the matching attribute is not stable. Check
that the unique identifier field is userName and that whatever feeds it does not change.
Users provisioning but groups absent means group push is not configured, not that group provisioning is broken.
A connection test that passes followed by nothing happening means no users are assigned to the application.