Configuring SCIM with Okta

You can use SCIM to onboard new employees into 15Five, update, and deactivate by syncing directly from Okta to 15Five. This saves you lots of time and ensures that data is accurate and up to date for all your employees.

What you’ll find in this article:

• Features synced
• How to set up SCIM with Okta
• Syncing
• How to disconnect
• Troubleshooting and FAQs

Features

Automatic User Provisioning is supported for the 15Five application.
This enables Okta to:

• Add new users to 15Five
• Update select fields in users’ profile information in 15Five
• Deactivate users in 15Five
• Push groups and membership to 15Five

The following provisioning features are supported:

• Push New Users. Creating a new user in Okta and assigning them to the 15Five application will create a new user in 15Five.
• Push Profile Updates. Updates to a user in Okta will be pushed to 15Five.
• Push User Deactivation. Deactivating the user or disabling the user's access to 15Five within OKTA will deactivate the user in 15Five.
• Import New Users. Users created in 15Five can be pulled into Okta and turned into new AppUser objects for matching against existing Okta users.
• Push Groups. Groups created in Okta can be pushed to 15Five. Attributes pushed include name and group members.
• Pull Groups. Groups created in 15Five can be pulled into Okta for reference within Okta.
• Delete Groups. Groups deleted or removed from the 15Five application within Okta will be deleted within 15Five.

How to set up SCIM with Okta

1. Set up SSO first if you will be using that integration.
2. Click on your Settings menu at the top right of your 15Five account and then click 'Features'.

3. Last, click on 'Integrations'.

4. Click on 'Enable' to the right of the SCIM 2.0 option.

5. Generate an Access Token.

6. Now open up your Okta instance and search for the 15Five application.
7. Enter an Application label ("15Five" is encouraged). Click Next.

