API Provisioning with SCIM
Direct integration with Keeper Enterprise using SCIM
Identity providers such as Okta, Azure AD, Google G Suite, JumpCloud and other popular IdP platforms support the use of SCIM for provisioning Teams and Users to Keeper Enterprise. The terminology differs between platforms. For example, Okta and Azure call it "Automated Provisioning".
Keeper supports SCIM 2.0, a REST-based API using JSON message structure. The Keeper SCIM endpoint supports Users and Groups resources, and the following message types:
- Retrieve user/team information
- Add a user/team
- Update a user/team profile
- Delete a user/team
A user can have multiple nodes synchronizing with different identity providers (Azure AD, Okta directory, etc.) from the same vendor or different vendors. One node per identity provider, parent-child relationship is not supported (e.g if SCIM is setup on a node, the sub-nodes of this node are not controlled by the integration, but they can be controlled by their own provider).
The authentication is the Header Authentication, with the token generated by Keeper when setting up the node.
Keeper SCIM endpoint supports Users and Groups resources, according to the following table:
Per specification: https://tools.ietf.org/html/rfc7644#section-188.8.131.52
Keeper supports the “excludedAttributes” for “members” attribute. To improve performance of working with groups that contain a large number of members, you can add a parameter such as:
...on SCIM queries for multiple groups and a single group, and on PATCH query for a group.
By default, Keeper SCIM API will only return the first 1000 entries for queries that yield large result sets. To query the entire data set, use SCIM pagination parameters according to the specification.
The SCIM identity provider maps to a single node, and the username of the provider maps to the Keeper user name (email address), which needs to be unique globally. Therefore, if an identity provider contains a user defined by the email which is already a member of the same or different Keeper Enterprise account, any attempt to provision this user will fail. The only exception is if the user is already a member of the same node, then the provisioning will be successful, establishing the link between the identity provider and Keeper. To avoid problems, if you already have manually created users in Keeper that match ones that you plan to use in the identity provider, move them manually under the SCIM node prior to setting up the integration in the provider.
When a user is provisioned, Keeper requires either their username or email to contain a valid email address. If not, the provisioning can be rejected (e.g. in Okta you can set username to be some arbitrary string and an email is not required). If the email is fake, it will be accepted, but the provisioned user will not be able to receive the invitation email and as such will not be able to join the enterprise.
New users added by the SCIM sync are created in the “invited” state and will receive an invite to join Keeper. New teams created by the SCIM sync are created in the “pending” state and require final approval from either the Keeper Administrator or another team member.
Users added to teams via SCIM are added in a "pending" state and require approval. Team and user approval will occur automatically when the Admin logs in to the Keeper Admin Console. Approvals can also be automated using Keeper Commander. This is because encryption keys must be generated and/or shared. In Keeper's Zero-Knowledge environment, this action must be performed by a Keeper Administrator or by another team member.
By default, Keeper will accept group creation even if the Group Name is identical to a previously used name.
If you encounter an issue with duplicate group names, please contact Keeper and we will set a flag on your SCIM connection which enforces unique names.
If necessary, contact Keeper Support to enforce unique group names on your SCIM instance.
Keeper has integrated SCIM into the Keeper Commander SDK. Users and groups can be pushed from any directory source (e.g. Google Workspace, Active Directory or any other source) directly into the Keeper SCIM endpoint.
- If you click the "Test" button before saving the SCIM provisioning method in the Admin Console, the test will fail. Copy the token first, then click Save.
- Keeper users are identified by their email, therefore when assigning so make sure the User Name contains a valid email address.
When setting up User and Team SCIM provisioning, make sure of the following:
- When you invite a user from SCIM, if the user does not exist yet in Keeper, they will receive an invite to sign up (or they can use just-in-time provisioning)
- After the user has created their Keeper account, the user will not yet be assigned into a Keeper team until one of a few things happen: (a) Admin logs into the Admin Console > Click on "Full Sync" from the Admin screen (b) A user from the relevant team logs into the Web Vault or Desktop App (c) Admin runs team-approve from Keeper Commander The reason that teams and users can't be created instantly via SCIM, is due to the encryption model and the need to share a private key between users. Sharing an encryption key (e.g. Team Key) can only be performed by a user who is logged in, and has access to the necessary private keys.