SCIM provisioning

Overview

SCIM (System for Cross-domain Identity Management) is the standard identity providers (IdPs) use to create, update, and delete user accounts in the applications they give access to. Redtrust exposes a SCIM 2.0 API that your IdP writes to directly: when you onboard someone in the IdP, their user appears in Redtrust without manual intervention, and when you offboard them, their access disappears.

Without SCIM, Redtrust creates the users of a SAML 2.0 or OAuth 2.0 domain through Automatic provisioning of users, the first time each person authenticates. With SCIM, the IdP doesn't wait for that first login: it sends every creation, change, and deletion as soon as it happens, and becomes the source of truth for the domain's users and groups.

How it works

To set up provisioning, you turn on SCIM on the domain, generate a token, and copy the base URL and the token into your IdP's provisioning application. From that point on, your IdP queries the Redtrust API to find out which operations and data it supports, and adapts its calls to what it finds.

Your IdP then runs an initial sync. It checks, one by one, whether the users assigned to it already exist in the domain, and creates the ones that are missing. When a user already exists in Redtrust, because Redtrust created it through automatic provisioning the first time the user logged in, the IdP doesn't duplicate it: it links it to the IdP account and starts managing it from that point on. If the domain has reached its user limit, Redtrust rejects the creation and records it in the audit log.

Once the initial sync is complete, your IdP sends every change as soon as it happens. Users keep authenticating with SAML 2.0 or OAuth 2.0 as before, but Redtrust no longer updates their data on every login, because the IdP now maintains it. If you later unlink SCIM, the domain returns to manual management and users keep their access.

Where it's configured

SCIM is only available on SAML 2.0 and OAuth 2.0 domains. To configure it, go to Access > Domain, open the domain, and select the SCIM tab. The tab doesn't appear for other domain types.

To turn on SCIM and manage its tokens, you need the Configure permission in the Domain section. See Role permissions settings.

What SCIM manages

Your IdP can perform these operations on the domain:

Resource	Operations
Users	Creation, update, activation, deactivation, and deletion.
Groups	Creation, renaming, member management, and deletion.

warning

To remove someone's access, deactivate them in your IdP or remove them from the provisioning application. Redtrust then marks them as deactivated: they lose access and keep their certificates. Deleting or suspending the account in the IdP might not send any command to Redtrust, so check the domain's user list to confirm the person shows as deactivated before you consider the offboarding complete.

On every creation and every change, your IdP sends the user's data. Redtrust only processes what it needs to authenticate and authorize, and rejects the operation if any of the required attributes is missing:

Attribute	Required?	What Redtrust does with it
Username	Yes	Identifies the user within the domain. Must be unique.
First and last name	Yes, at least one of the two	Appear in the domain's user list.
Email	Yes	If your IdP sends multiple addresses, Redtrust uses the first one.
Status	No	Determines whether the user can authenticate. When you deactivate the user in the IdP, they lose access but keep their certificates and permissions.
External ID	No, but recommended	Links the user to their account in the IdP.

The external ID is what connects both systems. Redtrust stores the value the IdP sends and uses it to tell which users the IdP manages from which are still managed manually. It's what you see in the SCIM column of the user list, and what Redtrust deletes when you unlink SCIM. A user without an external ID isn't linked to SCIM, so the IdP doesn't manage or update it. It still exists in the domain and authenticates with SAML 2.0 or OAuth 2.0 normally, just like before you turned on SCIM.

Redtrust ignores every other attribute from the standard SCIM schema, such as passwords, roles, language, and the Enterprise User extension. Your IdP sends many of these by default, so you should remove them from the attribute mapping to reflect what Redtrust actually applies.

For groups, Redtrust uses the name and the member list. Group names are unique within the domain, so a rename that matches an existing group is rejected. Provisioned groups work the same as any other domain group, so you can assign a role to a group for its members to inherit. See Roles.

SCIM doesn't manage Redtrust roles or certificates either. Even though the IdP creates the user, you must assign it a role in Redtrust for it to access the admin console.

How the console changes when SCIM is enabled

While SCIM is enabled on a domain, the console reflects that the IdP manages its users and groups:

• Manual management disabled: The buttons to create, edit, and delete domain users and groups are no longer available.
• Status column: In the domain's user list, the Mapped column becomes SCIM and identifies the users the IdP already manages. When you unlink SCIM, that same column becomes Mapped again, showing whether Redtrust keeps the user's data up to date through attribute mapping.
• Attribute mapping on login: Redtrust stops updating existing users' data and groups every time they authenticate, because that information now arrives through SCIM.

Access tokens

Your IdP authenticates to the SCIM API with a bearer token that belongs to the domain. Redtrust stores only a hash of the token, never its plaintext value, and each token is tied to the domain that generated it, so it never grants access to another domain's users.

The SCIM tab lists the domain's tokens with their Status, Last use, and Valid from and Valid until dates. A token generated with no expiration shows as No deadline.

Rule	Detail
Visibility	The full token is shown only once, when you generate it. After that, the list only shows its last characters.
Number of tokens	Each domain supports a maximum of two active tokens at a time.
Expiration	You can generate the token with no expiration, or with a validity of 30, 90, or 180 days, or 1 year.
Rotation	Before you generate a second token, the existing token must have an expiration date. If it doesn't, the console asks you to set one with a term of 1, 3, 7, 14, or 28 days.
Shortening the expiration	You can move up the expiration date of an active token, but never push it back.
Revocation	When you revoke a token, it stops being valid immediately. This action can't be undone.

warning

Save the token in a secrets manager as soon as you generate it. If you lose it, you can't recover it: you must generate a new one and update your IdP's configuration.

Unlink SCIM

Unlink returns the domain to manual management. When you unlink SCIM, Redtrust takes three actions:

1. Revokes all of the domain's active tokens.
2. Removes the IdP identifier from its users and groups.
3. Restores manual management of users and groups in the console.

Users and groups are preserved, along with their certificates and permissions. What disappears is the link to the IdP, so your IdP can no longer modify them.

If you turn SCIM back on later, the IdP recovers the link to the users that already exist in Redtrust when it provisions them again, instead of duplicating them.

System logs

Redtrust records every operation the IdP performs through SCIM in the system logs:

Recorded operation	When it occurs
User creation	The IdP creates a user in the domain.
User update	The IdP modifies a user or links one that already existed in Redtrust.
User deletion	The IdP deletes a user from the domain.
User creation rejected	The IdP tries to create a user and the domain has reached its user limit.
Group creation	The IdP creates a group in the domain.
Group update	The IdP modifies an existing group.
Group deletion	The IdP deletes a group from the domain.

Unlinking SCIM from a domain is recorded in the system log, along with the rest of the actions performed from the admin console.

Limitations

Your IdP queries the supported capabilities at the API's /ServiceProviderConfig endpoint and adjusts its behavior accordingly. Keep these limitations in mind when planning the integration:

• Filters: The API supports a single filter expression using the eq or ne operators. It doesn't support expressions combined with and, or, or not, or operators such as co, sw, or pr.
• Pagination: Each response returns a maximum of 200 results.
• Unsupported operations: Bulk operations, result sorting, ETags, and password changes aren't available.

Related guides

• How to configure SCIM provisioning
• How to manage the SCIM lifecycle