Configure a SCIM user directory integration with Okta
Before You Begin
- Complete the steps outlined in the SCIM Directory Integration support article to set up a new SCIM user directory in your Kandji instance. You will need to obtain the SCIM access token and API URL.
- Ensure you’re using Okta’s Advanced Lifecycle Management plan, which supports built-in, standards-based provisioning for SCIM.
- Copy and store the token provided as outlined in the SCIM Directory Integration article. The token will not be visible once you click Done and will be required in a later step.
- Be sure to review the supported user and group attributes listed in the SCIM Directory Integration.
Create the SCIM Integration in Okta
The Kandji application available in the Okta Integration Network (OIN) cannot be provisioned for SCIM. A new Application Integration must be created to leverage SCIM. This new app integration will not interfere with any existing Okta SSO integration leveraging the OIN Kandji application.
- Log into your Okta tenant via login.okta.com
- Once logged in, in the left-hand navigation, go to Applications > Applications
- Clicking Create App Integration
- Select SAML 2.0 as the application type and click Next.
- In General Settings, give the App a name and check the box within the App visibility section. Then, click Next.
- In SAML Settings, enter a dummy URL in the Single sign-on URL and Audience URI (SP Entity ID) fields. Do not change any other settings.
Since we will not be using this application integration for SSO, the URLs do not need to be valid; however, you must enter URLs in these fields in order to proceed. If you decide to enable SAML SSO in Kandji, you can use this same app to do so.
In Help Okta Support understand how you configured this application, select I’m an Okta customer adding an internal app, and click Finish.
Configure SCIM settings
- In the Kandji SCIM app, navigate to the General tab.
- In the Settings section, click Edit.
- Select SCIM in the Provisioning setting.
- Do not modify any other settings, and click Save.
- In the Provisioning tab, click Edit in the Integration section.
- For SCIM connector base URL, enter the SCIM integration base URL copied from Kandji (example: https://accuhive.api.kandji.io/api/v1/scim).
- For Unique identifier field for users, enter userName.
- For Supported provisioning actions, select Push New Users, Push Profile Updates, and Push Groups.
- For Authentication Mode, select HTTP Header.
- For Authorization, enter the Bearer Token obtained in the Kandji SCIM Directory Integration article mentioned above.
Click Test Connector Configuration to test the integration.
- Only Create Users, update User Attributes, and Push Groups should be checked in the modal that displays.
While still on the Provisioning tab, go to the To App section and click Edit.
In the Provisioning to App section, enable Create Users, Update User Attributes, and Deactivate Users.
(optional) In the Attribute Mappings, edit the user attributes to send to Kandji. Kandji will only store and use the attributes mentioned in the SCIM Directory integration knowledge base article.
Users and Groups
Assigning users to Kandji
This section covers assigning users to Kandji by creating an Okta user group called
kandji_apple_users. This group will be added to the Assignment tab in the Okta SCIM app.
This method is just one example showing how to assign users to Kandji via Okta SCIM.
- In a new browser tab, navigate to Directory > Groups and click Add Group.
- Give the group a meaningful name like kandji_apple_user and click Save.
- Search for the group you just created and add one or more test users.
- Navigate back to the browser tab where the Okta SCIM app is open
Go to the Assignments tab, click Assign > Assign to Groups.
Search for the newly created group and click Assign > Save and Go Back.
Confirm that the group was assigned and click Done. The group should now appear in the Assignments tab’s Groups section.
If the group does not display, try refreshing the browser tab.
All of the users that belong to this group will be pushed to Kandji and will show up in the Users module. We will discuss how to push groups to Kandji in the next section.
Pushing groups to Kandji
In this section, learn how to push user groups to Kandji.
When planning to push Okta groups to Kandji for use in Assignment rules, for each group that you would like to push, add it to the Group Push tab in the SCIM app.
Per this Okta article, groups used to assign users in the Assignment tab cannot be used in the Push Groups tab. Okta recommends creating additional groups containing the same users and adding the new groups to the Push Groups tab for consistent group membership.
If the same group is added in both places, the assignment tab will take precedence, and the group may not be pushed. One way to handle this is to create a single “user assignment” group containing all your Kandji users and add that group to the Assignment tab. From there, you can use your existing Okta groups as Push Groups. Remember that for the user-group association to work, the members of the pushed groups must also be members of the Kandji users group assigned to the SCIM app.
In the Push Groups tab, select Push Groups > Find groups by name. (If preferred, you can also use Find groups by rule)
Search for a group and select it.
Ensure that Create Group is chosen.
Click Save & Add Another.
Search for and add additional groups that you would like to push to Kandji.
For the user-group association to work, the members of the pushed groups must also be members of the Kandji users group assigned to the SCIM app.
Automatically updating membership for the kandji apple users group
Okta group rules can be used to automatically update the
kandji_apple_users group when adding someone to one of your existing groups used as push groups. For example, if you add someone to the developers group, a rule can be created such that when you add new users to the developer group, they will also be added to the
kandji_apple_users group. The new users will be assigned to the SCIM app, and sent to Kandji via the SCIM integration, and group associations will be updated.
- Click on Directory > Groups > Rules > Add Rule.
- Give the rule a name. Example: “update
- Choose Group membership as the condition.
- Enter the names of the groups used as push groups.
- For Assign to enter
Back on the group rules page, next to the rule. select the Actions dropdown and then Activate.
Pushing group updates
- If you add additional users to the group assigned to the SCIM app in Okta, be sure to also update the groups that you’ve added as the Push groups.
Updates should be seen in Kandji fairly quickly, but if you would like to push group updates immediately, you can choose the option to Push Now from the Push Groups tab in the Okta app. More information can be found in the Okta article.
User and group syncing is one-way, meaning the SCIM app will send user information to Kandji only when there is new or updated information to be sent. For this reason, a "Sync Now" option is not needed in the Kandji web app.
Deleting Pushed Groups
Use the following steps to stop pushing group updates or optionally delete a pushed group from Kandji.
- Go to the Push Groups tab for the app in Okta.
- In the Push Status column, select Unlink push group.
- Select the option to Delete the group in the target app (recommended). This will DELETE the group in the target app, and user accounts will NOT be deleted. The user accounts are tied to the assignment group on the Provisioning tab.
- Click Unlink.
You should no longer see the group listed in the Push Groups tab.