Skip to main content

SSO & SCIM

The process of provisioning and deprovisioning users involves creating, updating, and deleting their accounts in multiple applications and systems. Often, access management practices include associated information, such as user permissions, group memberships, or the groups themselves.

Kisi can be set up to work with one of two user provisioning methods: SSO or SCIM.

tip

Using SSO and SCIM is optional, you can manage your Organization's account without this setup.

note

SSO requires a Kisi Organization license. Please contact Kisi Support to learn more and upgrade your account.

SSO#

Single Sign On (SSO) is a session and user authentication service that allows a user to log in with a single ID and password to multiple applications and websites.

To activate SSO for Kisi, you can do it through any of these platforms: OneLogin, Azure, Okta, Google or JumpCloud.

note

To set up SSO, you must be the Kisi Organization Owner.

OneLogin#

The OneLogin unified access management (UAM) platform is an identity management system that uses SSO and a cloud directory to enable organizations to manage user access to on-premises and cloud applications. The platform also includes user provisioning, lifecycle management, and multi-factor authentication (MFA).

To configure SSO in OneLogin to work with Kisi, follow these steps:

  1. Sign in to OneLogin.
  2. At the top, select Applications and then click on Add App.
OneLogin app
  1. Search for Kisi and click on the app.
Kisi app in OneLogin
  1. Click Save to create the application.
OneLogin Kisi app save
  1. Once saved, please navigate to Configuration and enter your Kisi Domain. Every Organization in Kisi has a domain. It's an alphanumeric string that can also contain "-" character used to uniquely identify your organizations and required during signing in. If you do not remember your Kisi Domain, you can use Find My Organizations feature.
OneLogin Kisi app save
  1. Navigate to SSO and copy the Issuer URL.
OneLogin Kisi app save
  1. Click Save.

Now, from Setup > SSO & SCIM in the Kisi dashboard:

  1. Sign in to your Kisi Organization account
  2. Under Setup, click on SSO & SCIM and paste the Metadata URL (Issuer URL copied above)
OneLogin Kisi app save
  1. Click Save.

  2. Under Step 3, click on Generate Certificate.

In the OneLogin dashboard:

  1. Paste the contents of the encryption certificate you downloaded from the Kisi dashboard in the Public key section, under Configurations > SAML Encryption.
OneLogin Kisi app save
  1. Click Save.
  2. Assign users to the created Kisi application.

Azure#

Microsoft Azure, commonly referred to as Azure, is a cloud computing platform—with solutions including Infrastructure as a Service (IaaS), Platform as a Service (PaaS), and Software as a Service (SaaS).

Azure allows to integrate services like SSO to work with external systems like Kisi. Follow the Azure and Kisi Physical Security tutorial to configure SSO for Kisi in Azure.

Okta#

Okta is a platform in the Identity-as-a-Service (IDaaS) category that helps to manage and secure user authentication into applications.

To activate SSO for Kisi, in the Okta dashboard, follow these steps:

  1. Sign in to Okta and ensure you are using the classic UI interface (top-left corner).
  2. Click on Applications from the main navigation and select Add Application.
SSO Kisi app
  1. Search for the Kisi Physical Security app and select it from the dropdown menu.
SSO Kisi app search
  1. Click Add.
SSO Kisi app
  1. On the following General Settings page, click Done.
SSO general settings
  1. Click on the Sign On tab for the Kisi Physical Security app, then click Identity Provider metadata and copy the Metadata URL.
SSO copy metadata

In Kisi:

  1. Sign in to your Kisi Organization account.
  2. Under Setup, click on SSO & SCIM and paste the Metadata URL.
Kisi SSO setup
  1. Click Save.
  2. Under Step 3, click on Generate Certificate.

Now that you have generated the encryption certificate, go back to Okta and follow the steps below to complete the configuration.

  1. In Okta, under the Sign On tab for the Kisi Physical Security SAML app, click Edit.
SSO edit sign on
  1. In Encryption Certificate: Upload the encryption certificate that you have downloaded from the previous steps
  2. In Domain: Enter your Kisi Domain. Every Organization in Kisi has a domain. It's an alphanumeric string that can also contain "-" character used to uniquely identify your organizations and required during signing in. If you do not remember your Kisi Domain, you can use Find My Organizations feature.
SSO cert domain
  1. Click Save.

Assigning people to the Kisi application#

info

To test the SSO setup, please make sure to assign yourself to the Kisi app. You can then try to sign into Kisi using the SSO option.

In the Okta dashboard, under the Assignments tab, click the Assign button to assign people or groups who should be able to access Kisi. If you don't add them, they won't be able to access Kisi via Okta.

SSO assign

Google#

Kisi supports SSO with Google as a way of authentication for your Organization. Below are the steps to our self-service SSO configuration.

  1. Sign in to Google Workspace Admin Console.
  2. Click on Apps.
SSO Google apps
  1. Choose SAML apps.
