Skip to content

Okta - SAML

This feature is only available on the Pro and Enterprise plans.

SCIM for Okta supports the following SCIM resources:

  • Users (mapped directly to BSR Users)
  • Groups (not directly represented in the BSR, but can be added to BSR Organizations by name to manage Organization membership)

The steps below must be carried out by users with administrative privileges in your Okta account.

Prerequisites

  • Setup (Pro | Enterprise) needs to be complete.
  • You need to know your private BSR server domain (for example, example.buf.dev or buf.example.com) for the steps below.

Enable SCIM provisioning

  1. Sign in to your Okta organization.
  2. Navigate to Applications > Applications and click on your BSR application.
  3. Navigate to the General tab and click Edit in the App Settings pane.
  4. Check SCIM and click Save.
  5. Okta may take some time to propagate the change. When it's enabled, you should see a new Provisioning tab in your application.

Configure the SCIM connector

  1. In your Okta application, navigate to the Provisioning tab.
  2. Under the SCIM Connection pane, click Edit and enter the following information:
    • SCIM connector base URL: https://buf.example.com/scim/v2
    • Unique identifier field for users: userName
    • Supported provisioning actions: Check off the following:
      • Push New Users
      • Push Profile Updates
    • If you would like to push groups, also check the following:
      • Import New Users and Profile Updates
      • Push Groups
      • Import Groups
    • Authentication Mode: HTTP Header
    • Authorization: enter the SCIM token you created earlier

  3. Click Test Connector Configuration. You should see the following screen (an x will show for those you have not checked—this is expected):

    okta scim connector success

  4. Click Save.

  5. Click the To App side tab.
  6. Click Edit and enable the following options:
    • Create Users
    • Update User Attributes
    • Deactivate Users
  7. Click Save.

  8. In the Attribute Mappings section below, ensure the following attribute mappings are set. Unmap all other attributes.

    Attribute Value
    userName Configured in Sign On settings (should be mapped to Email)
    givenName user.firstName
    familyName user.lastName
    email user.email
    emailType (user.email != null && user.email != "") ? 'work' : ''
    (i.e., specified only if user.email is not null or empty)

Provision users

If you had previously assigned this Okta application to users before enabling SCIM, you need to provision those existing users to the BSR. Okta will try to match the users to existing users within the BSR, and this should succeed without error. Follow the steps below to do this.

  1. In your Okta application, navigate to the Assignments tab.
  2. You should see warnings for all the existing users. Click Provision User, click OK to the confirmation prompt.
  3. You will see a toast indicating that the provisioning job was queued. You can navigate to Dashboard > Tasks (https://yourog.okta.com/admin/tasks) to view any background tasks that Okta is running, as well as any errors that come up.

If you encounter any errors provisioning users, please see the relevant part of the FAQ. If you are unable to resolve those issues, please contact Support or your Buf representative.

Push groups

The BSR will use any IdP-provided groups in combination with automated organization provisioning to automatically manage users' memberships to BSR Organizations.

  1. In your Okta application, navigate to the Push Groups tab.

  2. Click Refresh App Groups to pull the latest groups from the BSR. You may have to wait a few moments for it to complete.

  3. Under Push Groups, chose the relevant group selection criteria. Once a group has been selected, you will see one of two options:

    • If the BSR already knows about the group, Okta indicates that a match was found.
    • If the BSR doesn't know about the group, Okta allows you to either link to another group in the BSR, or create a new one. In most cases, you will want to create a new group.

  4. Click Save.

  5. Okta will now attempt a Group Push. If an error is encountered, it will be shown directly next to the group, like below. If this happens, contact Support or your Buf representative to resolve the error and try again.

    okta scim attribute mappings