Manage users with Okta SCIM
Last Update: Sep 2024 • Est. Read Time: 7 MINOkta is a single sign-on (SSO) service that offers enterprise-grade identity management. In this article, you'll learn how to set up Okta with the SCIM (System for Cross-domain Identity Management) open standard for user provisioning with Kustomer.
Who can access this feature? | |
User types | Admins can access these settings. |
In this article
- Prerequisites
- Create an API key in Kustomer
- Configure provisioning in Okta
- How to use provisioning
- Troubleshooting
Prerequisites
Before you can set up Okta SCIM provisioning, the Okta app or another compatible SAML app should be installed. The instructions in this guide are tailored for an Okta SAML app installed following the steps in our earlier article SAML authentication and SSO login.
Your Okta account will also need to have purchased the Okta Lifecycle Management or Okta Advanced Lifecycle Management plan to use SCIM provisioning.
To set up the API key, you must have Administrator or Org Owner permissions.
Note: We strongly recommend that you turn on Technical Support Access in Settings > Security > Kustomer Access before you begin setup. This would allow our team to access your organization to help if you get locked out of your Kustomer account or if any mistakes occur during setup.
Once you're up and running with Okta SCIM and no longer need active technical assistance, you can return to the Security Settings to turn off Technical Support Access.
Create an API key in Kustomer
Start in Kustomer. You'll need Administrator or Org Owner access to create an API key.
To create an API key for Okta:
- In Kustomer, go to Settings > Security > API Keys.
- Select Add API Key.
- Fill in the fields as follows:
- Name: Okta SCIM Key
- Roles: org.admin, org.user, org.hooks, org.permission, org.tracking
- Expires: No Expiration
- CIDR IP Restriction: (leave blank)
- Select Create.
- A window will appear with your API key. Leave this Kustomer window for the time being, since you will need to copy this API key to Okta in the next step. For security purposes, do not save this API key elsewhere.
Configure provisioning in Okta
After creating the API key, you can turn on SCIM provisioning on the Okta site. Leave Kustomer open, and open the Okta site in another browser tab so you can copy your API key over.
To set up SCIM provisioning:
- In Okta, go to your Kustomer app.
- Go to General > App Settings > Edit.
- Under Provisioning, select the SCIM option, then press Save.
- The page will refresh, and a new tab named Provisioning will appear. Open the Provisioning tab and select Edit.
- Fill in the fields as follows:
- SCIM connector base URL:
https://[orgname].api.kustomerapp.com/v1/scim/v2/
- Unique identifier field for users:
email
- Authentication Mode: HTTP Header
- SCIM connector base URL:
- Check the following boxes:
Option Note Import New users and Profile Updates We do not recommend importing users as part of this process, but selecting this is required to check the "Import Groups" box. Push New Users Push Profile Updates Push Groups By default, Name and Display name are inherited and overwritten by the Okta group name. To change this, go to Group Push Settings in Okta and turn the Rename Groups setting On. This will preserve the group names found in your Kustomer organization.
Note: Turning this setting on will also overwrite the Display name with what is in Name.Import Groups Team names cannot contain an emoji when passing them to Okta. If an emoji is included, the Import Group function will fail. - In the HTTP Header: Authorization field, paste the API key you created on the Kustomer site in the previous step.
- Select Test Connector Configuration.
- If the test was successful, press Save.
Create a User Type attribute in Okta
Next, you'll start provisioning users in the Okta admin settings. The basic setup will allow you to provision users through managing permission sets in Teams. You'll begin by creating a User Type string attribute in Okta.
To create the User Type attribute:
- After saving the SCIM Connection, refresh the Okta page. Under the Provisioning tab, a sidebar option named To App should now appear. Select it.
- Select the Edit button.
- Check the Create Users box, then press Save.
- In the Okta settings, go to Directory > Profile Editor.
- Select Kustomer User, then select Add Attribute.
- Fill in the fields as follows:
- Data type: string
- Display name: User Type (make note of the space in Display Name only)
- Variable name: UserType
- External name: UserType
- External namespace:
urn:ietf:params:scim:schemas:core:2.0:User
- Enum: check the box Define enumerated list of values
- Set the following values:
Display name Value Full-Time User user Collaborator limited Seasonal seasonal
- Set the following values:
- When you're finished, Save the attribute.
Set a user's display name in Okta
You can set up an additional attribute in Okta for a user's Display Name, which is the name both customers and internal team members see. For example, if a user's full name is Mark Smith, their display name can be set to Mark.
To create a display name attribute:
- In the Okta settings, select Kustomer User again (if it's still not selected from the previous section), and then select Add Attribute.
- Fill in the fields as follows:
- Data type: string
- Display name: Display Name (make note of the space in this field only)
- Variable name: DisplayName
- External name: DisplayName
- External namespace:
urn:ietf:params:scim:schemas:core:2.0:User
- Enum: check the box Define enumerated list of values
- When you are finished, Save the attribute.
Assign permission sets to individual users
Next, you can set up an additional attribute in Okta for Permission Sets. Rather than just managing permission sets in Teams, you can manage provisioning through individual user permission sets. Alternatively, you can assign permission sets to all members of a group.
To set up provisioning for permission sets in Okta:
- In the Okta Settings, select Kustomer User again (if it's not still selected from the previous section), and select Add Attribute again.
- Fill in the fields as follows:
- Data type: string array
- Display name: Permission Sets (make note of the space in Display Name only)
- Variable name: PermissionSets
- External name: PermissionSets
- External namespace:
urn:ietf:params:scim:schemas:core:2.0:User
- Enum: check the box Define enumerated list of values
- For the Attribute Members list, you must add the permission sets from Kustomer with their IDs. When adding new permission sets in Kustomer, they will also need to be updated here. For more information on finding Permission Set IDs, see the next section Find IDs for Permission Sets.
Display name Value Content Admin <id from Kustomer> Collaborator <id from Kustomer> Admin <id from Kustomer> User <id from Kustomer> Manager <id from Kustomer> Owner <id from Kustomer> (Any additional Custom Permission Sets, as desired) <id from Kustomer>
- For the Attribute Members list, you must add the permission sets from Kustomer with their IDs. When adding new permission sets in Kustomer, they will also need to be updated here. For more information on finding Permission Set IDs, see the next section Find IDs for Permission Sets.
- Scope: check the box User personal
- When you're finished, Save the attribute.
Find IDs for permission sets
To find the ID for a permission set, use the Kustomer API, or locate the ID string using the Kustomer interface.
To find a permission set ID in Kustomer:
- In Kustomer, go to Settings > Users > Permission Sets.
- Locate the Permission Set, then select the Sharingicon.
- Refer to the current URL in the browser address bar. The ID is the alphanumeric string between
/permission-sets/
and/sharing
. - Copy that string as the value in the enumerated list in Okta. Repeat these steps for all the other permission sets in your org.
Alternative setup: Assign permission sets to all members of a group
If you want to assign permission sets to all users in a team instead of assigning permission sets to individual users, you can select the Combine values across groups option when creating the Permission Sets attribute in Okta.
Note: When assigning permissions at a group level, you may sometimes see errors when Okta attempts to override the permissions of org owners. These errors should not impact functionality, but contact Kustomer Support if you experience any issues.
How to use provisioning
Once you've set up this feature, you can use Okta Group Assignments to provision users by following this process:
- In the Push Groups tab in Okta, push a group to Kustomer. This creates the group in Kustomer as a Team.
- Update the Team's permission sets in Kustomer.
- In Okta, under the Kustomer app assignments tab, make sure to also assign the Okta Group to the Kustomer app so that its users are created.
- To unassign a group from Kustomer in Okta, go to the Push Groups tab in Okta, select Unlink Pushed Group, and then select Delete the group in the target app (recommended). Then, click Unlink to confirm.
We recommend creating a test user and test team to ensure that data from Okta is flowing properly into Kustomer. Once you've confirmed that you can create users and teams in Okta, open the Kustomer app in Okta, go to Provisioning > To App, then check Update User Attributes and Deactivate Users.
Congratulations - you've finished the provisioning process! Make sure to plan out your teams, permission sets, and user roles before deploying your changes to your production org.
Troubleshooting
Q. My changes don't seem to update immediately.
Changes in Okta can be delayed by up to several minutes due to Okta API rate limits. For more information on Okta's rate limits, please see Okta Developer - Rate limits overview.
Q. I updated the group members, but these changes haven't been reflected in Kustomer.
In Okta, go to the Push Groups tab of the Kustomer app. Check for errors in the applicable group.
Then, open the Push Status drop-down and select Push now.
Q. I unassigned a group from the Kustomer app, but I still see it in Kustomer with assigned users.
When assigning a group from the Kustomer app in Okta, you also need to unlink the group from Kustomer in the Push Groups tab.
Open Push Groups, open the Push Status drop-down menu, then select Unlink pushed group. Ensure the option to delete the group in the target app is selected, then click Unlink.
Q. I pushed my group to Kustomer, but team memberships aren't updating, or the team doesn't have the full list of members.
This might require fully refreshing the group. Follow these steps:
- Unassign the group from the Kustomer app.
- Stop pushing the group to the Kustomer app, then select the Delete option.
- Reassign and re-push the group.
Q. I deactivated a team in the Kustomer app, however the deactivated team still appears in the Global Directory and as an option under Link Group when pushing a new group, even after clicking the "Refresh App Groups" button.
You can fix this by going to the Import tab and clicking Import Now. To avoid creating or changing users unintentionally, click Clear Unconfirmed Users after running the import.
Q. Am I able to use Okta SCIM to manage a user with org owner permissions?
No, however you can manage all other permissions levels including administrators. If you attempt to manage an org owner using SCIM, you'll observe any of the following:
- Any updates made from SCIM to an org owner are dropped.
- Any attempts to add org owner permissions to a user from SCIM are ignored.
- Any attempts to create a user with org owner permissions from SCIM will create the user without org owner permissions.
Q. I get an error with the string InvalidTypeForProperty
.
Check the types of fields that were created in Okta. The User Types attribute must use the string data type, whereas the Permission Sets attribute should use the string array data type.