Skip to main content

Provision users and groups from Okta

Okta pushes users, groups, and memberships into Gravitino 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. Create a SCIM token, 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.

    SettingValue
    SCIM connector base URLhttps://{scim_host}/scim/v2
    Unique identifier field for usersuserName
    Authentication modeHTTP Header
    AuthorizationBearer {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 Gravitino 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.

  6. Add provisioned users and groups to a metalake and grant roles. Provisioning creates the identities only; a provisioned user reaches nothing until they belong to a metalake and hold a role there.

Base URL​

Okta appends /Users and /Groups to the base URL itself, so the base URL ends at /scim/v2 and has no metalake in it. Including the resource path produces requests against /Users/Users, which fail with a 404.

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 Gravitino's directory, 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 in Gravitino's directory with their memberships. Add them to a metalake and grant roles to them there 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.

Last updated on