SCIM Provisioning

Automate user provisioning and deprovisioning with SCIM 2.0

BuildBetter supports SCIM 2.0 (System for Cross-domain Identity Management) for automated user lifecycle management. SCIM enables your identity provider to automatically create, update, and deactivate user accounts in BuildBetter.

SCIM provisioning is available for Enterprise customers with custom SAML SSO integrations. Contact your account representative to enable SCIM for your organization.

Overview

SCIM automates the user provisioning process, ensuring that:

• New employees automatically get BuildBetter access when added to your identity provider
• Departing employees are immediately deprovisioned when removed from your identity provider
• User profile changes (name, email) are synced automatically
• Account management is centralized in your identity provider

Automatic Provisioning

New users are created in BuildBetter when assigned in your IdP

Automatic Deprovisioning

Users are deactivated when unassigned or removed from your IdP

Profile Sync

User profile updates are synchronized automatically

Centralized Control

Manage all access from your identity provider

Supported Identity Providers

BuildBetter’s SCIM implementation works with any SCIM 2.0 compliant identity provider, including:

• Okta
• Azure Active Directory (Entra ID)
• OneLogin
• JumpCloud
• Google Workspace (with SCIM connector)
• Ping Identity

SCIM Capabilities

Supported Operations

Operation	Description	Supported
Create User	Provision new users in BuildBetter	Yes
Update User	Modify user profile attributes	Yes
Deactivate User	Disable user access without deletion	Yes
Delete User	Remove user from BuildBetter	Yes
Get User	Retrieve user information	Yes
List Users	Retrieve all provisioned users	Yes

Supported Attributes

BuildBetter supports the following SCIM user attributes:

SCIM Attribute	BuildBetter Field	Required
userName	Email address (primary identifier)	Yes
name.givenName	First name	Yes
name.familyName	Last name	Yes
active	Account status	Yes
emails[primary]	Primary email	Yes
displayName	Display name	No

Role-based access control (RBAC) and department assignments are managed within BuildBetter’s admin settings rather than through SCIM. This allows for flexible permission configurations that may not map directly to your IdP’s group structure.

Setting Up SCIM with Okta

Follow these steps to configure SCIM provisioning with Okta:

1. Request SCIM Configuration

   Contact BuildBetter support at [e-mail] to request SCIM provisioning setup. We’ll provide you with:

   • SCIM Base URL
   • API Bearer Token for authentication
   • Any organization-specific configuration details
2. Create SCIM Application in Okta

   1. Log in to your Okta Admin Console
   2. Navigate to Applications > Applications
   3. Click Create App Integration
   4. Select SAML 2.0 (if you haven’t already configured SAML SSO)
   5. Or select your existing BuildBetter SAML application
3. Configure Provisioning

   1. In your BuildBetter application, go to the Provisioning tab
   2. Click Configure API Integration
   3. Check Enable API Integration
   4. Enter the SCIM Base URL provided by BuildBetter:
      https://api.buildbetter.ai/scim/v2
      

   5. Enter the API Token (Bearer Token) provided by BuildBetter
   6. Click Test API Credentials to verify the connection
   7. Click Save
4. Enable Provisioning Features

   After saving the API configuration:

   1. Go to Provisioning > To App
   2. Click Edit
   3. Enable the following options:
      • Create Users - Provision new users
      • Update User Attributes - Sync profile changes
      • Deactivate Users - Disable access when unassigned
   4. Click Save
5. Configure Attribute Mappings

   1. Go to Provisioning > To App > Attribute Mappings
   2. Verify the following mappings are configured:

   Okta Attribute	BuildBetter Attribute
   user.email	userName
   user.firstName	name.givenName
   user.lastName	name.familyName
   user.email	emails[primary].value

   3. Click Save after making any changes
6. Assign Users

   1. Go to the Assignments tab
   2. Click Assign > Assign to People or Assign to Groups
   3. Select the users or groups that should have access to BuildBetter
   4. Click Save and Go Back
   5. Click Done

   Assigned users will be automatically provisioned in BuildBetter.

Keep your SCIM API token secure. If you believe your token has been compromised, contact BuildBetter support immediately to rotate the credentials.

Setting Up SCIM with Azure AD (Entra ID)

1. Request SCIM Configuration

   Contact [e-mail] to receive your SCIM credentials.

2. Configure Enterprise Application

   1. Log in to the Azure Portal
   2. Navigate to Azure Active Directory > Enterprise Applications
   3. Select your existing BuildBetter application or create a new one
   4. Go to Provisioning in the left menu
   5. Set Provisioning Mode to Automatic
