SCIM: Provisioning and Deprovisioning Kisi Organization Members with OneLogin

SSO and SCIM require a Kisi Organization license. Please contact Kisi Support to learn more.

Kisi Organizations customers can configure OneLogin to enable System for Cross-domain Identity Management (SCIM) provisioning and deprovisioning for their Kisi members. Before you start, please check that you have set up SSO for your Organization, generated a SCIM token, enabled SCIM for your Organization.

SCIM with OneLogin allow you to:

• Create Users
• Update User Attributes (via PUT and PATCH)
• Deprovision Users
• Push Groups

Generating SCIM Token in Kisi

To generate your SCIM Token in Kisi:

1. Sign in to your Kisi Organization account
2. Under Organization Setup, click on SSO & SCIM
   
3. Toggle On Enable SCIM and click on Generate Token
   
4. Copy the Token (this Token is only shown once)
   

Setting up SCIM with OneLogin

To configure SCIM with OneLogin for your Kisi Organization:

1. Sign in to your OneLogin admin page, click Applications in the main navigation, and click Add App.
   
2. Search for "SCIM" and click on SCIM Provisioner with SAML (SCIM v2 Core).
   
3. Change the Display Name (optional), and click Save.
   
4. Once saved, the page will reload and you should see the additional sections in the left-hand side menu. Click on Configuration.
   
5. Under API Connection, fill out the following:
   SCIM Base URL: https://api.kisi.io/scim/v2
   Custom Headers: add Accept: application/json and Content-Type: application/json
   SCIM Bearer Token: paste the SCIM Token that you generated in the Kisi Dashboard
   
6. Click the Enable button and the API Status should show Enabled. Click on Save.
   
7. From the side menu, open Parameters.
   
8. Ensure that SCIM Username maps to Email (you can edit these values by clicking on the row with the SCIM Username). A pop-up window will appear, under Value select Email. Click on Save.
   
9. Next, click on the blue add sign () to add a custom field.
   
10. In the new pop-up, enter name : givenName in the field name and tick Include in User Provisioning. Click Save.
    
11. Select First Name as the value from the dropdown menu. Click Save.
    
12. Create another custom field and enter name : familyName in the field name and tick Include in User Provisioning. Click Save.
    
13. Select Last Name as the value from the dropdown menu. Click Save
    
    
14. Once done, you will be back on the Parameters page, please make sure to Save at the top right-hand corner. Then, navigate to Provisioning.
    
15. Under Workflow, check Enable provisioning. By default, OneLogin will create provisioning tasks that will require admin approval whenever you create, delete or update a user (available at Activity > Events). If you’d rather approve all tasks automatically, you can check off those options under Require admin approval before this action is performed.

    

16. There are two more options here, When users are deleted in OneLogin, or the user’s app access is removed, perform the below action and When user accounts are suspended in OneLogin, perform the following action. The possible behaviours are:
    Delete: this will remove the user from the Kisi system.
    

    Suspend: this will deactivate user - they’ll still be able to login in and see places, groups and other resources they had access to before, but they won’t be able to open any of the locks.
17. Navigate to Access > Roles and choose a role. All users with that role will be provisioned. You can select multiple roles. With no role selected, none of the users will be provisioned. Click Save when complete.
    

Only the roles that have at least one user will end up provisioning Kisi groups.

Trigger a sync

You can manually trigger a sync of OneLogin users with Kisi SCIM app users by selecting More Actions > Sync Logins.

If a user is assigned to the app, the user will be provisioned to your Kisi organization. However, the reverse is not true: a user created in the Kisi organization will not be added to the Kisi SCIM app in OneLogin. To manually sync users from the Kisi organization to OneLogin, create a user in OneLogin with the same email address as the user in the Kisi organization, and then assign the user to the app in OneLogin.

Delete users

You should delete users in OneLogin and let OneLogin take care of deprovisioning them from the Kisi Organization. If you delete a OneLogin-managed user directly in the Kisi organization, the user will remain active in the OneLogin Kisi SCIM app. When you then try to delete the user from the Kisi SCIM app, the attempt will fail, because the user is already deleted in the workspace. You can deprovision a user in multiple ways:

• Delete or suspend the user from OneLogin.
• Remove the user from the app manually by going to the Users tab in the Kisi SCIM app, selecting the user, and clicking the Delete button.
• If you have set up rules to assign the user to the app based on a OneLogin attribute, such as OneLogin Role, remove that attribute from the user (for example, remove the user from the OneLogin Role). You can also remove the Kisi app from a OneLogin Role that the user is assigned to (this deprovisions Kisi for all users in the role).

