People Integration: SCIM

Problem

You would like to set up on-demand provisioning and deprovisioning of your employee data directly via your IdP/SSO provider (e.g. Okta or OneLogin).

Solution

As an admin, configure your IdP/SSO provider (e.g. Okta or OneLogin) to automatically provision and deprovision your PlusPlus users on demand via the System for Cross-domain Identity Management (SCIM) standard.

Enable SCIM

As a PlusPlus admin, go to Settings ⇒ Integrations ⇒ People ⇒ SCIM.
Make note of the following two pieces of information:
1. Base URL - typically https://<your-company>.plusplus.app/, though it could also be a custom URL that you use to access PlusPlus.
2. SCIM Token - a secret access token, that your IdP needs for authentication.
Click on the Enable SCIM toggle, to allow PlusPlus to accept SCIM requests from your IdP/SSO provider.
Optionally, configure mapping of attributes (including custom attributes) that you wish your IdP/SSO provider to send to PlusPlus. More on this below.
Click on Save.

Configure SCIM

How you configure SCIM depends on your actual IdP/SSO provider and your own level of access.

As an authorized user, log into your IdP/SSO provider
Configure SCIM integration "to app" - i.e. from IdP to PlusPlus). For example, for Okta, see Configure Okta to your SCIM API service.
Use the Base URL and the SCIM token to configure a new app.

Go deeper

Semantics

Unlike other forms of People Integration, SCIM allows for on-demand user provisioning and deprovisioning:

User creation. As soon as a new user is provisioned on your IdP/SSO provider, PlusPlus will be notified, and we will create a corresponding user on our end.
User updates. As soon as an existing user is updated on your IdP/SSO provider, PlusPlus will be notified, and we will update the corresponding user on our end.
Note: if other methods of people integration are enabled as well (e.g. Workday), then SCIM user updates will be ignored, except for user de-activation (see below).
Push deactivation. As soon as an existing user is deactivated on your IdP/SSO provider, PlusPlus will be notified, and we will start the deprovisioning process of the corresponding user on our end.

Attribute mapping

SCIM core schema already specifies a number of common attributes, and how they should be sent to apps, such as PlusPlus. That said, the PlusPlus SCIM integration allows you to re-map any of the people attributes, including the common ones, as well as map new custom attributes.

The attribute mapping is based on JMESPath expressions, a query language for JSON. This allows us to extract a relevant piece of content from the SCIM JSON-based payload, which provides quite a bit of flexibility.

To understand how this works, consider the following SCIM payload:

{
    "name": { "givenName": "John", "familyName": "Smith" },
    "title": "Senior Manager, IT",
    "active": true,
    "emails": [ {"value": "[email protected]", "primary": true } ],
    "groups": [],
    "manager": { "Manager": "100789" },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
        "WorkerType",
        "manager",
        "HireDate"
    ],
    "HireDate": { "newHireDate": "2022-08-31" },
    "userName": "[email protected]",
    "WorkerType": { "WorkerType": "Employee" },
    "externalId": "00vmhxkujuXyjxMS01z9",
    "startIndex": 1,
    "totalResults": 1,
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "department": "Education", 
        "employeeNumber": "100123"
    }
}

The extract the relevant fields, we would use the following mappings:

Name field: join(" ", [name.givenName, name.familyName])
Email field: emails[?primary].value | [0] || userName
Title field: title
Department field: "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User".department
Location field: n/a, since it's not being sent
Manager field: manager.Manager
Manager field (type): Employee ID (this tells us how to resolve the manager)
Employee ID field: "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User".employeeNumber
Employee working-since date field: HireDate.newHireDate
Person's is-active status field: active
Extra field mappings: worker_type=WorkerType.WorkerType

To see how this works in practice:

Copy the JSON blob above
Go to https://jmespath.org
Past the JSON blob into the large text box
Copy-paste individual expressions in the text input field above