All pages
Powered by GitBook
1 of 2

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:

?excludedAttributes=members

...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. Pagination is supported on Users and Groups "GET" requests.

Pagination requires use of the startIndex and count parameters in the request.

Security

For security reasons, SCIM provisioning is only accepted by Keeper when the enterprise tenant has the affected email domain reserved. For example, if the email address being provisions is example.com, then this domain must be reserved to the specific tenant.

For more information about domain reservation process, please see this page.

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.

Team and User Approvals

SCIM Push Command

Keeper has integrated SCIM into the Keeper Commander SDK. Users and groups can be pushed from any directory 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.

Using SCIM API Provisioning

If you are testing or programming against Keeper's SCIM API, we have created a guide with examples on working with Keeper using Postman.

Using SCIM API Provisioning

This page contains information on how to use Postman, a popular API platform to provision your users into your Keeper tenant.

Setting up the Environment

  1. Open Postman

  2. Create a New Request

  • Method: GET , POST, DELETE, PATCH or PUT

  • URL: https://keepersecurity.com/api/rest/scim/v2/<node_id>

Depending on the data center of your Keeper tenant, the domain will change. US: keepersecurity.com EU: keepersecurity.eu AU: keepersecurity.com.au JP: keepersecurity.jp CA: keepersecurity.ca GOV: govcloud.keepersecurity.us

  1. Set the Headers

Key
Value

Authorization

Bearer YOUR_AUTH_TOKEN

Content-Type

application/scim+json

  1. Set the Body

  • Choose raw and select JSON format.


Adding a User - Users/POST

  1. Set the HTTP Method and URL

  • Set the HTTP method to POST using the dropdown menu.

  • Enter the URL for adding a user:

https://keepersecurity.com/api/rest/scim/v2/<node_id>/Users

Be sure to replace <node_id> with your actual node ID where you want the user added. This Node ID is provided to you on the SCIM setup page in the Keeper Admin Console, or it can be found using Keeper Commander's "enterprise-info --nodes" command.

  1. Set the Body

  • Click on the "Body" tab below the URL field

  • Choose raw and select JSON format

  • Add the JSON body with the details of the user you want to add. Here's an example JSON body:

{
 "schemas": [
   "urn:ietf:params:scim:schemas:core:2.0:User",
   "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
 ],
 "userName": "<user_email>",
 "displayName": "<user_name>",
 "externalId": "",
 "name": {
   "familyName": "<first_name>",        
   "givenName": "<last_name>"              
 },
 "emails":[
 	{
 		"value":"email@domain.com"
 	}
 ],
 "roles": "<role_ids>",
 "groups":[
    {
      "value":"<group_id>",
      "$ref":"http://keepersecurity.com/api/rest/scim/v2/<node_id>/<group_id>/scim/Groups",
      "display":"<team_name>"
    }
 ]
}

You can also add the user to a team upon creation by including the <group_id> for "value" in the groups object. This is the only required information to add the user to a group. "$ref" and "display" are optional

  1. Send the Request

Response HTTP codes

HTTP code

Meaning

201

Created

success

409

Conflict

Email already taken

428

Precondition Required

Number of licensed seats was exceeded.

Locking/Unlocking a user - Users/PATCH

  1. Set the Method to PATCH and the URL to the following:

https://keepersecurity.com/api/rest/scim/v2/<node_id>/Users/<user_id>
  1. Set the body of the JSON request

  • Choose raw and select JSON format

  • Add the JSON body with the details of the user you want to add. Here's an example JSON body:

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "Replace",
      "path": "active",
      "value": "true"
    }
  ]
}

Be sure to set the "value" to true (unlocked) or false (locked)

  1. Send the request


Retrieve information about a user/users - Users/GET

  1. Open Postman and set the HTTP method to GET

  • For a information about all the users in a node, use the following URL:

https://keepersecurity.com/api/rest/scim/v2/<node_id>/Users
  • For information on a specific user, specify the user ID

https://keepersecurity.com/api/rest/scim/v2/<node_id>/Users/<user_id>
  1. Send the request

We also support filter for users, below is an example for searching based on user id:

https://keepersecurity.com/api/rest/scim/v2/<node_ID>/Users?filter=id+eq+%22<user_ID>%22

Additionally, you can use pagination by using startIndex and count:

https://keepersecurity.com/api/rest/scim/v2/<node_id>/Users?startIndex=2&count=200

Retrieve Groups & Group ID’s - Groups/GET

  1. Open Postman and create a new GET request

  • Set the URL:

https://keepersecurity.com/api/rest/scim/v2/<node_id>/Groups
  1. Send the request

Expected Response

The response will be a JSON object containing details of all groups under the specified node. The "id" field within each group object represents the group ID. In Keeper, a group is represented by a Keeper Team object. The ID is the Keeper Team UID.

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 2,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
      ],
      "id": "group_id_1",
      "displayName": "Group 1",
      "members": []
    },
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
      ],
      "id": "group_id_2",
      "displayName": "Group 2",
      "members": []
    }
  ]
}