SSO Google SAML
  1. Click on the Add App dropdown menu and select Add custom SAML app.
SSO Google custom app
  1. Enter the app name (e.g. Kisi SSO) and click Continue.
SSO Google app name
  1. Download IDP metadata and click Continue.
SSO Google app name
  1. Fill out the fields below and once done, click Continue.
SSO Google app name
  • ACS URL: https://api.kisi.io/saml/consume/<your-kisi-domain>. Every Organization in Kisi has a domain. It's an alphanumeric string that can also contain "-" character used to uniquely identify your organizations and required during signing in. If you do not remember your Kisi Domain, you can use Find My Organizations feature.
  • Entity ID: https://api.kisi.io/saml/metadata
  • Start URL: Leave empty
  • Signed Response: Check
  • Name ID Format: Persistent
  • Name ID: Basic Information - Primary Email
  1. In the Attribute Mapping section, click Add Mapping and insert fields as shown below and click Finish.
SSO Google app name
  • Required by Kisi: Email - Basic Information - Primary Email
  • Optional: FirstName - Basic Information - First Name and LastName - Basic Information - Last Name
  1. Click on the arrow to edit the Service Status.
SSO Google app name
  1. Select ON for everyone and click on Save.
SSO Google app name
  1. Assign users to the Kisi Application.

In Kisi:

  1. Sign in to your Kisi Organization account.
  2. Under Setup, click on SSO & SCIM and upload the Metadata file that you downloaded in the steps above.
SSO Google app name
  1. Click Save.
  2. Click on Generate Certificate.

JumpCloud#

JumpCloud is a cloud based directory platform used to securely manage users identity, devices, and access.

JumpCloud allows SSO integrations, intended to work with platforms like Kisi. Follow the JumpCloud Single Sign On with Kisi tutorial to configure SSO for Kisi in JumpCloud.

SCIM#

The System for Cross-domain Identity Management (SCIM) is a standard for automating the exchange of user identity information between identity domains, or IT systems. SCIM keeps all the user information up to date across all platforms. When you connect it to physical access control with Kisi, you update your user information and de-provision accounts on your identity provider's interface and your doors' access permissions will be updated. The users' information doesn't need to be manually updated in your Kisi directory, it automatically gets refreshed when updated in your identity provider's interface.

When users are assigned to groups via SCIM, they receive a notification email. To avoid spam, there is a 1 week cooldown period on this email. This means that if users are deassigned and re-assigned to the same group during that week, they will only receive one email (for the first time user was assigned to the group).

Okta#

Users can be created in Okta and synchronized with Kisi through SCIM.

Available features#

All actions executed on users in the Okta dashboard, will take immediate effect in the Kisi dashboard after configuring the SCIM connection. These actions are:

  • Create users.
  • Update user attributes (via PUT and PATCH).
  • Deprovision users.
  • Push groups.

Requirements#

  • Setup SSO for you organization. To configure SSO please check the SSO setup.
  • Generate a SCIM token for your organization, through an API call to the scim_tokens endpoint:
curl -X POST 'https://api.kisi.io/scim_tokens' \
-H 'Accept: application/json' \
-H 'Authorization: KISI-LOGIN {authorization_token}'
  • Enable SCIM for your organization via the organization update endpoint:
curl -X PATCH 'https://api.kisi.io/organization' \
-H 'Accept: application/json' \
-H 'Authorization: KISI-LOGIN {authorization_token}'
  • Add a Kisi Physical Security app in your Okta organization, if you don't already have one.

Configuration in Okta#

Configure Okta for your Kisi Organization following these steps:

  1. Sign in to Okta and ensure you are using the classic UI interface (top-left corner).
  2. Click the Admin button, Applications in the main navigation, and select your Kisi Physical Security app from the list.
Zones status overview
  1. Navigate to the Provisioning tab and click Configure API Integration.
Zones status overview
  1. Check Enable API integration and enter your SCIM token (without the leading Bearer if present).
Zones status overview
  1. Click Test API Credentials.
Zones status overview
  1. Ensure a success message is displayed ('Kisi Physical Security was verified successfully!') and save.

  2. Click Edit and enable Create Users, Update User Attributes and Deactivate Users options in Provisioning > To App and save.

  3. Assign users to the SCIM group.

note

Okta doesn't support pushing groups that are responsible for assignments via SCIM. Check the About Group Push article in the Okta website. We cite an extract of this text below.

The following are the known Group Push limitations:

Using the same Okta group for assignments and for group push is not supported. To maintain consistent group membership between Okta and the downstream app, you need to create a separate group that is configured to push groups to the target app.

To comply with the instructions above, we recommend creating 1 additional group for assigning users to the SCIM application. This group should not be pushed. It will be used only to enable SCIM for assigned users, as users that don't have access to SCIM app won't be synced, even if they are assigned to a pushed group.

Each group that should be synced via SCIM to Kisi, needs to be pushed manually first. You can do that by visiting Applications > SCIM application > Push Groups and push group(s) using either a name or a rule (regular expression that will match multiple group names).

