Before following this guide, log into Interact as a power user and follow the instructions here to generate the tokens required for SCIM setup.

📘NOTE

OKTA's Lifecycle Management (LCM) product is required in order to utilize SCIM provisioning.

Configuring OKTA SCIM Application

Log into Okta with administrative rights.
Select Admin at the top right of the Okta app dashboard to enter the admin dashboard if you aren’t already there.
On the left panel expand Applications then select the Applications sub-option
In the main panel select Browse App Catalog
On the Browse App Integration Catalog window search for SCIM 2.0 Test App (OAuth Bearer Token) and select it once found
Select Add Integration
Change the application label to whatever you would like e.g. Interact - SCIM
(Optionally untick the Automatically log in when user lands on login page box)
Select Next
On the next page you can configure SAML options for Interact, you will need the details from the SAML configuration in Interact see here or leave blank if you wish to only use this test app for SCIM
Click Done
Select the Provisioning tab and click on Configure API Integration
Tick the Enable API Integration box
Enter the SCIM URL for your domain e.g. https://<Tenant URL>/api/v2/scim/v2/ where <Tenant URL> is your Interact site domain
Enter the OAuth token generated for the SCIM source in interact
Click Save

Adding Attributes

Before any users are assigned you will need to edit the application profile for this application as there is two attributes that are required for Interact that is not included in the base SCIM schema.
On the left panel expand Directory then select Profile Editor
Find the profile that has the name of the SCIM app we just created e.g. Interact - SCIM User
Click on the Name of this profile
Select + Add Attribute
Select/Enter the following information (Leave non declared values as default)

Data Type: string
Display Name: Location
Variable Name: Location
External Name: location (case sensitive)
External Namespace: urn:ietf:params:scim:schemas:extension:interactsoftware:2.0:User
Description: Identifies the name of the location
Attribute Required: True/Ticked

Repeat the process to the the Authentication type in Interact, especially if you are using SAML, if this is not mapped the users will be created as Local Directory users.
Select/Enter the following information (Leave non declared values as default)

Data Type: string
Display Name: loginType
Variable Name: loginType
External Name: loginType (case sensitive)
External Namespace: urn:ietf:params:scim:schemas:extension:interactsoftware:2.0:User
Description: Identifies the name of the location
Attribute Required: True/Ticked

Click Save

📓Note

The previous process is for the only required attribute by the interact SCIM schema. If you wish to populate other optional interact attribute you can follow the previous two steps for any additional attribute. More information on the Interact SCIM schema can be found here

Now we need to map a value into this attribute, this is a required field in Interact.

Mapping Attributes

Select Mapping and map both of these Attributes
Select the Okta User to APPNAME tab, where APPNAME is the name previously declared.
At the bottom of this list you should find the location attribute that we have just added. Map an Okta user attribute into this field that corresponds to the locations you wish to map into Interact.
For the Location map something like:
For the loginType map as below:

Interact requires the mapping of some mandatory fields, full details can be found here . These include the Department, Location and Company, to aid this, and ensure that empty values are not passed from OKTA to Interact, it is recommend to use expressions in the mapping from OKTA to Interact.
To do this change the mappings to use expressions similar to the below
Organisation

Using an expression similar to this, where in this case the value will be "Company - Not Specified" if the field in empty in OKTA.

user.organization == null || user.organization == "" ? "Company - Not Specified" : user.organization

Location

Using an expression similar to this, where in this case the value will be "Location- Not Specified" if the field in empty in OKTA.

user.city == null || user.city == "" ? "Location - Not Specified" : user.city

Department

Using an expression similar to this, where in this case the value will be "Department- Not Specified" if the field in empty in OKTA.

user.department == null || user.department == "" ? "Department - Not Specified" : user.department

Optionally preview with an okta user to confirm the values are what you want them to be. This is also a great time to make any other attribute mapping adjustments you wish to make.
Click Save Mappings
Now set the Provisioning of the Application. On
Now you should be able to assign users to the SCIM application and test SCIM provisioning into Interact

Adding SAML to this Application

You can use this application in OKTA to provide single sign-on via OKTA.

You will need to setup the SAML settings from your Interact site as per Configure SAML Single Sign-On.
Once you have completed this, click on the Sign On tab of the application, set this to SAML, and enter the following details in the

