Provision users and groups with SCIM

Enterprise Tier

From 0.10.0 an identity provider can manage Agent Router users and groups over SCIM 2.0. Creating a user in the provider creates the user here, deactivating or deleting the user blocks sign-in, sessions, keys, and new OAuth tokens, and a provider group named team:<name> becomes a team.

---

Optional configuration

Base SSO must already be configured, because a provisioned user still signs in through single sign-on. SCIM manages who exists and who is blocked; it does not sign anyone in.

Prerequisites

• The management plane runs 0.10.0 or later.
• An identity provider with a SCIM 2.0 client.
• An organization admin, because only an organization admin can create the key the provider uses.
• A deployment that serves SCIM. Where SCIM is unavailable, the endpoint answers 503, with the header X-Scim-Unavailable: shared when the deployment uses a shared authentication database.

Step 1: create the SCIM key

The identity provider authenticates with an organization-wide management key whose only scope is SCIM Provisioner.

1. In the Admin Console, create an organization-wide management key.
2. Choose SCIM Provisioner as its only scope. The scope cannot be combined with another scope or with a platform role, and a request for a key that tries is refused with 403.
3. Copy the key. It is the bearer token the identity provider sends.

The key can reach the SCIM endpoint of its own organization and nothing else. Every other API call refuses it.

A key stops working when its owner is banned or deleted. For that reason, a user who owns a live SCIM key cannot be deactivated through SCIM: the request is refused with 409. Rotating the key to another owner first clears the refusal.

Step 2: point the identity provider at Agent Router

Two values go into the provider's SCIM connector:

Setting	Value
Tenant URL (base URL)	https://api.<tenant>.tetrate.ai/v1/customers/<customer_id>/scim/v2
Authentication	Bearer token, the key from step 1

The provider is set to push users and groups. The endpoint accepts the paths below.

Method and path	Behavior
GET /ServiceProviderConfig, /ResourceTypes, /Schemas	Describe the supported features: PATCH and filtering are on; bulk, sorting, ETags, and password changes are off.
GET /Users	Filters on userName eq, externalId eq, emails[type eq "work"].value eq, emails.value eq, or an and of these. count defaults to 100 and is at most 1000. Any other filter is refused with 400 invalidFilter.
POST /Users, PUT /Users/{id}, PATCH /Users/{id}, DELETE /Users/{id}	Create, replace, patch, and delete a user.
GET /Users/{id}	404 for an unknown user, a user outside the organization, and a user the provider deleted.
GET, POST, PUT, PATCH, DELETE /Groups[/{id}]	Manage groups. Matching is by externalId first, then by displayName.

Bulk operations, /Me, /.search, passwords, roles, entitlements, nested groups, and the enterprise user extension are not supported. The enterprise extension is accepted and ignored.

What happens to a user

Event in the identity provider	Effect in Agent Router
Create a user	The user is created with the user role, a verified email, and membership of the default project. A user who already signed in through SSO with the same email is adopted when that is safe, and refused with 409 otherwise.
Deactivate (active: false)	The user is banned. Sessions end, and the user's API keys and OAuth tokens are revoked. An operator ban already in place is left as it is.
Reactivate (active: true)	The ban SCIM placed is lifted. A ban placed by an operator stays, and the user stays blocked.
Delete	The user is deleted. Where an operator ban is in effect, the user stays banned and only the SCIM record is marked deleted.
Create again after a delete	A user SCIM deleted is restored. A user an operator deleted is refused with 409.

Deactivating the last organization administrator is refused with 409. Revoked sessions and keys stay revoked after a reactivation: the user signs in again and issues new keys.

An email or name change is written to the user only until the first sign-in. After that the account belongs to the person who signed in, and the change is kept on the SCIM record and audited as SCIM_EMAIL_DRIFT.

First sign-in of a provisioned user

A user created over SCIM is treated as new at the first corporate SSO sign-in, so a provider configured with the on_create role sync mode applies the role its claims assert. A role an administrator set on the user before that sign-in is kept when no claim decides the role. A user who signed in some other way before the first SSO sign-in is treated as an existing user: the role is kept and no first-admin seat is taken, and under on_create a role the provider asserts still applies at that first corporate sign-in. See Configure SSO role mapping.

What happens to a group

Group in the identity provider	Effect in Agent Router
team:<name> (the default prefix)	A team named <name> is created, or an existing team of that name is adopted. The members of the group become the members of the team. The prefix is matched without regard to case, so Team:<name> and TEAM:<name> also create teams.
Any other name	An access-control group named scim:<name> is created. It grants nothing until it is bound to a role.

The kind of a group is decided when the group is created. A later rename across the team: boundary does not change it, and changing the kind takes deleting the group and creating it again.

A user belongs to one team. When the provider puts a user in several team: groups, the team whose name sorts first in byte order wins, and the choice is recomputed on every membership change and rename. Team spend follows the current team, so a rename that reorders the names moves future spend.

A rename onto a name another team already holds returns success and keeps the old team name. The new name is stored, and the event is audited as SCIM_GROUP_RENAME_BLOCKED for an administrator to resolve. Deleting a group removes the memberships SCIM wrote. A team that still has members added by hand, or an active budget, is kept as an unmanaged team instead of deleted.

Unban or restore a user the identity provider blocks

A user the provider deactivated or deleted cannot be brought back from the Admin Console. Unbanning or restoring such a user is refused, and the message names what to do:

• The provider turned the user off: turn the user back on in the provider. The next sync restores access.
• The user is also blocked by the provider after an operator ban: turn the user back on or add the user back in the provider first, then unban here.
• The provider deleted the user: add the user back in the provider. The next sync restores the user.

A deletion an operator made is the exception: it can be restored in the Admin Console, because SCIM refuses to re-create it. See Manage user accounts.

Audit and limits

Every SCIM change is written to the audit log with an action that starts with SCIM_, for example SCIM_CREATE_USER, SCIM_DEACTIVATE_USER, and SCIM_GROUP_RENAME_BLOCKED. The actor is the SCIM key.

Each key is limited to 50 requests per second with a burst of 500. A request over the limit gets 429 with a Retry-After header.

At sign-in, a user the provider deactivated is told the account is banned, not that the provider turned it off.

When a request is refused

Status	Meaning
401	The bearer token is not a key.
403	The key has a scope other than SCIM Provisioner, or the URL names an organization other than the key's own, or other than the one the deployment serves.
409	A create names an existing user that cannot be adopted (an administrator, a user with a password account, or a user holding a platform binding or admin-scoped key), a user an operator deleted is created again, the last organization administrator or a SCIM key owner would be deactivated, or a duplicate was posted.
429	The key's rate limit was passed. Retry after the interval in Retry-After.
503	SCIM is not available on this deployment.