API Provisioning with SCIM
Keeper supports direct SCIM API provisioning for any 3rd party identity provider
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 / Entra ID, 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".
Other identity management products such as SailPoint also support the use of SCIM 2.0 for provisioning users automatically.
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 |
Excluded Attributes
Per specification: https://tools.ietf.org/html/rfc7644#section-3.4.2.5
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.
Pagination
Per specification: https://tools.ietf.org/html/rfc7644#section-3.4.2.4
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.
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. Team and user approval occurs automatically when the Admin logs in to the Keeper Admin Console. Approvals can also be automated using the Keeper Automator service or using Keeper Commander. The reason that teams and users are approved using this method 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, by another team member, or by the automation service. Keeper's support team can assist customers in installing the automation service.
Unique Group Names
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.
SCIM Push Command
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.
Learn More about the SCIM Push command.
Troubleshooting and Tips
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.
Team Provisioning and Team Assignments
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 or.... (b) A user from the relevant team logs into the Web Vault or Desktop App or.... (c) Admin runs team-approve from Keeper Commander or... (d) The Keeper Automator service approves the transaction. 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.
To streamline this process, the Keeper Automator service as of version 3.2 performs instant approval of Teams and team assignments. More information about the Automator service is located here.
Last updated