Manage users via API (Generic SCIM integration)

Automate user creation and deletion via our API

Pearl McGuire avatar
Written by Pearl McGuire
Updated over a week ago

Setting up Generic SCIM in a single Location

Step 1: Install the Proxyclick Generic SCIMIntegration

Proxyclick has implemented REST API endpoints for SCIM at

https://api.proxyclick.com/scim/v1 

Authentication is via Bearer Token. To retrieve this bearer token, you must install the Custom SCIM integration from the Proxyclick Marketplace.

Log into your Proxyclick account (and, if appropriate, select the primary Location you will use for SCIM from the selection menu) then click on Settings(1), Integrations (2), Browse Marketplace (3).


Click on User Provisioning(1) in the Categories menu, then click SCIM(2).

Click on Install (1)

In your SCIM configuration, enter the API Base URL(1) and API Bearer Token(2) from the configuration page.

Step 2: Configure SCIM Attributes

The exact configuration details will vary based on your SCIM implementation and are beyond the scope of this document. Instead, we will focus on exactly what attributes we support and how they will be used in Proxyclick after provisioning.

Tip 💡 Proxyclick only supports the /Users data type, and will not accept calls to /Groups.

Proxyclick supports the following SCIM Attributes:

Sample JSON payload:

{ 
"schemas": [
"urn:scim:schemas:core:1.0"
],
"userName": "james.bond.007@mi6.org",
"name": {
"formatted": "James Bond",
"familyName": "Bond",
"givenName": "James"
},
"emails": [
{
"value": "james.bond.007@mi6.org",
"type": "work",
"primary": true
}
],
"phoneNumbers": [
{
"type": "mobile",
"value": "+44007007007"
},
{
"type": "work",
"value": "+44007007007"
}
],
"addresses": [
{
"primary": true,
"locality" : "London"
}
],
"title": "Secret Agent 007",
"preferredLanguage": "en",
"active": true
}

Additional attribute information:

The username, work email, and name fields are all required, and are used to define the minimum data necessary to load a colleague into Proxyclick. userName and email must be the same value; email address is the primary external identifier for user accounts and must be unique within the system.

phoneNumbers:

  • type:work should be a direct/desk number for the host. If supplied, it will be shown on the user profile and in the Logbook page of the web app. This number must be in E.164format. Numbers not in this format will cause the user creation/update to fail.

  • type:mobile is the mobile phone number for the host; used for SMS notifications if enabled. This number must be in E.164 format and be a valid Mobile number. Numbers not in this format or that return as a Landline when checked will cause the user creation/update to fail. May optionally be included in visit invitation emails.

preferredLanguage:

Generally, this should be a two-letter language code that will be used to set the language of the Web App for the provisioned host. This will also be the default language for invitation emails sent on behalf of this host. Supported language codes as of May, 2019: de, en, es, fr, it, nl, sk, sl, vi, ko

This field may optionally be used as part of multi-location user provisioning. Non-language values may be supplied, in which case the user’s profile language will be set to en.

addresses:

The addresses.locality value is used only when multi-location provisioning is in use. Please see the end of the document for information on multi-location provisioning.

title:

This optional field is typically used to show the host’s job title, functional role, or similar. It is displayed on the host’s Profile in the web app.

Step 3: Provision and Maintain Users

Once your SCIM client has been configured to send the appropriate attribute data, you are ready to begin sending user data to the Proxyclick SCIM endpoints. All methods below are listed against the Base URL value from your Integration settings.

Methods

GET /Users

Returns a paginated list of users; the default is 10 users per page. You may use the countparameter (max 5,000) to determine how many users appear per page, and the startIndexparameter to choose where in the user list to create the start of the page.

You may retrieve a single user by specifying a filter parameter with the value userName eq “user@example.com where you already know the user’s email address, but need to retrieve the Proxyclick user id value.

You may also retrieve a single user by making a GET request to /Users/{id}, where {id} is the Proxyclick user id value.

POST /Users

Creates a new user. The payload for this request must be the SCIM JSON (see above example) for the user you wish to create. The return response if successful will be the same JSON payload, with the addition of the Proxyclick user id value.

PUT /Users/{id}

Update an existing user. The payload for this request must be the full SCIM JSON data for the user you wish to update, including unmodified fields. You may omit the Proxyclick user id value in the JSON for this operation, as it is specified in the URL.

DELETE /Users/{id}

Delete an existing user. No payload is needed, simply specify the Proxyclick user id value in the URL of the request.

Optional Step: Setting up SCIM for multi-location provisioning

To configure SCIM provisioning for multiple locations, return to the Integrations settings page while logged in as a user with administrator rights in multiple locations. Click on “Multi-location mapping” to begin setup.

You will be shown a list of all locations you have administrative rights in. For each location, you will have the option to configure user provisioning. Select “Only import specific users” (1) to configure filtering if you do not wish to load all SCIM users to each location. Locations after the first are toggled with a toggle element (2). Locations which already have provisioning configured individually will not be available for setup (3).

User filtering, if enabled, can be performed based on the addresses.locality and language attributes. The filtering options will be listed below, please see the screenshot for reference numbers.

  1. Set this dropdown to determine if all the following rules must be met to provision a user, or if any match should result in provisioning.

  2. Sets which attribute to use for this filter rule, City (addresses.locality) or Language.

  3. Match row if mapped Attribute Equals, Contains, or Does not contain, the value in (4)

  4. The string value to check against the Attribute (2) using the matching rule (3).

  5. Press the plus sign to add a new filter row for this location.

Setting Home Location for users provisioned in multiple locations:

In the event that your provisioning allows users access to multiple locations, you can use the “Advanced” link to open an additional filtering view. Use this view to define which users provisioned to the select Location should treat that location as Home.

Home Locations are used as the landing location if using Single Sign-On, and also where any visit created using the generic Calendar integration will be registered. The filters in the Advanced panel work identically to those in the main view.

SCIM User Provisioning requires an add on to your subscription. Contact us at support@proxyclick.com if we can assist with this integration.



Did this answer your question?