SCIM user provisioning

Introduction

This guide helps you configure automatic user provisioning from your Identity Provider (IdP) to the RansomLeak platform using SCIM 2.0 (System for Cross-domain Identity Management).

With SCIM enabled, your organization can:

• Automatically create users when they’re assigned to the application in your IdP
• Automatically update user attributes when they change in your IdP
• Automatically deactivate users when they’re unassigned from the application
• Sync groups to target training and, optionally, grant roles

With chat learning, users your IdP creates can also get a welcome lesson in Slack, and users whose job title or department changes a lesson on their new role, if you turn on those just-in-time triggers. The first sync of a user never sends a role-change lesson.

Prerequisites

Before you begin, ensure you have:

1. Administrator access to your Identity Provider (Microsoft Entra ID, Okta, etc.)
2. SCIM credentials from RansomLeak support (see Step 1)

Step 1: Obtain SCIM Credentials

Important: SCIM provisioning is managed by RansomLeak support. You must request SCIM credentials from them before proceeding.

Contact RansomLeak support to enable SCIM for your organization. They will provide you with:

Credential	Description	Example
SCIM Endpoint URL	Where your IdP sends provisioning requests	https://yourcompany.ransomleak.com/scim/v2
Bearer Token	Secret authentication token (48 characters)	a1b2c3d4e5f6789...

Important Notes

• The bearer token is shown only once when generated by RansomLeak support
• Store the token securely - treat it like a password
• If you lose the token, contact RansomLeak support to generate a new one

Step 2: Configure Your Identity Provider

Microsoft Entra ID (Azure AD)

2.1 Create Enterprise Application

1. Go to the Microsoft Entra admin center
2. Navigate to Identity → Applications → Enterprise Applications
3. Click + New Application
4. Click + Create your own application
5. Enter a name (e.g., “RansomLeak - SCIM”)
6. Select Integrate any other application you don’t find in the gallery
7. Click Create

2.2 Configure Provisioning

1. In your new application, go to Provisioning
2. Click Get started
3. Set Provisioning Mode to Automatic
4. Under Admin Credentials:
   • Tenant URL: Enter the SCIM Endpoint URL provided by your administrator
   • Secret Token: Enter the Bearer Token provided by your administrator
5. Click Test Connection to verify
6. Click Save

2.3 Configure Attribute Mappings

1. Expand Mappings
2. Click Provision Microsoft Entra ID Users
3. Configure the following mappings:

Microsoft Entra ID Attribute	SCIM Attribute	Notes
objectId	externalId	Required - unique identifier
userPrincipalName	userName	Required - email address
givenName	name.givenName	First name
surname	name.familyName	Last name
jobTitle	title	Optional - synced to user profile
Switch([IsSoftDeleted],…)	active	Account status
department	urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department	Creates teams automatically
manager	urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager	Links to manager

4. Click Save

2.4 Configure Group Provisioning (Optional)

If you want to sync groups (as training audiences, and optionally to grant roles):

1. Click Provision Microsoft Entra ID Groups
2. Ensure displayName maps to displayName
3. Ensure members maps to members
4. Click Save

2.5 Assign Users and Groups

1. Go to Users and groups
2. Click + Add user/group
3. Select the users or groups to provision
4. Click Assign

2.6 Start Provisioning

1. Go back to Provisioning
2. Click Start provisioning

Initial sync may take 20-40 minutes. Subsequent syncs occur every 40 minutes.

Okta

RansomLeak is published in the Okta Integration Network. Use the catalog app: it covers SAML sign-on and SCIM provisioning in a single application and builds the SCIM endpoint for you, so there is nothing to paste except your subdomain and token. Only build a custom SCIM app if your Okta org blocks catalog integrations.

2.1 Add the RansomLeak app