To get the information of a single group, include the group ID at the end of the URL. https://keepersecurity.com/api/rest/scim/v2/<node_id>/Groups/<group_id>

Creating a Team - Groups/POST

  1. Create a New Request

  • Click on "New" and then select "Request" from the dropdown menu.

  • Alternatively, you can click on the "Request" tab if it is already open

  1. Set the HTTP Method and URL

  • Set the HTTP method to POST using the dropdown menu

  • Enter the URL for adding a team

https://keepersecurity.com/api/rest/scim/v2/<node_id>/Groups
  1. Set the Body

  • Click on the "Body" tab below the URL field.

  • Choose raw and select JSON format.

  • Add the JSON body with the details of the team you want to create. Here's an example JSON body:

{
	"schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group",
        "http://schemas.microsoft.com/2006/11/ResourceManagement/ADSCIM/Group"
     ],
     "displayName": "<team_name>",
	 "externalId": "dfe9166c-57f9-417d-83a6-072b5a56a4fe"
}

Replace "Team Name" with the desired team name.

  1. Send the Request

  • Click on the "Send" button in Postman to execute the request


Deleting a team - Groups/DELETE

  1. Set the HTTP Method and URL

  • Set the HTTP method to DELETE using the dropdown menu.

  • Set the URL:

https://keepersecurity.com/api/rest/scim/v2/<node_id>/Groups/<group_id>
  1. Send the request


Adding or removing a user to a team - Users/PATCH

  1. Set the HTTP Method and URL

  • Set the HTTP method to PATCH using the dropdown menu.

  • Set the URL:

https://keepersecurity.com/api/rest/scim/v2/<node_id>/Groups/<group_id>

Replace <node_id> with your actual node ID and <group_id> with the ID of the team you want to update

  1. Set the Body

  • Click on the "Body" tab below the URL field

  • Choose raw and select JSON format

  • Add the JSON body with the details of the user you want to add to the team. Here's an example JSON body:

{
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [
        {
          "value": "<user_id>"
        }
      ]
    }
  ]
}

Changing the "op" value to "add" will add a user to a team. Changing the value to "remove" will remove a user from the team

  1. Send the request


Updating User Attributes - Users/PUT

  1. Create a New Request

  • Click on "New" and then select "Request" from the dropdown menu.

  • Alternatively, you can click on the "Request" tab if it is already open.

  1. Set the HTTP Method and URL

  • Set the HTTP method to PUT.

  • Use the URL:

https://keepersecurity.com/api/rest/scim/v2/<node_id>/Users/<user_id>
  1. Set the Body

  • Click on the "Body" tab below the URL field

  • Choose raw and select JSON format

Here is an example of the JSON body to update the user information:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "userName": "email@domain.com",
  "displayName": "<Desired display name>",
  "externalId":
  
  "name": {
    "familyName": "<First Name>",        
    "givenName": "<Last Name>"              
 },
  "emails": [
    {
      "value": "<email@domain.com>",
      "primary": true
    }
  ],
  "roles":"none" | "123,432,4324,654", 
  "groups":[
    {
      "value":"<group_id>",
      "$ref":"http://keepersecurity.com/api/rest/scim/v2/<node_id>/<group_id>/scim/Groups",
      "display":"<group_name>"}
    }
 ]
  "active": true
}

Changing the "active" flag to false will lock the user account, changing it to true will unlock the account

  1. Send the request

  • Click on the "Send" button in Postman to execute the request

Updating User Attributes - Users/Patch

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "replace",
      "path": "userName",
      "value": "<user_name>"
    },
    {
      "op": "replace",
      "path": "displayName",
      "value": "<display_name>"
    },
    {
      "op": "replace",
      "path": "externalId",
      "value": "<external_Id>"
    },
    {
      "op": "replace",
      "path": "name.familyName",
      "value": "<last_name>"
    },
    {
      "op": "replace",
      "path": "name.givenName",
      "value": "<first_name>"
    },
    {
      "op": "replace",
      "path": "active",
      "value": false
    },
    {
      "op": "add",
      "path": "groups",
      "value": [
        {
          "$ref": "https://example.com/v2/Users/1743756723210",
          "value": "<group_id>"
        }
      ]
    },
    {
      "op": "remove",
      "path": "groups",
      "value": [
        {
          "$ref": "https://example.com/v2/Users/<user_id>",
          "value": "<group_id>"
        }
      ]
    }
  ]
}

SCIM related endpoints/GET

  • Set the HTTP method to Get

  • Use the URL:

ServiceProviderConfig / ResourceTypes (User/Group) / Schemas

https://keepersecurity.com/api/rest/scim/v2/<node_id>/ServiceProviderConfig
https://keepersecurity.com/api/rest/scim/v2/<node_id>/ResourceTypes/User
https://keepersecurity.com/api/rest/scim/v2/<node_id>/ResourceTypes/Group
https://keepersecurity.com/api/rest/scim/v2/<node_id>/Schemas/urn:ietf:params:scim:schemas:core:2.0:User
https://keepersecurity.com/api/rest/scim/v2/<node_id>/Schemas