Configuring SCIM

The System for Cross-domain Identity Management (SCIM) specification is designed to make managing user identities in cloud-based applications and services easier.

On Bitrise, SCIM provisioning is supported for Okta and Microsoft Entra ID.

SCIM provisioning requires a verified domain, and SCIM credentials: a SCIM base URL and an authentication token. The process of configuring these on Bitrise is the same for both Okta and Entra ID.

1. Log in to Bitrise and hover over the left navigation bar.

2. Make sure you have the right workspace selected in the Workspace menu.

3. Select Settings.

4. On the left, select Single sign-on.

5. Set up a verified domain.

6. Select the SCIM tab.

7. In the SCIM credentials section, click Connect with IdP to open the Connect with IdP dialog.

8. Save your SCIM credentials. In the dialog, you will see:

   • Your SCIM base URL.
   • Your SCIM authentication token.

   Copy and save both. You need them for SCIM provisioning. Once you've pasted them into your identity provider, select the checkbox confirming this, and click Done.

   For Okta, check out our SCIM provisioning guide.

Managing workspace and product roles via SCIM

By default, all SCIM-provisioned users receive the Viewer role and no product access. If your IdP supports the SCIM roles attribute, you can automate Workspace and product role assignment so that users are provisioned with the correct access from the start.

Available workspace roles

SCIM value	Workspace role	Description
workspace:workspace_viewer	Viewer	Default role for new members. Can view Workspace resources but cannot create apps or projects.
workspace:workspace_contributor	Contributor	Can create new apps and projects. Cannot modify Workspace settings or manage members.
workspace:workspace_manager	Manager	Can modify Workspace settings, manage members, and manage integrations and infrastructure.

For a detailed breakdown of permissions, see Roles and permissions in Workspaces.

Available product roles

SCIM value	Product role	Description
rde:rde_admin	RDE User	Can create and manage Remote Dev Environment sessions in the Workspace.

Project-level Bitrise CI and Release Management roles can't be assigned through SCIM. Set those up on the Collaboration page instead: Roles and permissions in Workspaces.

How role assignment works

Each role entry's value field uses the format <family>:<role_name>, where the family is either workspace or rde. Configure your IdP to include the roles attribute in SCIM requests using one of the following formats.

User creation and full update (POST and PUT):

Include roles as a top-level attribute in the request body:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "[email protected]",
  "roles": [
    { "value": "workspace:workspace_manager" },
    { "value": "rde:rde_admin" }
  ]
}

Partial update (PATCH, roles in value object):

Some IdPs, such as Okta, send roles nested inside the value object without an explicit path:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "value": {
        "roles": [
          { "value": "workspace:workspace_contributor" }
        ]
      }
    }
  ]
}

Partial update (PATCH, explicit path):

Other IdPs, such as Microsoft Entra ID, use an explicit path field. The type field is optional and ignored by Bitrise:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "roles",
      "value": [
        { "value": "workspace:workspace_manager" }
      ]
    }
  ]
}

Bitrise handles all three formats automatically.

important

If the roles attribute is present in a SCIM request, Bitrise treats it as the complete role assignment and replaces the user's current roles. This applies to every family, not just the ones you send: a request that lists only a workspace: role removes the user's RDE access, and a request that lists only rde:rde_admin reverts the user's workspace role to Viewer. Send every role the user should keep.

If roles is absent from the request entirely, existing role assignments are left untouched. An empty roles array reverts the user to the default Viewer role and removes their product access.