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. Group memberships can map to built-in roles or to custom permission groups. See the default group to role mapping for more details.
Directory sync configuration
#Contact the Knock support team to set up directory sync for your account. You'll receive a custom link to step-by-step instructions for configuring the directory sync for your specific identity provider.
We support many common identity providers. For detailed, provider-specific setup documentation, 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 on the Security page under the Admin section of your account settings in your Knock dashboard.
Group-to-role mapping
#You can optionally supply a set of group mappings for your organization. For instance, you might map the "Team Admins" group to the admin role, or the "Engineering" group to a custom permission group with the key engineering. 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.
Groups must be mapped to either a built-in role (owner, admin, member, production_only_member, billing, support) or a custom permission group key. The mapping value should always be the role or permission group key itself (admin, engineering), not a knock-role- prefixed value. Knock's default knock-role-{key} group names always apply and cannot be overridden by a custom mapping.
Built-in role groups
#To assign a built-in role from your identity provider, use the following group names. Knock automatically allocates the matching role to users in that group.
Custom permission groups
#If your account uses custom permission groups, directory sync can assign those groups as well.
Create a group in your identity provider named knock-role-{key}, where {key} is the permission group's key. For example, a group named knock-role-engineering maps to a custom permission group with the key engineering.
You can also include a custom permission group key in the custom mapping you send to Knock support. For example, mapping "Engineering" to "engineering" assigns that custom permission group to every member of the Engineering identity provider group.
Built-in role names always take precedence over a custom permission group with the same key. Avoid using a permission group key that matches a built-in role (owner, admin, member, production_only_member, billing, support). If you create a custom group whose key is admin, knock-role-admin still maps to the built-in admin role.
Missing or archived custom permission groups are ignored at sync time. If no live custom group remains, Knock falls back to the highest-privilege mapped built-in role, or to the support role if none is mapped.
How Knock assigns roles
#Knock resolves each user's assignment from their identity provider group memberships:
- Custom permission groups. A user can belong to more than one identity provider group. If any of those memberships map to live custom permission groups, Knock assigns the Custom role and the combined permissions of every matching group. This takes precedence over the owner and admin roles. A member cannot have both a built-in role and custom permission groups.
- Highest-privilege built-in role. If no live custom permission group matches, Knock assigns the highest-privilege mapped built-in role. See roles and permissions for more details.
- No mapped group. If a user does not belong to any mapped group, Knock assigns the support role.
Preventing account lockout
#Because Knock uses your identity provider as the source of truth, role changes coming from your identity provider are applied even when they would remove or demote your last account owner. As a result, it's possible to end up with an account that has no owner — for example, if the only user mapped to the owner role is removed from your directory (or from the knock-role-owner group).
Custom permission groups and owner access
#If a user belongs to both an owner-granting group and a group that maps to a live custom permission group, the custom assignment wins. Re-adding the user to knock-role-owner does not restore the owner role while that custom mapping still matches.
To restore the owner role, do one of the following:
- Remove the custom group memberships. Remove the user from the identity provider groups that map to custom permission groups.
- Archive the permission group. Archive the custom permission group in Knock so Knock ignores it at sync time.
Then keep the user in knock-role-owner or in a group that your custom mapping assigns to owner.