Provision users from Okta with SCIM
SCIM 2.0 lets Okta create, update, suspend and remove people in your Tara organization, and set their role from Okta groups. It does not sign anyone in: people still sign in with Organization SSO (OIDC), so set that up first.
SCIM is included in the Enterprise plan only. On Free and Team an owner cannot create a SCIM token, and a SCIM call from an organization that has lost the feature gets 403 with a message that names the plan (SCIM clients do not understand 402 Payment Required, so Tara uses 403 here).
You need to be an owner of the organization. Only owners can create SCIM tokens and map groups to roles.
In Tara
- Open Settings › SSO and find SCIM provisioning. Create a token and give it a name. Copy the token (starts with
tara_scim_); it is shown once. - Copy the base URL:
https://<tara host>/scim/v2/orgs/<org slug>.<org slug>is your organization's slug. - Optional but recommended: map Okta group names to roles (see Groups and roles).
From the terminal:
ph org scim-token create okta --out scim-token.txt
ph org scim-roles set '{"Engineering":"member","Platform":"admin","Stakeholders":"viewer"}'A token lasts 365 days by default (730 at most), belongs to this organization only, and can call only /scim/v2/orgs/<org slug>/…. An organization can have 10 active tokens, so you can create a second one before revoking the first when you rotate.
In Okta
The labels below are the ones Okta usually shows; they can differ a little between apps and versions.
- In the Okta Admin Console, add an app integration that supports SCIM 2.0 provisioning with HTTP Header authentication. Okta's catalog has a generic SCIM 2.0 app for this; use it, or your own SCIM app integration.
- Open the app's Provisioning tab and choose to configure the API integration (SCIM).
- SCIM connector base URL: the base URL from Tara.
- Unique identifier field for users:
userName. - Supported provisioning actions: turn on Push New Users, Push Profile Updates and Push Groups. Okta deactivates users when they are unassigned or deactivated; make sure the app is allowed to deactivate users.
- Authentication Mode: HTTP Header. Paste the token into the authorization field. Tara accepts only
Authorization: Bearer <token>. If Okta sends the field exactly as typed, enterBearerfollowed by the token. - Choose Test Connector Configuration. Okta calls the base URL; a green result means the token and URL are right. Save.
- Under the app's provisioning settings To App, enable Create Users, Update User Attributes and Deactivate Users.
- Make sure the Okta username attribute mapped to
userNameis the person's work email, and that the email attribute is mapped. Tara links a person by that email. - Assign people and groups to the app. To push groups, use the app's Push Groups tab.
Tara reads only these user attributes: userName, externalId, name (given, family, formatted), displayName, the work emails and active. Anything else Okta sends (title, phone numbers, and so on) is accepted and ignored, so extra mappings do no harm.
What happens
- A person is assigned. Okta creates them in Tara. If someone with that email already has a Tara account with a verified email, they are linked at once and become members. Otherwise Tara holds a pending membership for the email.
- First sign-in. When that person signs in with your organization's SSO and the email from Okta matches, Tara links their account and makes them a member with the role from their groups.
- Okta deactivates a person. Tara removes them from the organization and its projects, takes no seat, and does not let SSO sign-in or auto-join add them back. If you reactivate them in Okta, their membership comes back.
- Okta deletes a person. Tara removes them from the organization. Their Tara account is not deleted.
- Owners are never touched. SCIM never creates, changes or removes an owner.
Groups and roles
scimGroupRoles maps group names to admin, member or viewer (never owner). Names are not case-sensitive.
- A person in several mapped groups gets the highest role.
- If no mapping is set, every provisioned person is a member.
- If a mapping is set but a person is in none of the mapped groups, they are a viewer (free, no seat).
- People you added by hand or by invitation keep the role you gave them. SCIM changes the role of members who joined another way.
- Change the mapping and Tara updates the roles of everyone already linked.
Seats and limits
Admins and members use a seat; viewers do not. If your plan has no seat left, Okta gets 409 with Seat limit reached in the error detail, and shows it as a provisioning error. People already provisioned keep their access. Give new people the viewer role through a group mapped to viewer, or upgrade (Billing and upgrading).
Check it worked
Open Audit log in Tara and look for:
| Action | Meaning |
|---|---|
scim.user.create | Okta created a person |
scim.user.link | Linked to a Tara account (verified_email or oidc_login) |
scim.user.role | Membership added or role changed |
scim.user.suspend, scim.user.reactivate | Okta deactivated or reactivated them |
scim.user.delete | Okta deleted them |
scim.group.create, scim.group.update, scim.group.delete | Group changes |
scim.group.roles | An owner saved the group-to-role mapping |
scim_token.create, scim_token.revoke | An owner created or revoked a token |
Troubleshooting
| You see | Cause |
|---|---|
401 | The token is wrong, expired or revoked, or the header is not Bearer <token>. |
403 | The token belongs to another organization (check the slug in the URL), or something other than a SCIM token was used. |
404 | Wrong path. The base URL must end with the organization slug, with no /Users. |
409 with uniqueness | Another person in the organization already has that userName, email or externalId. |
409 with Seat limit reached | No seat left for this role. See above. |
400 with invalidFilter | Okta used a filter Tara does not support. Tara supports eq on userName, externalId, id, active and the work email for users, and on displayName, externalId, id for groups. |
scim_suspended at sign-in | The person is deactivated in Okta. |
Limits
- No bulk, sort, ETag or password operations.
- Only the
eqfilter operator. - Enterprise extension attributes are not stored.
Tara's own endpoint describes itself at /scim/v2/orgs/<org slug>/ServiceProviderConfig.
For Microsoft Entra ID, see Provision users from Microsoft Entra ID with SCIM.