# Manage users with Okta SCIM

> Okta 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 SCIM.

Source: https://help.kustomer.com/en_us/okta-scim-SJpB_K8f5

Last updated: 2024-09-26T15:13:31.938Z

Okta 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](#prerequisites)
*   [Create an API key in Kustomer](#api)
*   [Configure provisioning in Okta](#configure)
    *   [Create a User Type attribute in Okta](#user-type)
    *   [Set a user's display name in Okta](#display-name)
    *   [Assign permission sets to individual users](#individual-permission-sets)
        *   [Find IDs for permission sets](#ids)
    *   [Alternative setup: Assign permission sets to all members of a group](#group-setup)
*   [How to use provisioning](#how-to)
*   [Troubleshooting](#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](https://help.kustomer.com/saml-authentication-and-sso-login-rJHxwIUAw).

Your Okta account will also need to have purchased the [Okta Lifecycle Management or Okta Advanced Lifecycle Management](https://www.okta.com/products/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 ![](https://cdn.kustomerhostedcontent.com/media/570fad9d9001bc1000163b28/2e7f6333ccb79c1633f14f52da4263db.png)\> 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:**

1.  In Kustomer, go to **Settings ![](https://cdn.kustomerhostedcontent.com/media/570fad9d9001bc1000163b28/5392fd1be756434ce972fa317c5643c2.png)\> Security > API Keys**.
2.  Select **Add API Key**.
3.  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)
4.  Select **Create**.
5.  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:**

1.  In Okta, go to your Kustomer app.
2.  Go to **General > App Settings > Edit**.
3.  Under _Provisioning_, select the **SCIM** option, then press **Save.**
4.  The page will refresh, and a new tab named _Provisioning_ will appear. Open the **Provisioning** tab and select **Edit.**
5.  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
6.  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.
    
7.  In the **HTTP Header: Authorization** field, paste the API key you created on the Kustomer site in the previous step.
8.  Select **Test Connector Configuration**.
9.  If the test was successful, press **Save**.

![](https://cdn.kustomerhostedcontent.com/media/570fad9d9001bc1000163b28/b37754c20629bc39a606b5e2ab0b1286.png)

### 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:**

1.  After saving the SCIM Connection, refresh the Okta page. Under the _Provisioning_ tab, a sidebar option named **To App** should now appear. Select it.
2.  Select the **Edit** button.
3.  Check the **Create Users** box, then press **Save**.
4.  In the Okta settings, go to **Directory > Profile Editor**.
5.  Select **Kustomer User**, then select **Add Attribute**.
6.  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
            
7.  When you're finished, **Save** the attribute.

![](https://cdn.kustomerhostedcontent.com/media/570fad9d9001bc1000163b28/4a89fc057f0c3b4aef8b67ecf16829b0.png)

### 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:**

1.  In the Okta settings, select **Kustomer User** again (if it's still not selected from the previous section), and then select **Add Attribute**.
2.  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
3.  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](#group-setup).

**To set up provisioning for permission sets in Okta:**

1.  In the Okta Settings, select **Kustomer User** again (if it's not still selected from the previous section), and select **Add Attribute** again.
2.  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](#ids).
            
            **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>
            
    *   **Scope:** check the box _User personal_
3.  When you're finished, **Save** the attribute.

![](https://cdn.kustomerhostedcontent.com/media/570fad9d9001bc1000163b28/cd67ef23e210d460ec6b1b3582768a9a.png)

### 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****:**

1.  In Kustomer, go to **Settings ![](https://cdn.kustomerhostedcontent.com/media/570fad9d9001bc1000163b28/0237f896734662655f4b95fac12ba9a5.png)\> Users > Permission Sets**.
2.  Locate the Permission Set, then select the **Sharing**![](https://cdn.kustomerhostedcontent.com/media/570fad9d9001bc1000163b28/1e2a39d0f0fc0bf529125d250783970c.png)icon.  
    ![](https://cdn.kustomerhostedcontent.com/media/570fad9d9001bc1000163b28/e8d496bf5305f17ee7855d5ae1c391f2.png)
3.  Refer to the current URL in the browser address bar. The ID is the alphanumeric string between `/permission-sets/` and `/sharing`.  
    ![](https://cdn.kustomerhostedcontent.com/media/570fad9d9001bc1000163b28/a71ee3c27be6f9a6b9daf8307471b493.png)
4.  Copy that string as the value in the enumerated list in Okta. Repeat these steps for all the other permission sets in your org.  
    ![](https://cdn.kustomerhostedcontent.com/media/570fad9d9001bc1000163b28/2b7d323e8aae2c2a228366b56200429f.png)

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

![](https://cdn.kustomerhostedcontent.com/media/570fad9d9001bc1000163b28/7d7dc4d262a48c3f1d4a2ba1f06eb008.png)

  

### How to use provisioning

Once you've set up this feature, you can use **Okta Group Assignments** to provision users by following this process:

1.  In the **Push Groups** tab in Okta, push a group to Kustomer. This creates the group in Kustomer as a Team.
2.  Update the Team's permission sets in Kustomer.
3.  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.
4.  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.  
    ![](https://cdn.kustomerhostedcontent.com/media/570fad9d9001bc1000163b28/d50be072ebee17461850ef7b9935151f.png)

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

![](https://cdn.kustomerhostedcontent.com/media/570fad9d9001bc1000163b28/84ef03d8f12d6ec28751e92dc66938a3.png)

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](https://developer.okta.com/docs/reference/rate-limits/).

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

1.  Unassign the group from the Kustomer app.
2.  Stop pushing the group to the Kustomer app, then select the **Delete** option.
3.  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.