1. In the Okta Admin Console, go to Applications → Applications
2. Click Browse App Catalog
3. Search for RansomLeak and click Add Integration
4. Under Subdomain, enter your RansomLeak subdomain (the yourcompany in https://yourcompany.ransomleak.com). It is shown with a copy button on the SCIM and SAML SSO tabs of RansomLeak’s tenant settings.
5. Click Done

2.2 Enable provisioning

1. Go to the Provisioning tab and click Configure API Integration
2. Tick Enable API integration
3. Paste the SCIM bearer token into the API Token field. Enter the token on its own, with no Bearer prefix: the catalog app adds the scheme itself.
4. Click Test API Credentials, then Save
5. Under Provisioning → To App, click Edit and enable:
   • Create Users
   • Update User Attributes
   • Deactivate Users

2.3 Configure attribute mappings

1. Stay on Provisioning → To App
2. Confirm userName maps to the user’s primary email; the catalog app ships the rest of the defaults
3. Adjust the remaining attributes to match the Entra ID table above if your directory uses different source fields

2.4 Assign users

1. Go to the Assignments tab
2. Click Assign → Assign to People or Assign to Groups
3. Select users/groups and click Assign

Alternative: custom SCIM app

If you cannot use the catalog app, create the integration by hand instead:

1. Applications → Create App Integration → SCIM 2.0
2. Set SCIM connector base URL to your SCIM Endpoint URL (https://yourcompany.ransomleak.com/scim/v2)
3. Set Unique identifier field to: userName
4. Under Supported provisioning actions, select:
   • Push New Users
   • Push Profile Updates
   • Push Groups (if using group sync)
5. Set Authentication Mode to: HTTP Header
6. In the Authorization field, enter: Bearer YOUR_SCIM_TOKEN. The Bearer prefix is required here, unlike the catalog app.
7. Click Test Connector Configuration, then Save
8. Configure attribute mappings and assignments as described in 2.3 and 2.4 above

OneLogin

2.1 Add SCIM Application

1. Go to Applications → Add App
2. Search for “SCIM Provisioner with SAML (SCIM v2 Core)”
3. Click Save

2.2 Configure SCIM

1. Go to Configuration
2. Set SCIM Base URL to the SCIM Endpoint URL from your administrator
3. Set SCIM Bearer Token to the token from your administrator
4. Set SCIM JSON Template (use default or customize)
5. Click Save

Step 3: Understanding Groups and Roles

How Group Sync Works

Every group your identity provider syncs becomes a group in RansomLeak (User Management → Groups), with the same members. Use synced groups to target training: give a group automatic learning paths, or add it to campaigns.

A synced group changes people’s roles only if you tell it to:

1. Open User Management → Groups and click the pencil on the synced group.
2. Under Members get role, choose the role and a priority.

Groups without a role are training audiences only and never change anyone’s role. See Roles from groups.

Groups Linked Before This Change

If your identity provider already synced groups to roles, nothing changes for your users: each of those groups became a synced group that grants the same role with the same priority.

Role Priority

If a user belongs to several groups that grant a role, they get the role with the lowest priority number. Roles set on a person by hand are never changed by group sync. A user removed from every role-granting group gets the default role.

Step 4: Verify Provisioning

Check Users Were Created

1. Log in to your admin portal
2. Navigate to Users
3. Verify that provisioned users appear in the list
4. SCIM-provisioned users will show their job title as synced from the identity provider

Common Verification Steps

Check	Expected Result
User appears in user list	✓
First/Last name correct	✓
Email matches IdP	✓
Synced groups appear under User Management → Groups	✓
Team matches department	✓
Job title synced from IdP	✓

Troubleshooting

Users Not Syncing

1. Check Test Connection: In your IdP, re-run the SCIM test connection
2. Verify Token: Ensure the token was copied correctly with no extra spaces
3. Check Assignment: Confirm users are assigned to the application in your IdP
4. Wait for Sync Cycle: Initial sync can take up to 40 minutes

Error: 401 Unauthorized

• Token may be incorrect or expired
• Contact RansomLeak support to verify SCIM is enabled
• Request a new token if needed

Error: SCIM Not Enabled

• Contact RansomLeak support to enable SCIM for your tenant

Users Have Wrong Role

• Check which groups the user belongs to in your IdP
• Check which role each of those groups grants (User Management → Groups)
• Remember: the lowest priority number wins, and roles set by hand are never changed

Manager Not Linked

• The manager must be provisioned before the employee
• Trigger a manual sync or wait for the next sync cycle

Token Expired or Invalid

• Contact RansomLeak support to generate a new token
• Update the new token in your IdP’s SCIM configuration

Security Best Practices

1. Token Security

   • Store the SCIM token securely (treat it like a password)
   • Only share tokens through secure channels
   • If you suspect token compromise, contact RansomLeak support immediately

2. Access Control

   • Only assign users who need access to RansomLeak
   • Use groups to manage role assignments

3. Monitoring

   • Review provisioning logs in your IdP regularly
   • Report any unexpected user creations to RansomLeak support

Getting Help

If you encounter issues not covered in this guide:

1. Check IdP Logs: Your Identity Provider’s provisioning logs show detailed error messages
2. Contact RansomLeak Support: They manage SCIM configuration and can:
   • Verify SCIM is enabled for your tenant
   • Generate new tokens if needed
   • Check SCIM sync status
3. Include Details: When reporting issues, include:
   • Your tenant URL
   • The IdP you’re using
   • Error messages from IdP provisioning logs
   • Timestamps of when the issue occurred

Appendix: SCIM Endpoint Reference

For technical administrators, here are the SCIM endpoints:

Endpoint	Method	Description
/scim/v2/ServiceProviderConfig	GET	SCIM capabilities
/scim/v2/Schemas	GET	Supported schemas
/scim/v2/Users	GET, POST	List/create users
/scim/v2/Users/{id}	GET, PUT, PATCH, DELETE	User operations
/scim/v2/Groups	GET, POST	List/create groups
/scim/v2/Groups/{id}	GET, PUT, PATCH, DELETE	Group operations

Document Version: 2.0