SCIM v2.0

SCIM: System for Cross-domain Identity Management v2.0

Interact now supports SCIM v2.0 for user provisioning, group provisioning, and associated profile information provisioning for an all-in-one profile management experience, in accordance with RFC 7642, 7643, 7644.

Interact provides a number of schema extensions, to cover all profile fields, and additional profile functionality, and expose the ability to set, update them via SCIM, at the point of User updates.

There are several schemas that are supported right now by Interact.

Configuration

Profile Source Configuration

To configure Interact to accept SCIM requests, you need to add a new SCIM data source and generate an authorization token.

Create new SCIM Profile Source

As a Power User, go to Application Settings > Manage People > Manage Profile Sources.

Click SCIM.

Enter a user-friendly name, click Generate Key, and make sure the Active checkbox is checked. It is highly recommended that you also check the "Log Request Body in SCIM Service" as this will provide more verbose logging.

Keep a copy of the Authentication Token as this will be required for the setup of SCIM Provisioning in your system of record.

Retrieving SCIM Configuration Settings

As a Power User, go to Application Settings > Manage People > Manage Profile Sources.

Find the existing SCIM profile source.

You can find the Authentication Token by editing the profile source, and you can find the SCIM URL endpoint in the table (Api Url Suffix column.)

Authentication

OAuth Bearer Token-based authentication - this method is based on a generated token, which is included in the Authorization header.

Authorization: Bearer <token>

Base URL

This is the URL under which all of the core SCIM endpoints will be located.
eg. https://intranet.mysite.com/api/v2/scim/v2

Service Configuration Endpoint

The service configuration endpoint can be called to load information on supported protocols, actions, and other optional SCIM v2.0 features, in accordance with the RFC specifications.

https://intranet.mysite.com/api/v2/scim/v2/ServiceProviderConfig (requires a valid Authorization header)

📘

This information can be configured and retrieved from the Manage Profile Sources are of Application Settings.

Supported Resource Types

  • Users
  • Groups

Both of these resources support numerous extension schemas, to provide a complete experience within the Interact ecosystem.

Resource Types and associated schemas can be accessed here:
https://intranet.mysite.com/api/v2/scim/v2/ResourceTypes (requires a valid Authorization header)

Supported Schemas

Schema URN

Purpose

urn:ietf:params:scim:schemas:core:2.0:User

Core SCIM User Schema

urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Core SCIM User Schema Extension for Enterprise Users

urn:ietf:params:scim:schemas:extension:interactsoftware:2.0:User

User Schema Extension for Interact Software Users

urn:ietf:params:scim:schemas:extension:interactsoftwareadditionalfields:2.0:User

User Schema Extension for Interact Software Additional Profile Fields

urn:ietf:params:scim:schemas:core:2.0:Group

Core SCIM Group Schema

urn:ietf:params:scim:schemas:extension:interactsoftware:2.0:Group

Group Schema Extension for Interact Software Groups

Access to the schemas, and details on supported fields, descriptions, uniqueness constraints, required fields, canonical values, and other useful information, can be found here:
https://intranet.mysite.com/api/v2/scim/v2/Schemas (requires a valid Authorization header)

Alternatively, you can access all the details of a single schema on this endpoint:
https://intranet.mysite.com/api/v2/scim/v2/Schemas/{schema_urn} (requires a valid Authorization header)

User Provisioning

User provisioning, and maintenance happens via the Users resource, which is a common SCIM 2.0 endpoint.
eg. https://intranet.mysite.com/api/v2/scim/v2/Users

Interact supports the following actions against the Users endpoints.

Action (HTTP Verb)

Description

POST /Users

Create a new user.

This endpoint will attempt to match any existing users based on Username, Primary Email, or External ID (UMI UID), to avoid user duplication.

This endpoint supports setting a password for new users so that they can use local directory login - the password field won't be returned when GET endpoints are interrogated, and the password can't be updated using SCIM for existing users (for security reasons in case Auth Keys are compromised.)

GET /Users

Get all users.

Supports paging via ?startIndex=0&count=10 parameters.

Supports user filtering via ?filter=userName eq "username123" and ?filter=externalId eq "myexternalid".

Additional fields (if the user has any assigned) are also returned in this payload.

GET /Users/{id}

Get a user profile by Interact User ID.

PUT /Users/{id}

Update the user profile by Interact User ID - this endpoint will perform a replace operation, so anything not included in this payload will be wiped.

This endpoint is generally used by calling GET /Users/{id} first, applying the change, and then calling PUT /Users/{id}.

This endpoint can be called to *deactivate the users in Interact, by submitting the request with "active": false attribute.

