Interact 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 Control Panel > Profile Sources (listed under 'Configuration, Integrations, and Advanced Settings').

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 Control Panel > Profile Sources (listed under 'Configuration, Integrations, and Advanced Settings').

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 Profile Sources area of Control Panel.

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
- As per the SCIM RFC here @https://www.rfc-editor.org/rfc/rfc7643.html additional fields must start with a letter, and only contain alphanumeric characters or underscores. When creating an additional field Interact will automatically replace space characters in the label with underscores. For example, 'Social Security Number' will have an id of 'social_security_number'.
company, department, location memberships
user types
- you can provision users as
  - Intranet Users
  - Power Users
  - Non-Intranet Users
  - etc.

Here is some guidance when using the Bio field:

Interact's SCIM process is bound by the characteristics of JSON in that all information in the Bio field must be on one line
Special characters must be converted before placed in the Bio field:
- Backspace to be replaced with \b
- Form feed to be replaced with \f
- Newline to be replaced with \n
- Carriage return to be replaced with \r
- Tab to be replaced with \t
- Double quote to be replaced with "
- Backslash to be replaced with \
- Any other control characters (U+0000 through U+001F) must be escaped as well
Here is an example that works:

The \ character cannot exist in the bio field unless it is followed by b, f, n, r, t, “ or another \ otherwise the package will error out. An example is that \’ and c:\test fail to load if part of the Bio field.
Here is an example that will not load: "bio": "These won’t work: \’ c:\test \a \c \d etc.”
Interact has not tested every example or scenario to see what will (or will not) load via the API and how it will render within the UI. The above information is meant to provide some guidance on known issues with special characters.

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)

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

Another caveat to this functionality is that the UID value cannot be a numeric value or the manager.value lookup will fail because our application cannot distinguish between lookups by personid and lookups by a numeric UID. Numeric values can include values like 1999 or even 01999, i.e. anything translatable to a numeric. So, if you have numeric UIDs, the manager lookups by UID will fail. To work around this issue, you would need to provide some type of non-numeric value along with the numeric value when you load the UID field. Examples: x1999, _01999, etc.

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 /Groups/{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/