People Integration: SCIM

Provision and de-provision your employee data on PlusPlus with your IdP/SSO provider (e.g. Okta or OneLogin) via SCIM.

Michael Wallace avatar
Written by Michael Wallace
Updated over a week ago

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

  1. As a PlusPlus admin, go to Settings β‡’ Integrations β‡’ People β‡’ SCIM.

  2. 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.

  3. Click on the Enable SCIM toggle, to allow PlusPlus to accept SCIM requests from your IdP/SSO provider.

  4. Optionally, configure mapping of attributes (including custom attributes) that you wish your IdP/SSO provider to send to PlusPlus. More on this below.

  5. Click on Save.

Configure SCIM

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

  1. As an authorized user, log into your IdP/SSO provider

  2. Configure SCIM integration "to app" - i.e. from IdP to PlusPlus). For example, for Okta, see Configure Okta to your SCIM API service.

  3. 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:

  1. Copy the JSON blob above

  2. Past the JSON blob into the large text box

  3. Copy-paste individual expressions in the text input field above

See Also

Did this answer your question?