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": "[e-mail]",
 "displayName": "<user_name>",
 "externalId": "",
 "name": {
   "familyName": "<first_name>",        
   "givenName": "<last_name>"              
 },
 "emails":[
 	{
   "value":"[e-mail]"
 	}
 ],
 "roles": [], // SCIM definition not used in Keeper
 "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

---

Handling Roles with the Role Prefix

While Keeper's SCIM integration does not handle the roles argument of the User object, you can create and assign roles by using the role prefix.

In the settings of the SCIM Provisioning Method on the Admin Console, you can define a Role Mapping Prefix:

Any SCIM Group object created with this prefix will not generate a Team, but a Role instead. Likewise, you can assign the role to your users by running the same request as a team assignment.

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

---

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": "[e-mail]",
  "displayName": "<Desired display name>",
  "externalId":"",  
  "name": {
     "familyName": "<first_name>",        
     "givenName": "<last_name>"              
  },
  "emails": [
    {
      "value": "[e-mail]",
      "primary": true
    }
  ],
  "roles":[], // SCIM definition not used in Keeper
  "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