PATCH /Users/{id}

Used for partial updates of the User.

This endpoint can be called to *deactivate the users in Interact, by submitting the request with "active": false attribute.

It can also be used to update, add, remove any piece of information on the User.

Value path, and attribute path requests are both supported.

Logical value expressions are supported on emails (type eq work), addresses (type eq home/work), phoneNumbers (type eq home/work/mobile), ims (type eq chat/skype.)

No other value expressions are supported.

DELETE /Users/{id}

Archives the user - this is an irreversible action.

Due to the available Interact Software extensions in this SCIM integration, it is possible to manage almost every aspect of the users' profile using SCIM 2.0:

  • basic profile fields
  • managerial hierarchy
  • login information
    • including setting a password for local login on user creation - this will apply password strength validation based on Interact Application Settings - where a Password Strength Regex is used, it will be evaluated using the PCRE regex engine (please be mindful of the supported syntax, and use online PCRE regex validators before applying a regex.) The SCIM User POST endpoint will return regex validation messages in case of invalid/incompatible regex being detected. https://pcre.org/pcre.txt <- official PCRE regex specification
  • additional fields
    • can be configured in Application Settings, to extend the profile with custom fields which can then be populated via SCIM
  • company, department, location memberships
  • user types
    • you can provision users as
      • Intranet Users
      • Power Users
      • Non-Intranet Users
      • etc.

Manager Relationships

Normally, SCIM expects the manager.value field to contain a SCIM User ID to an already provisioned user.

Many systems support this correctly and maintain value maps internally to ensure the correct Manager ID is sent with any user creation, and update requests - eg. Azure AD, OneLogin etc.

There are some systems that do not offer out-of-the-box support for SCIM compatible Manager ID resolutions - usually due to other constraints in the systems, such as no native support for organizational structures, or linked user-profiles - eg. Okta.

This then makes the integration, a lot less seamless and requires automation to be built by the customer to "crowbar in" the right Manager IDs against the profiles. This is a pain to build, and maintain.

Interact's SCIM integration has expanded on the 'official' support for manager.value support, and it will analyse the value, to determine if it is a SCIM User ID first, and if not, it will take the value and attempt the look up any existing user using their:

  • Primary/Work Email
  • Username
  • ExternalID (UMI UID)

The caveat to this functionality is, that the lookup select * users where email=value or username=value or externalid=value must return exactly 1 user. If more than 1 user is matched, the manager assignment (and the call) will fail.

This support offered by Interact's SCIM interface allows for organizational structures to be synced from systems that natively struggle with such concepts, or don't provide a comprehensive SCIM support, as long as manager.value can be set to a unique identifier for an already provisioned user.

Group Provisioning

Group provisioning, and maintenance happens via the Groups resource, which is a common SCIM 2.0 endpoint.
eg. https://intranet.mysite.com/api/v2/scim/v2/Groups

Interact supports the following actions against the Groups endpoints.

Action (HTTP Verb)

Description

POST /Groups

Create a new group, of a specific type.

This endpoint will attempt to match any existing groups based on Name, or External ID (UMI UID), to avoid group duplication.

GET /Groups

Get all groups.

Supports paging via ?startIndex=0&count=10 parameters.

Supports group filtering with ?filter=displayName eq "groupname" and ?filter=externalId eq "myexternalid".

members property is not populated on this endpoint - to get group members, you need to call GET /Groups/{id} endpoint.

GET /Groups/{id}

Get a group by Interact Group ID.

PUT /Users/{id}

Update the group by Interact Group ID - this endpoint will perform a replace operation, so anything not included in this payload will be wiped.

This endpoint is generally used by calling GET /Groups/{id} first, applying the change, and then calling PUT /Groups/{id}. This can be a heavy operation, as this payload accepts and respects, the members attribute, and will update the memberships accordingly.

PATCH /Groups/{id}

Updates the group by Interact Group ID - this endpoint accepts a set of operations, such as "add member 123", or "remove member 456", instead of accepting a whole object.

This makes this endpoint really efficient for Group membership operations.

This endpoint only supports add, remove, and replace operations on all mutable properties.

Logical value expressions are supported for members property and support filtering by the member value field.

No other value expressions are supported.

DELETE /Groups/{id}

This endpoint deletes the group, and all associated memberships - this operation is irreversible.

Due to the available Interact Software extensions in this SCIM integration, it is possible to manage Interact specific properties of groups, including group types such as:

  • company
  • department
  • location
  • security group

You can also use these endpoints to view the memberships of a Persona created in Interact, as personas are returned in the API.

Other Resources

http://www.simplecloud.info/