Groups provisioning

After creating, changing or deleting any of the rules, you'll need to click More Actions > Reapply entitlement mappings to apply the changes in Kisi.

To provision groups, navigate to Parameters and click on the Groups field mapping. Then, select Include in User Provisioning.

Assign users to groups that already exist in Kisi

To assign users to existing groups in Kisi, navigate to Provisioning and Under Entitlements, click Refresh. This fetches all the groups available on the Kisi side. Now you can assign users to groups in Kisi either manually or by using a rule.

Manual assignment:

1. Go to Users from the main navigation
2. Select one of the users from the list
   
3. In the left-hand navigation panel, click Applications, and then click blue add icon ().
   
4. Add both the Kisi and SCIM apps
   
   
5. When adding the SCIM app, choose the correct group(s) from the Groups dropdown menu and click Add.
   
   This will override any rules, mappings etc. so it's not preferred, as it may lead to issues that are hard to debug. Use at your own peril.

Rule assignment:

1. Inside the Kisi SCIM application, click on Rules (from the left-hand side menu)
   
2. Click on Add Rule
   
3. Under Conditions, you will need to add the logic that will determine which users are affected. With no conditions defined, the rule will apply to all users.
4. Under Actions, you can define actions that will be applied to any of the attributes provisioned by SCIM. When assigning Groups, you'll need to use Set Groups in <your SCIM app name> option. You can have multiple conditions and actions in the same rule.
5. Click Save

Example: Your OneLogin system has two roles - Alpha and Beta - that you want to map to existing Kisi groups - Administrators and Users. You'll need two rules, one for each Role-Group mapping.

• First rule

  • Conditions:

    • Roles - include - Alpha

  • Actions:
    • Set Groups in - From Existing Select and Add Administrators Kisi group.
• Second rule
  • Conditions:
    • Roles - include - Beta
  • Actions:
    • Set Groups in - From Existing Select and Add Users Kisi group.

Click More Actions > Reapply entitlement mappings to apply the rules.

 

Assign users to Kisi groups created based on OneLogin roles

Example: Your OneLogin system has two roles - Alpha and role Beta - that you want to map to Kisi group. Those groups don't exist in Kisi. You'll need a single rule:

• Rule
  • Conditions:
    • Leave empty
  • Actions:
    • Set Groups in - Map from OneLogin for each role with a value that matches Alpha|Beta. (If we had more roles and we wanted to provision groups based on all of them, we could use .* match value instead)

Click More Actions > Reapply entitlement mappings to apply the rules.

Example: Let's say you have 2 roles in your system, Alpha and Beta, and a single User with role Alpha assigned. After creating the rule described above, and applying it, a single group Alpha will appear in Kisi. After assigning role Beta to any of the users, OneLogin will provision Kisi group Beta automatically.

Notes:

• Deassigning all users from a given role, or removing the rule (and reapplying the entitlements) will not deprovision the Kisi group. It will have to be removed manually.
• You can use rules to provision groups based on other attributes than role too (eg. user email domains, user departament etc.).
• Renaming a role in OneLogin (or other attribute groups are based on) won't rename the group in Kisi. After entitlements are refreshed, the new group (with new name) will be created, the relevant users will be assigned to it, and deassigned from the old group. The old group will not be removed from Kisi.

Troubleshooting and tips:

• Changes to SCIM attributes of Users and Groups done in Kisi will NOT be visible in OneLogin. The sync works in one direction: OneLogin -> Kisi. Subsequent SCIM requests for User/Group will override any of the relevant changes done manually on Kisi side.
• Users who existed in Kisi prior to provisioning setup:
  • Are automatically linked to a OneLogin user if they already exist in OneLogin and are matched based on email address.
  • Can be manually linked to an existing user or created as a new user in OneLogin if they are not automatically matched.
• If at any point you need to resync/reset users:
  1. Ensure you have the latest data on existing groups - Provisioning > Entitlements > Refresh.
  2. Visit Users section of Kisi SCIM application, and select Apply to All > Reset. Users that were added manually in Kisi and are not in OneLogin will not be affected.
• Groups can't be removed in Kisi from OneLogin side - you'll need to remove them manually in Kisi and then Provisioning > Entitlements > Refresh in OneLogin.