API Provisioning with SCIM

Direct integration with Keeper Enterprise using SCIM

Keeper supports SCIM 2.0, a REST-based API using JSON message structure. The Keeper SCIM endpoint supports Users and Groups resources, and the below message types:

User Provisioning

- Retrieve user information

- Add a user

- Update a user profile

- Delete a user

Team Provisioning

- Retrieve team information

- Add a team

- Add users to a team

- Delete a 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 provides (Azure AD, Okta directory, etc.), from the same vendor or different vendors. One node per identity provider, parent-child relationship is not supported, f.e. 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/scim/Users

Returns all users for the node 123

Users/GET

https://keepersecurity.com/api/rest/scim/v2/123/scim/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/scim/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/scim/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/scim/Users/456

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

Groups/GET

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

Returns all teams for the node 123

Groups/GET

https://keepersecurity.com/api/rest/scim/v2/123/scim/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/scim/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/scim/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/scim/Groups/789

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

Approval process

New users added by the SCIM sync are created in the “invited” state and sent an invite to join Keeper.

New teams created by the SCIM sync are created in the “pending” state and require final approval by either the Keeper Administrator or another team member. This is because the encryption keys required to decrypt team folders must be provided to the user.

Method 1 - Pending Queue

Keeper administrator can approve the teams in the Enterprise Console by visiting the "Pending Queue" screen.

Admin Console Approval Queue

Method 2 - Team Member Login

Team members approvals are also completed automatically when any member of the team (including the Admin) log into the Keeper Web Vault or Desktop App. Approval is performed by encrypting the Team Key with the user's public key.

When teams are approved, if users linked to these teams have already joined the enterprise, they become the team members immediately. If the linked users have not joined yet, they become pending members after they join and Keeper administrator must approve those users team membership in the Keeper Enterprise Console.

Integration Notes

  • The SCIM identity provider maps to a single node, and username in the provider maps to Keeper user name (email) 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 user is provisioned, Keeper requires either username or email to contain a valid email. If there is none (f.e. In Okta you can set username to be some arbitrary string and email is not required) the provisioning can be rejected. 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.