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 Generate SCIM credentials to open the SCIM credentials dialog box.

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

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

   Copy and save both. You need them for SCIM provisioning.

   For Okta, check out our SCIM provisioning guide.

Managing workspace roles via SCIM

By default, all SCIM-provisioned users receive the Viewer role. If your IdP supports the SCIM roles attribute, you can automate Workspace role assignment so that users are provisioned with the correct role 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.

How role assignment works

Each role entry's value field uses the format workspace:<role_name>. 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" }
  ]
}

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 workspace role. 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.