SCIM

SCIM (System for Cross-domain Identity Management) is a standard for provisioning and deprovisioning users and groups in an organization. IdPs (identity providers) like Okta, OneLogin, and Azure Active Directory support provisioning users through SCIM.

Sourcegraph supports SCIM 2.0 for provisioning and de-provisioning users.

How to use

To use SCIM, you must have an existing IdP configured as an auth provider on your Sourcegraph instance. For authenticating SCIM requests, we currently support Bearer token authentication. We have a guide for Okta setup below.

To configure:

  1. Generate a random alphanumeric bearer token of maximum 255 characters. To do this in a terminal, run:

    openssl rand -base64 342 | tr -dc 'a-zA-Z0-9' | cut -c -255

    (This command generates a random base64 string with more characters than required (342 characters) and then filters out non-alphanumeric characters. Finally, it trims the output to 255 characters. The reason we generate a longer string is to account for the fact that the base64 encoding has non-alphanumeric characters, which are removed by the tr command.)

  2. Add the following line to your site configuration:

    "scim.authToken": "{your token}"

  3. If you use Microsoft Azure AD, add the following setting to your site config:

    "scim.identityProvider": "Azure AD"

  4. Set up your IdP to use our SCIM API. The API is at

    https://sourcegraph.company.com/.api/scim/v2

Configuring SCIM for Okta

To set up user provisioning in Okta, you must first set up a new app integration of the "SAML 2.0" type, then configure it to use SCIM. Here are the steps to do this:

  1. Follow our SAML guide to set up a new app integration with SAML, then open the integration you just created.
    • If you already have the integration, just open your existing app integration.
  2. Go to the "General" tab and click "Edit" in the "App Settings" section.
  3. Set "Provisioning" to "SCIM". This creates a new tab called "Provisioning".
  4. Go to the "Provisioning" tab, and click "Edit"
  5. Set "SCIM connector base URL" to {yourSourcegraphUrl}/.api/scim/v2
  6. Set "Unique identifier field for users" to userName
  7. Check the first three items in Supported provisioning actions: "Import New Users and Profile Updates", "Push New Users", and "Push Profile Updates".
  8. Set "Authentication mode" to "HTTP Header"
  9. Under "HTTP Header", paste the same alphanumeric bearer token you used in your site config.
  10. Click "Test Connection Configuration" (first four items should be green—the user-related ones), then "Save".
  11. Switch to "Provisioning" → "To App" and click "Edit". Enable "Create Users", "Update User Attributes" and "Deactivate Users".

Features and limitations

User attributes

The User endpoint only synchronizes attributes needed to create a Sourcegraph account.

We sync the following attributes:

  • preferred username
  • name
  • email addresses

REST methods

We support REST API calls for:

  • Creating users (POST)
  • Updating users (PATCH)
  • Replacing users (PUT)
  • Deleting users (DELETE)
  • Listing users (GET)
  • Getting users (GET)

Feature support

We support the following SCIM 2.0 features:

  • ✅ Updating users (PATCH)
  • ✅ Pagination for listing users
  • ✅ Filtering for listing users

Limitations

  • ❌ Bulk operations – need to add users one by one
  • ❌ Sorting – when listing users
  • ❌ Entity tags (ETags)
  • ❌ Multi-tenancy – you can only have 1 SCIM client configured at a time.
  • ❌ Tests with many IdPs – we’ve only validated the endpoint with Okta and Azure AD.