After the initial manual push, the groups will use SCIM protocol to keep their name/memberships in sync, automatically.

Alternative group provisioning method#

Below is described an alternative method for group provisioning.

caution

This is incompatible with regular group assignment flow. Don't try to use both methods at the same time.

note

If Okta's groups don't work with your workflow, it's possible to assign users to Kisi groups in a different manner - based on Kisi group name.

  1. Follow steps 1 to 7 from the Configuration in Okta section.
  2. Go to Provisioning > To App > Go to Profile Editor.
  3. Add custom attributes:
  • Data type: string.
  • Display name: Team Name.
  • External name: groupName.
  • External namespace: urn:scim:schemas:kisi:1.0:User.
  • Leave the rest fields with default/empty values.
  1. Go to Assignments > People and set Group Name for specific Users. In this step, take into account:
  • Each User can only have one Kisi group assigned this way.
  • This will allow you to specify Group Name for each User, when they are assigned to the Kisi application in Okta. This value must match an existing group in Kisi. If it doesn't, the request to provision User will fail with 422 HTTP status. If the value matches name of an existing Group, User will be provisioned and automatically added to it.
  • Changing the Group Name to a different value, will remove the Share for the old Group, and create one for the new Group.
  • Suspending/Deprovisioning User will not remove the Share (and thus access) to the Group. However, it won't allow User to open any of the locks.

Optional Step 4

If instead of having to manually set it for each user you want the Group Name to be calculated by an expression, hardcoded to a specific value, or mapped from a different attribute:

  • Go to Provisioning > To App > Go to Profile Editor > Mappings
  • Choose Okta User to <Name of the Okta's Kisi app>.
  • Locate custom attribute groupName in the column on the right, and choose an attribute or enter an expression in the matching input box on the left.
  • Save and Apply updates now.

Example: Your organization doesn't use Groups in Okta, but all your Users belong to one of three departaments (set in Departament field) - Sales, QA, and Developers. You want to create 2 groups - Devs and NonDevs in Kisi and assign Users based on their department.

After you've created 2 groups with matching names - Devs and NonDevs - in Kisi app, and added a custom Group Name attribute to you Kisi app in Okta, you'll need to add a mapping user.department == 'Developers' ? 'Devs' : 'NonDevs' => groupName. After force syncing, your Users will be assigned to appropriate groups in Kisi.

Known Issues/Troubleshooting#

  • Suspended users won't be deleted on Kisi side. After their active session expires, they won't be able to login in either.
  • Deactivated users will still be able to sign in to Kisi, but they won't be able to unlock any door.
  • Users (and their shares) that were added via shares and not via SCIM will not be removed when Push Now is used.
  • If you can't use the Reset SCIM token endpoint, please contact support@getkisi.com and ask for access token.

OneLogin#

To configure OneLogin to enable SCIM provisioning and deprovisioning for your Kisi members, follow the steps through the next sections.

User provisioning#

  1. Sign in to your OneLogin admin page, click Applications in the main navigation, and click Add App.
Zones status overview
  1. Search for "SCIM" and click on SCIM Provisioner with SAML (SCIM v2 Core).
Zones status overview
  1. Change the Display Name (optional), and click Save.
Zones status overview
  1. Once saved, the page will reload and you should see the additional sections in the left-hand side menu. Click on Configuration.
Zones status overview
  1. 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 via the /scim_tokens endpoint.
  1. Click the Enable button and the API Status should show Enabled. Click on Save.
Zones status overview
  1. From the side menu, open Parameters.
Zones status overview
  1. 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.
Zones status overview
  1. Next, click on the blue add sign to add a custom field.
Zones status overview
  1. In the new pop-up, enter name : givenName in the field name and tick Include in User Provisioning. Click Save.
Zones status overview
  1. Select First Name as the value from the dropdown menu. Click Save.
Zones status overview
  1. Create another custom field and enter name : familyName in the field name and tick Include in User Provisioning. Click Save.
Zones status overview
  1. Select Last Name as the value from the dropdown menu. Click Save.
Zones status overview
  1. 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.

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

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

  1. 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.
Zones status overview
note

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

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

Trigger a sync#

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

Zones status overview

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.

Groups provisioning#

note

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.

Zones status overview
Zones status overview

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.
Zones status overview
  1. When adding the SCIM app, choose the correct group(s) from the Groups dropdown menu and click Add.
Zones status overview

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)
Zones status overview
  1. Click on Add Rule.

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

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

  4. Click Save.

ExampleFirst ruleSecond rule
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.- Conditions: Roles - include - Alpha
- Actions: Set Groups in - From Existing Select and Add Administrators Kisi group.
- 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#

To assign groups based on OneLogin rules, you have to create rules. Follow the Rule assigments steps explained in the previous section.

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

A specific case of the above example could be having the two roles mentioned, 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 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.