Skip to main content

SCIM Integration for Enterprise Organizations

note

SCIM is only available with an Enterprise plan and requires Single Sign-On (SSO) to be enabled. Currently, GrowthBook only supports Okta as the identity provider.

SCIM, or System for Cross-domain Identity Management, is the standard for managing users and groups across multiple applications. With SCIM, you can automate the provisioning and deprovisioning of users in your GrowthBook account through your identity provider.

GrowthBook's SCIM integration currently offers the following features:

  • User provisioning
  • User deprovisioning
  • Group Push

When a user is provisioned, they are added to your GrowthBook organization with your organization's default role. After provisioning, admin users can adjust their roles and permissions via the GrowthBook application as needed. It's important to note that if a user is provisioned through SCIM, they can only be deprovisioned through your identity provider.

GrowthBook does support the ability to optionally define a role when provioning a user. Project-level permissions are not supported when provisioning a user via SCIM. That must be done via the GrowthBook application.

When a group is added to "Push Groups" in your Okta SCIM application, groups and their members will be synced with GrowthBook via a corresponding Team. Please note that only members that have been provisioned into the GrowthBook app will be added to the Team in GrowthBook. For example, if you have a push group with members A, B, and C and only A and B are assigned to GrowthBook on the "Assignments" tab, the corresponding team on GrowthBook will only include members A and B. Just like how user provisioning works, new Teams will be set up with your organization's default role. You'll need to adjust the permissions for the Team in GrowthBook. Group removal or membership changes will need to be done through your identity provider.

note

We are actively working on adding support for additional identity providers.

Configuring SCIM Integration​

Okta Setup​

  1. Verify that your GrowthBook organization is on an enterprise plan with SSO enabled.

  2. Log in to your Okta account and go to the Applications page. Select "Browse App Catalog," then search for "SCIM 2.0 Test App (OAuth Bearer Token)." Click "Add Integration" to add the app to your Okta account.

  1. Once the app is added, you can change its name, for example, to "GrowthBook SCIM." Click "Next."

  1. On the next page, you don't need to modify any settings. Simply click "Done."

  2. With the application created, click on the "Provisioning" tab and select "Configure API Integration."

  1. Choose to enable API Integration, and input your credentials. Contact your account representative to obtain the SCIM 2.0 Base URL. You can acquire your OAuth Bearer Token by creating a new Secret API Key with an Admin role. To do this, go to your GrowthBook account, and in the left navigation, select "Settings → API Keys." We recommend creating a dedicated API key exclusively for your SCIM integration.

  2. After adding your credentials, click "Test API Credentials" to ensure they are valid. If they pass the test, click "Save."

  1. Next, click on the "To App" tab and select "Edit" to enable "Create Users" and "Deactivate Users." Once enabled, click "Save."

  1. Congratulations! Your application is now set up. You can navigate to the "Assignments" tab and assign people to GrowthBook and to the "Push Groups" tab to sync groups with GrowthBook Teams.

How to define user role when provisioning​

  1. First, ensure that you've followed the general setup instructions above.

  2. In Okta, navigate to the Application you created for GrowthBook SCIM, and click on the "Provisioning" tab, and scroll to the "Attribute Mappings" section, before clicking "Go to Profile Editor".

  3. Then, you'll click "Add Attribute" to create a new attribute. with the following details.

  • Data type: string
  • Display name: GrowthBook Role
  • Variable name: growthbookRole
  • External name: growthbookRole
  • External namespace: urn:ietf:params:scim:schemas:core:2.0:User
  • Check the box to define an enumerated list of values
  • Here, you need to add the following enum Options
    • Display name: Read only
    • Value: readonly
    • Display name: Collaborator
    • Value: collaborator
    • Display name: Engineer
    • Value: engineer
    • Display name: Analyst
    • Value: analyst
    • Display name: Experimenter
    • Value: experimenter
    • Display name: Admin
    • Value: admin

note

It's important each of these values are entered exactly as shown above, including capitalization. If there is a descrepancy, the user's role will fall back to your organizations default role.

  1. Once complete, when you provision a user, you can select their role from the dropdown, and that will be applied to the user in GrowthBook. If you're not sure which role a user should have, you can view GrowthBook role permissions here.

Frequently Asked Questions​

What features are supported with SCIM?

Currently, GrowthBook supports user provisioning and deprovisioning, and group pushing.

What identity providers are supported?

At present, GrowthBook only supports Okta, but we are actively working on adding support for additional identity providers.

What happens if I deprovision a user in my identity provider?

If a user is deprovisioned in your identity provider, they will be removed from GrowthBook. If they are re-provisioned, they will be added back to GrowthBook, and their role will reset to the organization's default role.

All the users from my group aren't being synced with my GrowthBook team. What's happening?

If you notice that some users that you expect to be in your GrowthBook team from your identity provider are not being added in GrowthBook, double check that those users are assigned to the GrowthBook SCIM application in your identity provider. Only users that are both assigned and withing the group will be synced to the corresponding team.

What if I already have users in GrowthBook?

Existing users in GrowthBook will not be affected by SCIM. You can continue to manage them through the GrowthBook application as usual. If you wish to transition them to be managed by your identity provider, you can provision them through your identity provider. As long as the email matches, the existing GrowthBook user will be converted to be managed by your identity provider.

Does GrowthBook follow SCIM 1.1 or 2.0 Protocol?

GrowthBook follows the SCIM 2.0 protocol.

What happens if I provision a user with a role that doesn't exist?

GrowthBook will fallback to your organization's default role.

Can I provision a user with project-specific permissions?

No, at this time, you can only provision a user's global role. Project-specific permissions must be managed through the GrowthBook application.

Can I change a user's global role after they've been provisioned?

Yes, you can change a user's global role through the GrowthBook application or via Okta. Please note that if you change a user's global role through the GrowthBook Application, it will then be out-of-date in Okta. If you then update the user in Okta, it will update the user's global role.

I'm changing the user's role in Okta, but it's not changing in GrowthBook

In order for the user's role to be updated in GrowthBook, you must update your Application provisioning to support "updates". Please note that the only property GrowthBook supports updating is the growthBookRole.