GuidesAPI Reference
Guides

OKTA (OLD)

Log into Interact as a power user and follow the instructions here to generate the tokens
required for SCIM setup.

Also, you will need OKTA's Lifecycle Management (LCM) product in order to utilize SCIM provisioning. If you don't have it, you will not see the Provisioning tab on Step 10 below.

Steps Needed within OKTA

  1. 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.
  2. On the left panel expand Applications then select the Applications sub-option
  3. In the main panel select Browse App Catalog
  4. On the Browse App Integration Catalog window search for SCIM 2.0 Test App (OAuth Bearer Token) and select it once found
  5. Select Add
  6. Change the application label to whatever you would like e.g. Interact - SCIM
    b. Optionally untick the Automatically log in when user lands on login page box
  7. Select Next
  8. On the next page you can configure SAML options for Interact or leave blank if you wish to only use this test app for SCIM
  9. Done
  10. Select the Provisioning tab
  11. Configure API Integration
  12. Tick the Enable API Integration box
  13. Enter the SCIM URL for your domain e.g. https://interactbaseURI/api/v2/scim/v2/ where interactbaseURI is your Interact site domain
  14. Enter the OAuth token generated for the SCIM source in interact
  15. Save
  16. Before any users are assigned you will need to edit the application profile for this application as there is one attribute that is required for Interact that is not included in the base SCIM schema.
    a. On the left panel expand Directory then select Profile Editor
    b. Find the profile that has the name of the SCIM app we just created e.g. Interact - SCIM User
    c. Click on the Name of this profile
    d. Select + Add Attribute
    e. Select/Enter the following information (Leave non declared values as default)
    i. Data Type = string
    ii. Display name = Location
    iii. Variable name = (up to you)
    iv. External name = location
    v. External namespace = urn:ietf:params:scim:schemas:extension:interactsoftware:2.0:User
    vi. Description = Identifies the name of a location.
    vii. Attribute required = True/ticked
    f. Save
    i. As a 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.
    g. Now we need to map a value into this attribute as it is a required attribute. Select Mappings
    h. Select the Okta User to APPNAME tab, where APPNAME is the name previously declared
    i. 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. 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.
    j. Save Mappings
  17. Now you should be able to assign users to the SCIM application and test SCIM provisioning into Interact

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 have a field like location that is required, you can ensure that something is passed every time with an expressions like this: user.city != null && user.city != "" ? user.city : 'default'

  • 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 Azure expression says if the OKTA “preferredname” is null, then populate Interact’s firstname field with the “firstname” from Azure… 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.

Updated 10 days ago