Connecting to OKTA with SCIM v2.0

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

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

Known Limitations of OKTA SCIM support

Provisioning:

  • You cannot have an additional field inside Interact that has a questions mark (i.e. ?) 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 a question mark.

  • 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"

  • 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 this formula: Time.fromStringToIso8601(user.hiredate,"YYYY-MM-dd")

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.