ACS URL: https://<Tenant URL>/Interact/Login/default.aspxwhere Tenant URL is your Interact Site domain (for example https://intranet.interactgo.com/Interact/Login/defaults.aspx)
Audience URL: http://<Entity ID> where Entity ID is the entity ID created when setup SAML you obtained from the Interact Site in step 1 above, generally in the format of http://intranet.interactgo.com/saml-sp)

You can then copy this Metadata URL from this page in OKTA and import this as details in Configure SAML Single Sign-On

Notes and Troubleshooting

Make sure to utilize the Logging provided by OKTA. This will be your only way of checking if you have synchronization issues.
Interact's SCIM implementation has been designed to be extremely verbose and provide necessary context with all errors, to ensure you have everything needed to resolve any issues.
You can check if the SCIM service is functional by opening your browser and using https://{yourURL}/api/v2/scim/v2/health. You might want to check this if you receive any errors.
Errors will mention issues with specific attributes. eg.
- Bad value type for attribute X
- Missing attribute Y
- Value in attribute Z does not comply to a required format (.....)
- etc.
If the manager sync functionality is not working while you are testing this functionality, you need to ensure that the manager is part of the users being synced. The reconciliation of the manager information has to happen on the OKTA side not within Interact... so the manager is required to be part of the OKTA Provisioning.
If you receive "Work phone number attempted to be set twice", the work-around is as follows:

**remove these mappings:
phoneNumbers.^[primary==true].type
phoneNumbers.^[primary==true].value

**add this mapping:
phoneNumbers.^[type=='work'].value

Known Limitations of OKTA SCIM support

Provisioning:

You cannot have an additional field inside Interact that has a questions mark (i.e. ?) or other special characters in the field name or the process will not work. You will receive an Error 500 when trying to perform any activity within SCIM until the issue is resolved. You will need to remove the field completely and recreate it without special characters.
OKTA will not push an item to Interact if it is null. So effectively it uses logic similar to Interact's "ApplyBlank" logic for all fields. The "default value" field only works on the initial sync but doesn't help with subsequent syncs. This causes an issue when you are dealing with required fields.
If you have an issue where Power User permissions are being removed, you need to add the urn:ietf:params:scim:schemas:core:2.0:User:userType field to the OKTA sync and provide one of these values for each user:
"Power User",
"Intranet User",
"Non Intranet User"

In order to avoid this, you can create an OKTA group (e.g. "Interact Power Users") with those users and then add an expression to the userType field: isMemberOfGroupName("Interact Power Users") ? "Power User" : "Intranet User"

If you already ran an sync and wiped Power User access, you will need to manually re-add this permission for your users.
If you have an issue where duplicate users are being created because you had a set of users already existing within Interact, you need to add both email and username as lookup fields within OKTA.
If you want to add a start date, use a formula like this: String.append(user.startDate,"T01:00:00Z")
If you want to map the address, you need to map to the Interact field "formatted" which should be automatically added as a target and use a formula like this:
user.streetAddress + ", " + user.city + ", " + user.state + " " + user.zipCode
If users are inactive within Interact, you must set the Active field to true to force it back to an active state. This can be accomplished by always setting the Active field to true since Deactivating users is a separate process.
Many customer have a desire to leverage preferred name if it is populated in OKTA and firstname if preferredname is not populated in OKTA. Interact doesn't directly support a PreferredName field though you can add it as an additional field; however, if you want to populate Interact's firstname with the preferredname field when it has a value and Interact's firstname field when preferredname is null, then use this formula: IIF(ISNULL([preferredname]),[firstname],[preferredname]) This expression says if the OKTA “preferredname” is null, then populate Interact’s firstname field with the “firstname” but if OKTA’s “preferredname” record is not null (i.e. it has a value), then populate Interact’s firstname field with the “preferredname” from OKTA.
A caveat to the manager lookup 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.
There is an option at the field mapping level to "Create Only". This option allows you to map a field upon the creation of a user, but then allows a user to adjust the field in their Interact profile without Azure overwriting the field on a subsequent sync. This is useful for fields like Language, Culture and even Primary Company/Department/Location.

Deprovisioning:

If a user that was previously managed by the provisioning service is unassigned from an app, or from a group assigned to an app we will send a disable request. At that point, the user is not managed by the service and we will not send a delete request when they are deleted from the directory.
Provisioning a user that is disabled in OKTA is not supported. They must be active in OKTA before they are provisioned.
When a user goes from soft-deleted to active, the OKTA provisioning service will activate the user in the target app, but will not automatically restore the group memberships. The target application should maintain the group memberships for the user in inactive state. If the target application does not support this, you can restart provisioning to update the group memberships.