Configuring SCIM with Okta

This guide provides the steps required to configure provisioning for 15Five, and includes the following sections:

• Features
• Prerequisites
• Configuration Steps
• Troubleshooting Tips

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.

Prerequisites

Make sure you have configured the General Settings and any Sign-On Options for the 15Five app.

Before you configure provisioning in Okta...

1. Click on 'Settings' from the left navigation.

2. Then click on 'Features' to expand the feature settings.

3. Last, click on 'Integrations'.

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

5. Generate an Access Token.

Configuration Steps

Configure your App Settings:

• Enter an Application label ("15Five" is encouraged).

• On the next page on Sign-On Options, scroll down to ADVANCED SIGN-ON SETTINGS and Base URL. Please enter your 15Five domain (ie. https://acme.15five.com if your subdomain is "acme").

For SAML 2.0 enabled 15Five customers, simply 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. 

Configure your Provisioning settings as follows:

• Under the provisioning tab and the Integration subtab, click "Enable API Integration".
• 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.
    
    • NOTE: The *Public API* key is 32 characters long. The *SCIM* key is 30 characters long.
• Click the save button and if a save is successful then the Okta is correctly communicating with 15Five.

Under the Provisioning tab and under the "To App" subtab:

• Ensure the following features are checked:
  • 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.

Please note that you may need to do a one time import of users from 15Five into Okta so that Okta is made aware of the users already in 15Five. Please see the "Or was SCIM setup after users were already in 15Five?" section below for more details.

You can now assign people to the app (if needed) and finish the application setup.

Syncing Passwords

Okta can be configured to sync passwords with 15Five. This sync direction is from Okta to 15Five. That is, passwords are only ever sent from Okta to 15Five for a user; never from 15Five to Okta.

If Sync Password is enabled, the password sent from Okta to 15Five must be randomly generated. For added security, check the Generate a new random password whenever the user's Okta password changes checkbox next to Password Cycle.

If your company uses SSO with 15Five, do not enable Sync Password. User authentication will be determined from the SAML setup associated with 15Five.

Emails

When giving 15Five access to an Okta user for the first time, a new user in 15Five will be created. If SSO is enabled for that user’s company in 15Five, that user will be sent a welcome email with a link to the SSO page at 15Five. If SSO is not enabled, that user will be sent a link to sign in and set their password.

When updating an Okta user’s password, that user’s 15Five password may be updated (depending on whether “Generate a new random password whenever the user’s Okta password changes” was checked or not). If SSO is enabled for the user’s company in 15Five, no password changes will occur for the user within 15Five. If SSO is not enabled in 15Five and Sync Password is enabled in Okta, then a user will receive an email with a link to reset their password in 15Five.

Attribute Mappings

Below is a list of the attribute mappings between Okta and 15Five. 

Groups

Please note that these are the only Group attributes that are updatable via the Okta integration:

• Group Name
• Group Members

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.

Group types

When a new group gets created and synced over via SCIM, that new group will go into the 'Groups' group type. In terms of attributes, the only thing 15Five will read from SCIM in regards to groups and group types is the group ID. After a group is appearing in 15Five, it will be up to the account admins to reorganize this group(s) to other 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 because the group ID itself hasn't changed.

The jist: 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). 

Start Dates

Interested in having your users enter 15Five for the first time on a specific day? With 15Five Start Dates, you can send a date before which your users will not be able to log in to 15Five nor will they receive notifications. One the specified date, they will be sent an email notifying them that they can log in.

To send Start Dates to 15Five, follow these steps:

• Navigate to Okta and open the configuration tabs for 15Five.
• Under the "Provisioning Tab", click on the "Go to Profile Editor" button.
• 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
• Click "Save".
• Click "Mappings" and then "Okta User to 15Five".
• 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 here: https://support.okta.com/help/s/article/How-to-create-a-new-custom-attribute-in-Okta
• Click "Save Mappings". Start dates will now be sent to 15Five.

Please note that you must add the start date to the user before assigning the user to 15Five for the first time. If a user is assigned to 15Five for the first time without a start date, it is assumed that the user should start immediately and a welcome email will be sent immediately.

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"
    }
  ] 
}

Troubleshooting, Support, and FAQs

Fields like Start Date and location not syncing?

Occasionally 15Five makes changes to its Okta integration. These changes aim to provide a better overall experience to 15Five customers however newly published fields may not update properly until the new app integration is used. 

To take advantage of the new integration and have these field sync appropriately, please follow this guide:

• https://success.15five.com/hc/en-us/articles/360041759471-Migrating-To-A-New-15Five-App-Version-in-Okta

Location Field is Syncing as ", ,"

If the location field for a user is syncing as ", ,", this is because the city, state, and country-code are not defined in Okta for that user. Update those fields in Okta to correct this issue.

Manager/Reviewer not syncing? 

Make sure that the manager exists within 15Five prior to provisioning. 15Five will ignore any manager assignments that include managers not present in 15Five. If a reporter was provisioned before a reviewer, clicking "Force Sync" under the provisioning tab may resolve the issue. "Force Sync" doesn't always trigger immediate action within Okta and you may need to wait for several minutes for the sync job to start. You can review the system logs within Okta for details about what jobs have taken place.

Okta sends the manager information present in the managerId field for a given user. The information in the field can be an email address for the manager or a 15Five ID for the user. Make sure this field is populated.

Finally, ensure that Sync Managers is enabled within 15Five's SCIM settings:
https://my.15five.com/scim/settings/

 

 

Please note, for consistency reasons, manager updates are not performed during active Best-Self Reviews. 

Changing a username?

15Five depends on the uniqueness of a user’s email address. Therefore, provisioning will fail if a user’s userName is updated but their email address is not. Ensure these two values (userName and email) are the same and retry the provision if it has failed. 

Updates or de-provisioning not working for some users? 

This issue often occurs when a user was added to 15Five manually or prior to SCIM being enabled. Please see the "Users added to 15Five manually?" below.

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. Please see the "Users added to 15Five manually?" below.

Users added to 15Five manually? Or was SCIM setup after users were already in 15Five? 

Users added to 15Five manually or before SCIM was enabled for the 15Five account may not be tracked by Okta. 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. 

Users still not syncing as expected?

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).

Seeing this 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 "Users added to 15Five manually? " section above.  

 

Older Groups

If you added an instance of 15Five before August 27, 2018, you must re-authenticate with 15Five to take advantage of this update. Please follow the steps below to re-authenticate:

1. Go to the Provisioning tab of your 15Five application within Okta.
2. Go to the API Integration menu.
3. Click Edit and then click the Test API Credentials button. Check that your credentials were verified successfully.
4. Done! You can now use the Group Push functionality of 15Five.

Q: My user has a SCIM ID. Does that mean they were provisioned via SCIM?
A: No. All users are given a SCIM ID upon account creation regardless of whether or not they were provisioned via SCIM. Assigning these IDs helps 15Five stay consistent and organized. It's the value which is used to look up the user when a SCIM call comes in of the form /scim/v2/Users/<scim id>.

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: 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, your Implementation Specialist, or your Customer Success Manager to support you with this.

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: 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.

This integration is built and supported by 15Five and our Support Team. Contact the 15Five Support Team at support@15five.com if any issues arise. Thanks!