How to Configure SCIM Provisioning

Advanced 25 minutes Org Admins Team & Access Management

Automate user provisioning and deprovisioning from your identity provider using SCIM 2.0.

Overview

SCIM (System for Cross-domain Identity Management) 2.0 lets your identity provider automatically create, update, and deactivate user accounts in Chainsaw. Instead of manually inviting users or relying solely on JIT provisioning, SCIM keeps Chainsaw in sync with your IdP’s user directory.

With SCIM:

  • New users are automatically provisioned when added to the Chainsaw app in your IdP
  • Deactivated users are automatically disabled and removed from the organization
  • Group changes in your IdP update Chainsaw role assignments
  • Attribute updates (name, email) are synced automatically

Prerequisites

  • Owner or Admin role in Chainsaw
  • An IdP that supports SCIM 2.0 outbound provisioning (Okta, Azure AD, OneLogin, CyberArk Identity, etc.)
  • SSO is recommended but not required

Step 1: Generate a SCIM Bearer Token

Navigate to Settings > SCIM.

  1. Enter a descriptive token name (e.g. “Okta SCIM” or “Azure AD Provisioning”)
  2. Click Generate Token
  3. Copy the token immediately – it is shown only once
Store the SCIM token securely. If lost, delete it and generate a new one. Treat it like an API key.

Step 2: Copy the SCIM Base URL

On the same page, copy the SCIM Endpoint URL displayed at the top:

https://chain305.com/chainproxy/scim/v2

You will enter both the token and URL into your IdP in the next step.

Step 3: Configure Your IdP for SCIM Provisioning

Okta

  1. Navigate to your Chainsaw application in Okta
  2. Go to the Provisioning tab > Configure API Integration
  3. Check Enable API integration
  4. Enter the SCIM Base URL and Bearer Token
  5. Click Test API Credentials to verify connectivity
  6. Under Provisioning > To App, enable:
    • Create Users
    • Update User Attributes
    • Deactivate Users
  7. Go to Assignments and assign users/groups to the application

Azure AD (Entra ID)

  1. Navigate to Enterprise Applications > your Chainsaw app
  2. Go to Provisioning > Get started
  3. Set Provisioning Mode to Automatic
  4. Under Admin Credentials:
    • Tenant URL: your SCIM Base URL
    • Secret Token: your SCIM bearer token
  5. Click Test Connection
  6. Configure Attribute Mappings (map userPrincipalName to userName, mail to emails[type eq "work"].value)
  7. Set Provisioning Status to On

CyberArk Identity

  1. Navigate to Apps > Web Apps > your Chainsaw app
  2. Enable Provisioning in the app settings
  3. Enter the SCIM Base URL and Bearer Token
  4. Configure user/group sync settings
  5. Map CyberArk roles to Chainsaw groups
Most IdPs will test the connection by calling the SCIM ServiceProviderConfig endpoint. If the test fails, verify the URL includes the /chainproxy prefix and ends with /scim/v2 and the bearer token is correct.

Step 4: Map SCIM Groups to Chainsaw Roles

SCIM groups in Chainsaw map directly to roles. When your IdP assigns a user to a SCIM group, Chainsaw updates their membership role.

The available groups correspond to Chainsaw’s built-in roles:

SCIM Group IDChainsaw Role
org-adminOrganization Admin
org-ownerOrganization Owner
org-managerManager
org-memberMember

Custom roles are also available as SCIM groups (using their slug as the group ID).

To assign roles via SCIM:

  1. In your IdP, create groups matching the Chainsaw role names
  2. Assign users to the appropriate groups
  3. Push the group assignments via SCIM
Combine SCIM provisioning with SSO group-to-role mappings for defense in depth. SCIM sets the initial role during provisioning, and group mappings re-validate on every login.

Step 5: Verify Provisioning

After configuring your IdP:

  1. Assign a test user to the Chainsaw application in your IdP
  2. Wait for the provisioning cycle (Okta: near-instant, Azure AD: up to 40 minutes for first sync)
  3. Navigate to Settings > Users in Chainsaw and verify the user appears
  4. Check Settings > SCIM for the Last Used timestamp on your token to confirm API calls are happening

Testing User Lifecycle

Action in IdPExpected in Chainsaw
Assign user to appUser created with Member role (or group-assigned role)
Update user nameUser name updated
Change group assignmentUser role updated
Unassign user from appUser deactivated and removed from org

Supported SCIM Operations

Chainsaw’s SCIM server supports:

ResourceOperations
UsersList (GET with filters), Create (POST), Get (GET), Replace (PUT), Patch (PATCH), Delete (DELETE)
GroupsList (GET), Get (GET), Replace (PUT), Patch (PATCH)
FiltersuserName eq "value", emails.value eq "value", externalId eq "value"

Troubleshooting

IssueCauseFix
Test connection failsWrong URL or tokenVerify the URL is https://chain305.com/chainproxy/scim/v2 – the /chainproxy prefix is required and /chainsaw/scim/v2 returns a 404 from the static site, not from the API; regenerate token if needed
Users not provisionedIdP provisioning not enabledCheck IdP provisioning settings are “On” with create/update enabled
Duplicate user errorUser already exists with that emailExisting users are linked automatically on email match
Role not updatedGroup push not configuredEnable group push in your IdP’s SCIM settings
Azure AD slow to syncNormal first-sync behaviorInitial sync can take 20-40 minutes; subsequent syncs are faster

Checking SCIM Activity

Monitor the Last Used column on the SCIM tokens page to verify your IdP is making API calls. For detailed troubleshooting, check server logs:

docker logs chainsaw | grep -i "scim"

Best Practices

  • Use one SCIM token per IdP – if you have multiple IdPs, create separate tokens
  • Name tokens descriptively – e.g. “Okta Production” or “Azure AD Staging”
  • Rotate tokens periodically – delete old tokens and generate new ones
  • Combine with SSO – SCIM handles provisioning, SSO handles authentication
  • Test in staging first – verify user create/update/deactivate cycles before production
  • Monitor the token activity – a token that stops being used may indicate a broken integration

Next Steps