Docs

Manage your account

Directory sync (SCIM)

How to configure directory sync on your account to automate the management of users and their permissions from your identity management platform to Knock.

Overview

Directory sync allows you to automatically provision users and manage their permissions in Knock by leveraging the identity provider your organization is using (e.g. Okta) as the single source for user and group information.

Once configured, it enables automated syncing of user identity information from identity providers to Knock using SCIM (System for Cross-domain Identity Management), an open standard for managing automated user and group provisioning.

Any users that are assigned in the Knock application in your identity provider will be created in Knock (or vice versa), with their roles and permissions automatically configured based on their group memberships (see the default group to role mapping for more details).

Directory sync configuration

To set up directory sync for your account:

Contact the Knock support team.
Our team will provide you with a customized link to guide you through the Directory Sync setup process for your specific identity provider.
Follow the step-by-step instructions in the guide provided at the link in order to complete the configuration.

We support many common identity providers. For detailed, provider-specific setup guides, please refer to the following:

Once the setup is complete and user data starts syncing from your identity provider to Knock, you'll see a "connected" status for directory sync under Settings > General in your Knock dashboard

Group-to-role mapping

You can optionally supply a set of group-to-role mappings for your organization. For instance, you might want to always map the "Team Admins" group to the admin role within Knock. You must supply this mapping to the Knock support team to set on your account as there is currently no way to self-service this information.

In the case where you want to force a group to a particular role within your IDP, you can use the following group names to automatically allocate the roles to users in that group.

Group name	Role
knock-role-owner	owner
knock-role-admin	admin
knock-role-member	member
knock-role-billing	billing
knock-role-support	support

How Knock assigns roles

If a user does not belong to any group, Knock will assign the support role to the user. If a user belongs to more than one of these groups, then Knock will assign the highest privileged role available to that user. See roles and permissions for more details.

Frequently asked questions

Knock will identify existing users based on their email, and update (i.e. overwrite) their access and roles based on the user data synced from your identity provider.

Any users that exist in Knock but not in identity providers will retain access to Knock and retain its role originally assigned to them.

If directory sync connection becomes disabled, all users and roles will be left in the state at the time of disconnection and stop syncing from your identity provider.

Yes, please contact the Knock support team to configure a custom mapping. Note, however, you cannot override Knock's default role mapping.

Yes, you can still invite users to Knock from the Knock dashboard, but keep in mind that users created via directory sync will take precedence. This means if you invite a user who is managed via directory sync, the user's role will be updated to reflect the state of your identity provider. Once you enable directory sync, Knock uses your identity provider as the source-of-truth for any users synced via SCIM.