Bright Breaks Okta SCIM User Provisioning

This document describes Bright Breaks’ SCIM (System for Cross-domain Identity Management) support for user provisioning with Okta. Our SCIM support allows partners who use Okta to easily automate user management. The SCIM integration requires some manual setup which we will describe here, along with an overview of the user provisioning capabilities.

Prerequisites

We require some basic prerequisites before you can integrate with SCIM:

• You must first have a Bright Breaks partner account, with at least one Champion account.
• We recommend inviting your Okta administrator to Bright Breaks manually, so that they can manage the SCIM integration directly.
• You must generate a SCIM Token to enable the integration, described in the “Configuration Steps” section below.

Supported Features

We support the following capabilities through our SCIM integration:

• Create Users - Users assigned to the SCIM application, either individually or through a Group, will be provisioned with a Bright Breaks account. Attributes mapped from users’ profiles will also be synced to Bright Breaks.
• Update User Attributes - Any updates to the user profile attributes listed below will be synced accordingly.
• Deactivate Users - If a user is removed from the application, or removed from a Group assigned to the application, their account will be marked as “Blocked” in Bright Breaks and they will not be able to log in.
• Push Groups - We support Okta’s “Push Groups” feature as well, which allows us to determine which team a user belongs to.

We recommend assigning groups of users to the Bright Breaks SCIM integration. Once a Group is assigned to the Bright Breaks SCIM application, any users that are added to that group will be automatically provisioned in Bright Breaks. Users will immediately receive emails inviting them to complete their registration with Bright Breaks. We recommend testing this with a small test group first, to ensure there aren’t any major issues with the provisioning process.

Additionally, users who are marked as “Deactivated” in Okta, or are removed from the assigned Group(s) will be marked as “Blocked” in Bright Breaks, and they will be unable to access their Bright Breaks account.

In addition to the email address associated with each user’s account, we recommend mapping the following attributes. These attributes allow us to offer additional features in Bright Breaks such as activity breakdowns per user segment, with more features and capabilities planned in the future.

Attributes to map:

• userName - A unique identifier for the user
• givenName - The user’s first name
• familyName - The user’s last name
• email - The user’s primary email address
• title - The user’s job title
• locality - The user’s locality, typically the name of a city
• region - The user’s region, typically the name of a state or province
• country - The user’s country, as a two-character country code
• timezone - The user’s timezone in IANA “tz” format, for example, “America/New_York”
• organization - The user’s organization
• division - The user’s division
• department - The user’s department
• managerValue - The user’s manager’s email address

We recommend mapping all these attributes in order to enable additional features in Bright Breaks.

The underlined attributes must be stable across users who share those attributes. For example, if two users belong to the Engineering department, both their attributes should be “Engineering”, not variants like “Eng”.

We also support the “Push Groups” capability, which will allow us to determine what group/team a user belongs to, for added functionality in Bright Breaks. We recommend pushing all groups that a user might belong to.

There are capabilities in Okta that we do not intend to support. We will not support provisioning “To Okta”. Similarly, we will not support “Import” from Bright Breaks.

Configuration Steps

Generating a SCIM Token

The SCIM setup starts in the Bright Breaks web application. Champions will be able to access a page that allows them to create a “SCIM Token” that will then be used in Okta. We recommend champions invite their Okta admin to Bright Breaks, so that we can give them direct access to this page.

The SCIM Token page will be available at:

https://brightbreaks.com/champion/<partner-route>/scim-token

Where “<partner-route>” is the route specific to your company’s account.

The SCIM Token page, before a token is created

This page allows you to create a SCIM Token that will be used to integrate Bright Breaks with Okta. Clicking the “Create SCIM Token” button will generate a unique token. This token should be kept secret and safe, as it provides access to any user data you sync to Bright Breaks. For security purposes, the token will only be shown once, and can only be revoked and re-generated if needed. Copy this SCIM Token and store it securely. It will be used in the following steps.

The SCIM Token page, with a generated token

Okta SCIM Application Setup

The following steps will take place in your Okta administration console.

In Okta’s “Applications” section, click on “Browse App Catalog” and search for “Bright Breaks”. Choose this App, and click on “Add Integration”. You can also find the application integration at this link: https://www.okta.com/integrations/bright-breaks/ 

Choose the “Bright Breaks” app in the Integration Catalog

Proceed through the setup steps. Once the application is created, go to the application’s “Provisioning” section and click on “Configure API Integration”

Configure the API Integration in the Provisioning section

Enable the “API integration” checkbox, and fill out the API configuration.

The “Base URL” will be:

https://api.brightbreaks.com/scim/<partner-route>

Where “<partner-route>” is the route that is specific to your company.

The “API Token” is the SCIM Token copied from the Bright Breaks SCIM Token page mentioned in the instructions above. Click the “Test API Credentials” button to verify the configuration. Finally, click the “Save” button before continuing to the next step.

API Integration configuration

Once the API Integration is configured, enable the “To App” provisioning settings. You must enable the “Create Users”, “Update User Attributes” and the “Deactivate Users” options. Be sure to save the “To App” settings before continuing.

Enable the “To App” settings.

You may now assign Groups or People for provisioning. We recommend provisioning with Groups, to make full use of the automation capabilities. You may configure the attribute mappings as you wish, depending on your particular organization’s configuration, though the defaults should suffice.

The provisioning will occur immediately after you perform the assignment. Any errors that occur should be displayed in the Okta administration console.

You can verify a successful provisioning by viewing the “Members” section of Bright Breaks’ Champion Portal:

https://brightbreaks.com/champion/<partner-route>/members

Chose “Assign to Groups” in the “Assignment” section

Verify that the users from the assigned groups were synced correctly by viewing the “Members” section of the Bright Breaks Champion Portal. You should also see the mapped attributes for each user. The provisioned members will have the status “Invited” until they log in to Bright Breaks

Use the “Push Groups” section to push all the users’ relevant groups.

You may push groups by name or by rule.

Pushed groups are not currently displayed in Bright Breaks, but the push should succeed with an “Active” status.