This article explains the steps needed to implement User Provisioning (hereafter UP) through our generic SCIM connector. These instructions assume that the person implementing the guide is familiar with the SCIM specification and will only detail the information relevant to Proxyclick’s implementation of SCIM. Further, it is assumed that the implementer has already created or configured the means to push directory data outbound via SCIM and only needs the information on what attributes are supported. We will first explain how to use SCIM to provision a single location, then how to extend the setup if you are using Proxyclick in multiple locations.

Requirements:

  • Plan Large or Enterprise
  • Administrator access to Proxyclick (for all locations to be provisioned)

Setting up Generic SCIM in 1 single Location:

Step 1: Install the Proxyclick Generic SCIM Integration

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. Proxyclick only supports the /Users data type, and will not accept calls to /Groups.

Proxyclick supports the following SCIM Attributes:

Base Attribute SubAttribute Attribute Data Type Required
userName string true
name formatted string false
name familyName string true
name givenName string true
emails type:work string true
phoneNumbers type:mobile string false
phoneNumbers type:work string false
addresses locality string false
title string false
preferredLanguage string false
active boolean true

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.164 format. 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 count parameter (max 5,000) to determine how many users appear per page, and the startIndex parameter 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.

Print Friendly, PDF & Email