How to configure SCIM provisioning

Overview

This guide explains how to connect your identity provider (IdP) to Redtrust through SCIM so that user and group creations, changes, and deletions reach the domain automatically. When you're done, your IdP creates, updates, and deactivates the domain's users without you having to manage them by hand.

To learn what SCIM manages and how it changes the console when you turn it on, see SCIM provisioning.

Before you start

You need the following:

• A supported domain: SCIM is only available on SAML 2.0 and OAuth 2.0 domains that are already configured and running. See Domains to learn how to configure each type. If you don't have one yet, the Integrate Redtrust with an identity provider tutorial walks through the SAML 2.0 integration step by step.
• Sufficient permissions: The user who configures the provisioning needs the Configure permission in the Access > Domain section. See Role permissions settings. For Cloud users, the Customer Success team configures this permission.
• Access to your IdP: You need to be able to edit your IdP's provisioning application.
• Connectivity: Your IdP must be able to reach the base URL of the Redtrust SCIM API. Cloud IdPs send requests from their own servers, so for on-premises deployments you need to check that the endpoint is reachable from the internet.

Step 1: Turn on SCIM for the domain

1. Go to Access > Domain.
2. Open the SAML 2.0 or OAuth 2.0 domain you want to provision and select the SCIM tab.
3. Click Configure SCIM.

The tab now shows the domain's Base URL, the list of Tokens, and the option to unlink SCIM.

Step 2: Generate a token

1. In the Tokens section, click Generate.
2. Select the token's expiration: Never, 30 days, 90 days, 180 days, or 1 year.
3. Click Generate token.
4. Copy the token and save it in your secrets manager.

warning

The full token is shown only once. After you close the window, the list only shows its last characters. If you lose it, you must generate a new one and update your IdP's configuration.

note

Never is the default option. If you set an expiration date, keep in mind that Redtrust doesn't warn you before the token expires, and that once it expires, your IdP stops provisioning users until you provide it with a new one.

Step 3: Connect your IdP

1. In the SCIM tab, click Copy next to the Base URL.

2. In your IdP's provisioning application, paste the base URL and the token into the corresponding fields. Each IdP names them differently:

   IdP	Field for the base URL	Field for the token
   Entra ID	Tenant URL	Secret Token
   Okta	SCIM connector base URL	Authorization (HTTP Header mode)
   Others	Base URL or SCIM endpoint	Bearer token

3. Replace the host name in the URL you just pasted with the one from your Redtrust instance. The console's Base URL field isn't editable and contains a sample value, so you need to fix the URL in your IdP.

4. Turn on your IdP's write provisioning actions: sending new users, sending profile changes, and sending groups. Leave user and group import turned off, because the flow goes from the IdP to Redtrust, not the other way around.

5. Run your IdP's connection test to check that it reaches the Redtrust API and that the token is valid.

The specific configuration of each field depends on your IdP. Check its documentation to complete this part:

• Okta: Add SCIM provisioning to app integrations
• Entra ID: Integrate your SCIM endpoint with the Microsoft Entra provisioning service

Step 4: Adjust the attribute mapping

Your IdP includes a default mapping with many more attributes than Redtrust supports. Keep only the following:

• Username: Required. Must be unique within the domain.
• First and last name: You must send at least one of the two.
• Email: Required. Redtrust uses the first address it receives.
• Status: Determines whether the user can authenticate. It's the attribute you use to remove someone's access without deleting their account.
• External ID: Links each user to their account in the IdP.

Remove every other attribute from the mapping. Redtrust ignores them, so keeping them in the mapping only makes it look like data is being applied that never actually reaches the domain.

Step 5: Provision groups

Your IdP can also maintain the domain's groups and their membership. Redtrust supports creating groups, renaming them, adding and removing members, and deleting them.

1. Turn on group provisioning in your IdP and select the groups you want to send to Redtrust.
2. Start the group sync.
3. In Redtrust, open the domain and select the Groups tab to check that the groups and their members arrived.

In Okta, this feature is called Group Push and is configured in the app's Push Groups tab. See Group Push.

note

If a group includes a member that doesn't exist yet as a domain user, Redtrust skips that member instead of rejecting the rest of the group. The member is added on the next group sync your IdP sends, once it has provisioned them as a user. To avoid this, provision users first and groups second.

Step 6: Verify provisioning

1. Start the sync from your IdP or wait for its automatic cycle.
2. In Redtrust, go to Access > Domain, open the domain, and select the Users tab.
3. Check that the SCIM column identifies the users your IdP just provisioned.
4. Go to Events > System logs and check that the user creation events appear. See Events.

The buttons to create, edit, and delete domain users are no longer available for SCIM. This is expected: your IdP now manages the users.

Summary

You turned on SCIM for a SAML 2.0 or OAuth 2.0 domain, generated an access token, and connected your IdP to the Redtrust SCIM API. Your IdP now keeps the domain's users and groups up to date, and the SCIM column in the user list lets you check which ones it manages.

Next steps

• Assign a role to the provisioned users or groups so they can access the admin console. See Roles.
• Review the operations your IdP performs on the domain in the system logs.
• See SCIM provisioning to learn about the API's limitations.
• When you need to rotate or revoke a token, or unlink SCIM from the domain, see How to manage the SCIM lifecycle.