Importing Roles and Teams (Okta)

Select Star's User Management API follows the SCIM standard. This document walks through integrating the User Management API with a SCIM App in Okta to pass user role and team information. In this document "SCIM app" and "app" are used interchangeably to mean the SCIM app created in Okta that represents the Select Star application.

Considerations for Using the SCIM App

1. The SCIM app should only be used to sync role or team from Okta.

2. After setting up the SCIM app, users should create users, assign roles and teams directly within Okta, as Okta will push that information into Select Star

   1. Note: after the SCIM app is set up, if a user is created in Select Star, the admin needs to re-import users from Select Star into the SCIM app

3. When deprovisioning users, users need to be removed from both Okta and Select Star, in that order.

Setup

Prerequisites

1. An Okta account that is being by your organization

2. Team or role information you'd like to pass from Okta already existing as a user attribute in Okta

Main Steps

At a high level there are three main steps to setting up the SCIM app in Okta:

1. Add the SCIM 2.0 (Header Auth) App from the Okta Application Catalogue

2. Configure the SCIM app

   1. API Integration Settings

   2. Create Attributes (Role, Team)

   3. Map Attributes

3. Import user information from Select Star into the app

Let's walk through it:

Video walkthrough for adding the Okta app to sync teams

1. Adding the SCIM 2.0 (Header Auth) App

In Okta, go to Applications and find the SCIM 2.0 (Header Auth) app in the application catalogue, and select +Add Integration

We recommend giving the application a label that includes Select Star in the name for easy identification

Under Sign-On Options, select SAML 2.0.

Important Note: Although you are selecting SAML 2.0 here, you must set up your SSO integration separately.

Click Done and the app be added. Next, configuration.

2. Configure the SCIM App

API Integration Settings

Under Provisioning, click Configure API Integration to Enable API Integration. Here you will need to enter the following:

• Base URL: https://api.production.selectstar.com/scim/v2/

• API Token: This should be the access token, formatted as Token <your access token> e.g. Token abc123

  • Follow the steps in API Token to get your token.

Click Test API Credentials to ensure the URL and Token get a response, and hit Save to move to the next settings.

Create Attributes (Role, Team)

In order to add an attribute to be passed to the SCIM app, it must be created in the Okta user profile. Note: Role and Team are not part of the SCIM spec and are optional. If either attribute is not set and mapped from Okta, when users are created in the app, default values will be used.

• For role, the standard default value is 'user' which maps to the viewer role (unless it has been otherwise configured for your organization)

• For team, the default value is null, and the user will not be assigned a team

If the values you want to map do not already exist as an attribute in the Okta user profile, you must add them now. Head to Directory > Profile Editor and select Okta.

Select +Add Attribute to add fields for the information you want to map (either role, team or both).

If you want to map role from Okta into Select Star, add role as an enumerated list of values:

If you want to map team from Okta into Select Star (and it does not already exist in your Okta user profile), add it as a string:

Next, add the fields you want to map into Select Star to the SCIM app. You can do this in the profile editor by going to Directory > Profile Editor in the left navigation, selecting the SCIM app and select + Add Attribute.

For the Team attribute, use the following:

• Data type: string

• Display name: Team

• Variable name: team

• External name: team.name

• External namespace: urn:ietf:params:scim:schemas:core:2.0:User

For the Role attribute, use the following:

• Data type: string

• Display name: Role

• Variable name: role

• External name: role

• External namespace: urn:ietf:params:scim:schemas:core:2.0:User

• Enum: define enumerated list of values

• Attribute members

  • display name: admin, value: admin

  • display name: data_manager, value: data_manager

  • display name: user, value: user

Note: you can also safely remove any attribut that will not be mapped from and into the SCIM app here.

Map Attributes

Once the attributes exist in both the Okta user profile as well as the SCIM app, you can map the two together. You need to do this in both directions, from Okta to the app, and from the app to Okta.

In the SCIM app profile editor, click Mappings

On the first tab (SCIM app to Okta), scroll down until you find the Okta user attributes for role and team. Add the corresponding application attribute names and hit Save.

Scroll up and select the second tab (Okta user to SCIM app), and add the corresponding Okta user profile attributes to map to the SCIM app attributes for team and role.

Click Save and then Apply updates now. Now your attributes are mapped between Okta and the SCIM app which will facilitate pushing them to Select Star.

The last step is to sync the data already available in Select Star.

3. Import User Information from Select Star

This step is crucial to ensure that the existing teams, roles and other information in Select Star is properly captured in Okta and won't be accidentally overwritten.

Head to Applications > Applications, select the SCIM app and go to the Import tab. Select Import Now.

Now you can view the external users found, import or map them to existing Okta users, and assign the app to them. In Okta, you can choose whether imported users are matched to an existing Okta user, creating a new Okta user, or ignored.

Once you select the users to assign, you're all set. Now, new users assigned to the SCIM App will have their mapped attributes sent to Select Star.