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
Custom 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

Validating the integration:

To validate your SCIM settings push a user change from your SCIM system and verify that the appropriate user fields in PlusPlus are updated as desired.

To see Custom Fields you can visit a user profile and click on View Custom Attributes from the ellipsis (3-dot) menu.

Note: Users who sign in via OKTA do not need to create an account manually. As long as they can successfully authenticate, the system will automatically create their account.

For additional help with SCIM configuration please reach out to support!

People Integration: SCIM