Skip to main content
Applies to:
  • Plan - Enterprise
  • Deployment - Braintrust-hosted
  • Use case - Set up SSO (Okta/SAML) and SCIM provisioning so multiple Braintrust organizations that share one email domain are segregated correctly and users get the intended org and permission group memberships

​
Summary

Use one Okta SSO app with SCIM and distinct org groups to manage membership across Braintrust organizations that share an email domain.

​
What is happening

SCIM mappings control organization membership. Users with access to multiple organizations still open their last visited organization after login, even after mappings are configured.

​
Fix or suggestion

​
Option 1 (recommended): Single Okta app with SCIM and group mapping

Have Braintrust support connect SCIM to every intended organization before configuring Okta.
  1. Configure SCIM provisioning on the primary Okta SSO app using the supplied SCIM endpoint URL and bearer token.
  2. In Okta, create one SCIM group per Braintrust organization. Example group names: SSO-Braintrust_Prod_US, SSO-Braintrust_Prod_CA, SSO-Braintrust_NonProd
  3. If an Okta group assigns app access, create a separate group for SCIM group push. Okta does not allow the same group to be used for both app assignment and SCIM Group Push.
  4. Ensure every member of an org SCIM group is also assigned to the Okta app.
  5. In Okta, add each org group under Push Groups, then select Push now.
  6. In each Braintrust organization, go to Settings > Permissions > SCIM, reload the page, then save the Organization membership mapping for the corresponding pushed SCIM group.
  7. To manage permission groups via SCIM, turn on Manage permission groups via SCIM, then use Add mapping to pair each Braintrust permission group with a SCIM group and save. Unmapped permission groups retain their existing memberships. Alternatively, leave Manage permission groups via SCIM off and select Default group for newly provisioned members. This does not update existing members’ permission groups.
Enabling SCIM updates makes your identity provider authoritative for organization membership. On the next synchronization, existing members who are missing from the mapped organization membership group are removed from the organization, and their API keys for that organization are deleted.
  1. For each organization, turn on Enable SCIM updates, review the membership checks, resolve or acknowledge the results, and confirm.
  2. In Okta, select Push now again for each mapped group to resynchronize memberships.

​
Option 2: Alternative when domains are unique

If each Braintrust organization uses its own email domain, you may keep separate Okta SSO apps. Use a separate application dedicated to SCIM.

​
How to confirm it worked

  • Sign in with a test user who is a member of a single org SCIM group. Confirm the user lands in the expected organization.
  • Sign in with a test user who is a member of multiple org SCIM groups. Confirm the user can switch organizations with the org selector and that sign-in opens their last visited org.

​
Notes

  • Use a consistent naming convention for groups — for example, prefix each group name with the organization it controls: SCIM-OrgA, SCIM-OrgB, SCIM-OrgC.