Skip to main content

Provision users and groups from Okta

Okta pushes users, groups, and memberships into Gravitino over SCIM 2.0. Below is what Okta needs and where its behavior differs from the protocol description in SCIM provisioning, which covers tokens and the endpoint.

Quick start​

  1. Create a SCIM token, in the UI or over REST, 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. A user name cannot change once provisioned, so mapping it to an email address that changes when someone's name changes makes every later update for that user fail with 400.

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.

Gravitino keeps only the attributes listed in Supported attributes. Okta pushes profile updates as a full replacement with PUT, which ignores attributes Gravitino does not store, so the remaining default mappings can stay.

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.

Expect and test for deactivation. An operator watching for the user to disappear entirely will conclude deprovisioning failed when it worked.

Gravitino cannot remove a provisioned user on its own, since the Directory deletes local users only. The record goes only when the identity provider sends a DELETE.

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. A pushed group cannot be renamed: renaming it in Okta makes its next push fail with 400.

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