3. Enter Admin Credentials

   In the Admin Credentials section:

   • Tenant URL: Enter the SCIM Base URL from BuildBetter
     https://api.buildbetter.ai/scim/v2
     

   • Secret Token: Enter the API Bearer Token from BuildBetter

   Click Test Connection to verify, then Save

4. Configure Mappings

   1. Expand Mappings
   2. Select Provision Azure Active Directory Users
   3. Verify the attribute mappings match your requirements
   4. Enable the mapping and save
5. Start Provisioning

   1. Set Provisioning Status to On
   2. Click Save
   3. Azure AD will begin initial synchronization

User Lifecycle Management

When a User is Assigned

When you assign a user to BuildBetter in your identity provider:

1. The IdP sends a SCIM create request to BuildBetter
2. BuildBetter creates the user account with the provided attributes
3. The user receives a welcome email (if enabled)
4. The user can sign in via SSO immediately

When a User is Updated

When you update a user’s profile in your identity provider:

1. The IdP sends a SCIM patch request to BuildBetter
2. BuildBetter updates the user’s profile with the new attributes
3. Changes take effect immediately

When a User is Unassigned or Deactivated

When you remove a user’s access in your identity provider:

1. The IdP sends a SCIM deactivate request to BuildBetter
2. BuildBetter deactivates the user account
3. The user can no longer sign in
4. User’s data is retained according to your data retention policy

Deactivated users’ data remains accessible to administrators for compliance and audit purposes. If you need to permanently delete user data, contact [e-mail].

Troubleshooting

Users not being provisioned

Common causes:

• API credentials are incorrect or expired
• User is not assigned to the application in your IdP
• Required attributes (email, first name, last name) are missing

Solutions:

1. Test the API connection in your IdP’s provisioning settings
2. Verify the user is assigned to the BuildBetter application
3. Check that all required user attributes are populated
4. Review provisioning logs in your IdP for specific error messages

Profile changes not syncing

Common causes:

• Attribute mappings are misconfigured
• Provisioning is paused or disabled
• Rate limiting on API requests

Solutions:

1. Verify attribute mappings in your IdP
2. Ensure provisioning is enabled and running
3. Trigger a manual sync if available
4. Wait a few minutes and check again (some IdPs batch updates)

Users not being deprovisioned

Common causes:

• Deactivation is not enabled in provisioning settings
• User was removed from IdP but not unassigned from the app

Solutions:

1. Verify “Deactivate Users” is enabled in provisioning settings
2. Ensure the user was properly unassigned from the application
3. Check provisioning logs for any errors
4. Contact BuildBetter support if the issue persists

API connection test failing

Common causes:

• Incorrect SCIM Base URL
• Invalid or expired API token
• Network/firewall blocking the connection

Solutions:

1. Verify the SCIM Base URL is exactly: https://api.buildbetter.ai/scim/v2
2. Request a new API token from BuildBetter support
3. Ensure your network allows outbound HTTPS connections to BuildBetter

Security Considerations

Authentication

• SCIM requests are authenticated using Bearer tokens
• Tokens are organization-specific and can be rotated on request
• All SCIM traffic is encrypted via TLS 1.2+

Audit Logging

All SCIM operations are logged for compliance purposes:

• User creation events
• Profile updates
• Deactivation events
• API authentication attempts

Enterprise customers can access these logs through the audit log feature.

Data Protection

• SCIM data is transmitted over encrypted connections only
• User data is stored according to BuildBetter’s data security policies
• Deactivated users can be permanently deleted upon request

Frequently Asked Questions

Can I use SCIM without SSO?

SCIM provisioning is typically paired with SAML SSO for a complete identity management solution. Contact your account representative to discuss your specific requirements.

Are groups/roles supported via SCIM?

Currently, BuildBetter manages roles and permissions within the application rather than through SCIM group provisioning. This provides flexibility for complex permission structures that may not map directly to your IdP’s group hierarchy.

How quickly are changes synced?

Most identity providers sync changes within minutes. The exact timing depends on your IdP’s provisioning schedule and configuration.

Can I provision users to multiple workspaces?

Yes. Contact BuildBetter support to configure multi-workspace provisioning based on your organizational structure.

What happens to existing users when I enable SCIM?

Existing users can be linked to your IdP through email matching. Contact BuildBetter support to coordinate the initial sync and avoid duplicate accounts.

---

For assistance with SCIM configuration or to request SCIM provisioning for your organization, contact [e-mail] or your account representative.