8. On the next page on Sign-On Options, scroll down to ‘Advanced Sign-on Settings.‘ Enter your
15Five domain (ie. https://acme.15five.com if your subdomain is "acme") in the ‘base URL" field:

9. For SAML 2.0 customers, select the SAML 2.0 radio button option under Sign-On Methods. No relay state is required.

For all other 15Five customers, select Secure Web Authentication and select a level of authentication that makes the most sense for your company.

10. Now you will have to configure your provisioning settings. Under the provisioning tab and the Integration subtab, click ‘Enable API Integration’.

11. Under the provisioning tab and the Integration subtab, click ‘Enable API Integration’.
12. Add your API Credentials:

• For subdomain, add your 15Five subdomain. (eg. "acme")
• For API Token, add your API token found in the SCIM integrations page in 15Five.

13. Click the save button and if a save is successful then the Okta is correctly communicating with 15Five.
14. Go to the Provisioning - To App subtab and ensure the following are enabled:

• Create Users Update
• User Attributes Deactivate
• Users Sync Password (optional)
• Read through the section entitled Syncing Passwords in this guide to decide if you would like to have Okta sync passwords with 15Five.

15. Map your attributes to the corresponding fields in 15Five using the screenshots below:

16. Assign the 15Five application to employees. If you would like to delay provisioning an employee to 15Five before a certain date, see the section below about ‘Start Dates’ before assigning them to 15Five.

18. If you would like to sync groups to 15Five, go through the following steps. The group name and group members are the only group attributes synced to 15Five. Groups created in 15Five and imported into Okta cannot be deleted or changed in Okta. They must be managed in 15Five. Since groups imported from 15Five into Okta are not editable within Okta, it is suggested to create groups in Okta first and then push those groups to 15Five via the "Push Groups" button in Okta.

If you have groups already in 15Five and want to associate those groups with groups in Okta, take the following steps:

1. Create a group with the same name in Okta. For example, if a "Leadership" group exists in 15Five, create a "Leadership" group in Okta.
2. Add members to the group in Okta.
3. Push the group to 15Five.

If a group in Okta has the same name as an existing group in 15Five, pushing the group from Okta to 15Five will not create a new group. Instead, the group from Okta will overwrite the membership of the group in 15Five.

Use Start Dates to delay invite to 15Five

15Five Start Dates allows you to set a date that employees will gain access to 15Five and receive their invites. On the specified date, they will be sent an email notifying them that they can log in.

To set up Start Dates to sync to 15Five from Okta:

1. Navigate to Okta and open the configuration tabs for 15Five.
2. Under the "Provisioning Tab", click on the "Go to Profile Editor" button.
3. Click "Add Attribute" and fill in the following:

• Display Name: Start Date
• Variable Name: startDate
• External namespace: urn:ietf:params:scim:schemas:extension:15Five:2.0:User
• Scope: Check "User personal"
• Other settings can be left as is

4. Click "Save".
5. Click "Mappings" and then "Okta User to 15Five".
6. Select the field on your employees that you would like Okta to send as a Start Date value. If a Start Date value does not already exist on your Okta User, please add such an attribute as described in Okta's Help Center.
7. Click "Save Mappings". Start dates will now be sent to 15Five.

Below are some examples of what is expected in the various SCIM payloads:
POST / PUT Payload

...
"schemas": [
 "urn:ietf:params:scim:schemas:core::2.0:User",
 ... 
 "urn:ietf:params:scim:schemas:extension:15Five:2.0:User"
],
...
"urn:ietf:params:scim:schemas:extension:15Five:2.0:User": {
 "startDate": "12/15/2019"
}
...

PATCH Payload

{ 
  'schemas': ['urn:ietf:params:scim:api:messages:2.0:PatchOp'], 
  'Operations': [ 
    { 
      "op": "Replace", 
      "path": "urn:ietf:params:scim:schemas:extension:15Five:2.0:User",
      "value": "12/15/2019"
    }
  ] 
}

Syncing

Syncing through SCIM is done when a field changes, or if you complete a ‘Force Sync’ in Okta. The ‘Force Sync’ function is controlled by Okta and can sometimes take up to 40 min to complete, so if you don’t see the sync going through, make sure to wait that amount of time to confirm. You can also test a sync by updating the desired field, which will kick off a sync with the same possible delay.

You can sync groups, start dates, and the following fields from Okta to 15Five:

If you are having issues with fields not syncing correctly, email our Support Team at support@15Five.com and we can take a look!

Syncing Groups to 15Five

You can sync group name and group members from Okta to 15Five. Groups created in 15Five and imported into Okta cannot be deleted or changed in Okta. They must be managed in 15Five.

If you have groups already in 15Five and want to associate those groups with groups in Okta, take the following steps:
1. Create a group with the same name in Okta. For example, if a "Leadership" group exists in 15Five, create a "Leadership" group in Okta.
2. Add members to the group in Okta.
3. Push the group to 15Five.
If a group in Okta has the same name as an existing group in 15Five, pushing the group from Okta to 15Five will not create a new group. Instead, the group from Okta will overwrite the membership of the group in 15Five.

Group Types and group placement in 15Five
When a new group is created and synced via SCIM, that new group will appear in the 'Groups' group type in 15Five. In terms of SCIM attributes for groups and group types, the only thing 15Five will read is the group ID. After a group exists in 15Five, it will be up to the account admins to update group types as needed. Groups can be moved to a new group type (manually, via CSV, or via API) in 15Five and SCIM syncs will not override the group type change- since the group ID itself hasn't changed.

Group types within 15Five do not talk to SCIM. SCIM does not talk to 15Five about group types. SCIM only talks to 15Five from a group perspective (ie creating a group, naming a group, adding or removing members, deleting a group). The group type organization and maintenance is manually done in 15Five alone (ie creating a new group type, moving to a group type, enabling features per group type).

How to disconnect

Disconnecting the SCIM integration is a matter of unchecking the ‘Enabled’ box in your SCIM settings:

Once deactivated, the employee accounts will remain active but will no longer be automatically updated by Okta.

Troubleshooting, Support, and FAQs

Q: What is the frequency of SCIM uploads from our IdP to 15Five?
A: It’s an on-demand basis, i.e. you make a change and your IdP pushes it immediately to 15Five.

Q: Can SCIM update custom attributes in 15Five?
Yes. And if you are already familiar with adding custom attributes to your IdP, then you can add a new profile attribute within your SCIM app (15Five app) using an external name that is prefixed with custom_ and uses the external namespaceurn:ietf:params:scim:schemas:extension:15Five:2.0:User. Once set up, you can then map a value from your IdP profile into the 15Five app profile.

Q: If SCIM is on can I still add people on a one-off basis?
A: No, if SCIM is on you cannot manually add users via the 'Manage people' page or the team 15Five page. Importing new users via CSV is an option if SCIM is enabled for your organization. Please reach out to Support at support@15Five.com to get this turned on for your company.

Q: We have data currently in 15Five, if we turn on SCIM provisioning do we risk having data deleted for people with existing data?
A: No, the data will not be deleted if the email addresses are the same. You will need to reimport all of your people so that SCIM will work with users that were active in 15Five prior to SCIM being enabled. Doing this does not affect check-ins, objectives, and other user-generated content.

Q: Can I sync employee timezones via SCIM?
A: Not at this time.

Q: Should we make groups in our IdP and then push them over to 15Five? If so, how do we pass over the group admin?
A: It is advisable to pass over the groups through IdP. However, there is no way to pass over a group admin. The field for group admin will be blank in 15Five. After you set up the groups between IdP and 15Five, you can add a group admin for each group.

Q: I’m not seeing the ‘Start Date’ or ‘Location field syncing from Okta to 15Five.
A: Make sure you are on the most recent version of the 15Five application. Follow this guide to migrate.

Manager- Reviewer field is not syncing
A: There are a few potential reasons for this:

• Confirm that ‘Sync Managers’ is selected in your SCIM settings.
• Did the manager exist in 15Five before assigning them to the employee in Okta? If not, try a ‘Force Sync’ or changing their manager field to initiate another sync. You can review the system logs within Okta for details about what jobs have taken place.
• Confirm that your managerId or managerEmail attributes are mapped correctly.
  
• If you have a downstream software connecting to Okta, confirm that the id mapped from that software to Okta is an id that is passed to 15Five. We verify users by SCIM ID, then User ID, then Email, then Employee ID, stopping at any point if we hit a match. If we do not see an ID we recognize, often the reviewer field will appear blank in 15Five.
• Modify the user(s) profile in some way (perhaps by altering an unused field (State, Zip, etc)). Bulk modification of users is possible in Okta.
• Un-assign and re-assign the direct report to the 15Five application. Please note this will trigger a "Welcome Back" email to be sent to the re-assigned user(s).

Getting an "Email address already in use?" error when creating a user?
This error often occurs when a user was added to 15Five manually or prior to SCIM being enabled. See section below under ‘Updates or de-provisioning are not working for some users’ to troubleshoot.

Updates or de-provisioning are not working for some users.
This issue often occurs when a user was added to 15Five manually or prior to SCIM being enabled. To make Okta aware of these users' membership in 15Five, perform an "Import" within Okta. Under the 15Five app in Okta, find the "Import" tab, and click "Import Now". A list of 15Five users and possible associations with Okta users will be populated below. Click "Confirm Assignments" and these users will now be tracked, updated, and de-provisioned by Okta. Please make sure all of the users you would like to import from 15Five are active as inactive users will not be imported by Okta.

If users are still not imported into Okta after an "Import Now" operation, then Okta's suggested course of action is the following:
1. Perform a "Force Sync" on the "provisioning" tab's page.
2. Modify the user(s) profile in some way (perhaps by altering an unused field (State, Zip, etc)). Bulk modification of users is possible in Okta.
3. Un-assign and re-assign the user(s) to the 15Five application. Please note this will trigger a "Welcome Back" email to be sent to the re-assigned user(s).

Error: "Automatic provisioning of user to app failed: Error while reactivating user: Not Found. Errors reported by remote server: Resource None not found"
If a user has not been synced with Okta prior to their deactivation within 15Five, Okta will not know about them and will not be able to take action on them. Please re-activate (within 15Five) the user you would like to sync with Okta, and then perform an import within Okta as described in the "Updates or de-provisioning are not working for some users" section above.