API Provisioning with SCIM

Direct integration with Keeper Enterprise using SCIM

What is SCIM?

System for Cross-domain Identity Management (SCIM) is a standard for automating the exchange of user identity information between identity domains, or IT systems [wikipedia].

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:

User/Team Provisioning

  • Retrieve user/team information

  • Add a user/team

  • Update a user/team profile

  • Delete a user/team

Keeper SCIM Rest endpoint is a resource available at http://keepersecurity.com/api/rest/scim/v2/<node_id>, where node_id identifies the Keeper Enterprise node used in the SCIM protocol sync.

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:

Resource/Method

URL sample

Users/GET

https://keepersecurity.com/api/rest/scim/v2/123/Users

Returns all users for the node 123

Users/GET

https://keepersecurity.com/api/rest/scim/v2/123/Users/456

Returns the user 456 for the node 123 or 404 if not found

Users/POST

https://keepersecurity.com/api/rest/scim/v2/123/Users

Parses SCIM content (User) of the requests and adds an user to the node 123

Users/PATCH

https://keepersecurity.com/api/rest/scim/v2/123/Users/456

Parses SCIM content (Operations) and adds or removes the user 456 to/from teams referenced in add/remove operations as groups. Also, can process “active” property making user locked or unlocked in Keeper. The referenced teams must belong to the same node. Returns 404 if user is not found.

Users/DELETE

https://keepersecurity.com/api/rest/scim/v2/123/Users/456

Locks user 456 from the node 123. Returns 404 if user is not found.

Note: Keeper locks the account instead of deletion to prevent data loss. Admin can perform permanent user deletion within the Admin Console interface or Commander API.

Groups/GET

https://keepersecurity.com/api/rest/scim/v2/123/Groups

Returns all teams for the node 123

Groups/GET

https://keepersecurity.com/api/rest/scim/v2/123/Groups/789

Returns the team 789 for the node 123 or 404 if not found

Groups/POST

https://keepersecurity.com/api/rest/scim/v2/123/Groups

Parses SCIM content (Group) of the requests and adds a team to the node 123

Groups/PATCH

https://keepersecurity.com/api/rest/scim/v2/123/Groups/789

Parses SCIM content (Operations) and adds or removes to the team 789 users referenced in add/remove operations. The referenced users must belong to the same node. Returns 404 if team is not found.

Groups/DELETE

https://keepersecurity.com/api/rest/scim/v2/123/Groups/789

Deletes team 789 from the node 123. Returns 404 if team is not found.

ServiceProviderConfig/GET

https://keepersecurity.com/api/rest/scim/v2/123/ServiceProviderConfig

Returns SCIM Service Provider Configuration for Keeper SCIM service

Notes Regarding Integration

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.

Team and User Approval Process

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. Actions must be taken by either the Admin or using a methods outlined in the following section, 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.

Teams and Users that are provisioned via SCIM require approval as described in the following section, "Approval Queue".