Skip to main content
Language Selector

  1. Other Languages

    (machine translation)

Planview Customer Success Center

Cloud-Based User Provisioning with OKTA

  1. Last updated
  2. Save as PDF

Background

User provisioning is the process by which organizations create, modify, disable, and delete user accounts and their profiles across IT infrastructure and business applications, such as AdaptiveWork.

Provisioning tools are used to automate onboarding, offboarding, and other administration workforce processes, for example; new hires, transfers, promotions, and terminations.

AdaptiveWork has previously offered an AD User Sync installable Windows package to automate the provisioning of groups of users to AdaptiveWork.

Benefits

With AdaptiveWork’s cloud-based user provisioning it is possible to create users and groups directly inside OKTA and “push” (provision) them to AdaptiveWork using the SCIM (System for Cross-Domain Identity Management) protocol.

This functionality complements AdaptiveWork’s existing SSO (Single-Sign-On) solution to provide a complete Federated Authentication suite.

Features

  • API key mechanism to authenticate SCIM-based user provisioning service
  • Provisioning (creation, updating, and deletion) of users and groups in AdaptiveWork
  • Picking up existing AdaptiveWork users to be managed by OKTA
    Note: Subject to proper configuration in OKTA
  • Automatic mapping of predefined standard fields and entities:
    • User Name
    • Display Name
    • Email
    • First Name
    • Last Name
    • Office Phone
    • Mobile Phone
    • Direct Manager
    • Job Title
      Note: The automatic mapping is to an internal text field. It will require an additional workflow rule to further map it to the corresponding Job Title in AdaptiveWork.
  • Ability to include additional fields (string only) in the automatic mapping
    Examples: “Country”, “Department”, etc. attributes may require adding custom fields and workflow rules to ensure proper mapping to a target entity in AdaptiveWork
  • Hard-coded “best provisioning practices”:
    • Do not send invitation emails automatically
    • If a user’s Direct Manager is not included in the sync group, do not add it to AdaptiveWork
    • When a synced user is removed from a sync group, suspend such a user in AdaptiveWork
    • When a synced user is disabled in OKTA, suspend such a user in AdaptiveWork
    • When a synced user is deleted from OKTA, delete such a user in AdaptiveWork
  • Currently, AdaptiveWork does not support the following Okta provisioning features, but may in the future:
    • Import groups
    • Import users
    • Sync password
    • Profile master

Requirements

SCIM-based user provisioning is available to all Enterprise and Unlimited Edition AdaptiveWork customers.

Configuration Instructions in Okta

Adding the AdaptiveWork App

Log into your Okta admin portal and complete the following steps:

  1. In OKTA, go to Applications.
  2. Click Add Application.
  3. Search for the AdaptiveWork application:
    1.png
  4. Click Add.
  5. Inside the newly created app, begin the setup wizard.
  6. Under Advanced Sign-on Settings, enter the Base URL as follows:
    clipboard_e9c73031536860f314708bbe2390f964c.png
  7. Click Done.
  8. Open the Provisioning tab, and click Configure API Integration.
  9. Click Enable API Integration.
  10. Enter the Base URL (see above).
  11. Enter the API Token.
    AdaptiveWork provides a dedicated API Key mechanism to authenticate SCIM-based user provisioning service. Refer to the API Key article for instructions on how to generate an API Key for your newly created application. Once you obtain a key, paste it into the OAuth Bearer Token field.
  12. Click Test API Credentials Connection and verify that the connection is working.
  13. Click Save.

Best Practices

  • Creation of users and groups in AdaptiveWork will be made on behalf of the integration user, which is used to generate the API Key. Therefore, make sure to give the integration user at least Lite Admin privileges.
  • The API Key contains information about a AdaptiveWork instance, where the key was generated. This way AdaptiveWork knows which instance to provision users and groups to. If you use multiple OKTA applications to provision several AdaptiveWork instances, make sure you use the right key in each application.

Enabling Provisioning Functionality

  1. Under the Provisioning tab, for Provisioning to App, click Edit.
    clipboard_e142c8f6d63c4a9886cffe24f2cccba21.png
  2. Enable Create Users, Update User Attributes, and Deactivate to allow users to be automatically provisioned, updated, and diprovisioned in AdaptiveWork.
  3. Click Save.

Set Up Mappings

  1. Under the Provisioning tab, scroll down to the AdaptiveWork Attribute Mappings section and click Go to Profile Editor.
  2. Although AdaptiveWork supports the entire list of default attributes (see Initial Setup in AdaptiveWork for more details), it is recommended to review the list of attributes and delete those that you won’t be using in your integration:

attributes.png

 

Once you have finished reviewing the attributes, click Mappings at the top.
mceclip5.png
Click Okta User to AdaptiveWork tab and review the attributes’ mappings. This mapping defines how the internal OKTA attributes are mapped into standard SCIM attributes, which will be visible in your AdaptiveWork instance. Save any changes you make:
 

clipboard_ee62031e8d950ed275555de3b9f2226d3.png

Refer to the Best Practices section below for more information about picking up existing AdaptiveWork accounts or SSO-related considerations.

Assign Users and Groups

At this stage you can select which users and groups (out of all existing users and groups in your OKTA account) will be provisioned by the newly created application. This operation is frequently referred to as “Assigning to a sync group”.

Open the Assignments tab and select People and/or Groups:

clipboard_e4e7936901ceca09f63ebd8e2525002bb.png

 

Initial Setup in AdaptiveWork

Predefined standard fields (see Features section above) are automatically mapped. However, AdaptiveWork allows changing some of the predefined mappings or adding new ones.

  1. In AdaptiveWork, log in with an admin account, and go to Settings → Extensions. Locate the User Provisioning section.
  2. Click Setup to view and define how the user attributes are mapped from your newly created application in OKTA to the User entity fields in AdaptiveWork:
  3. The first few mappings are read-only and cannot be changed.
  4. The rest of the mappings can be changed by clicking the corresponding item (on both sides) and selecting an alternative value from the list:
  5. You can add new mappings by clicking Add New Mapping, if needed. It is possible to add mappings to any standard or custom field on the User entity in AdaptiveWork.
    Notes:
    • Only mapping to textual (string) fields is supported
    • Refer to the Best Practices below for more information on how to provision ‘reference to objects’ fields in AdaptiveWork using an intermediate mapping to a textual custom field, which triggers a workflow rule to map it further to an object in AdaptiveWork
  6. You can also delete unnecessary mappings or restore default mappings if needed.
  7. Click Save when done.

Default Provisioning/Deprovisioning Rules

During the User Provisioning process, the system will execute the following provisioning / deprovisioning rules:

  • Do not send invitation emails automatically
  • If a user’s Direct Manager is not included in the sync group, do not add it to AdaptiveWork
  • When a synced user is removed from a sync group, suspend such a user in AdaptiveWork
  • When a synced user is disabled in OKTA, suspend such a user in AdaptiveWork
  • When a synced user is deleted from OKTA, delete such a user in AdaptiveWork

Best Practices

Picking up Existing Accounts in AdaptiveWork

There can already be existing users or groups in AdaptiveWork from before - either provisioned manually or by using the AD Sync tool.

If you need such existing users and groups to be “picked up” (become provisioned) by OKTA when you switch to cloud-based user provisioning, you will need to ensure the following:

  1. The names of the groups that are assigned to your user provisioning application in OKTA must be the same as the names of already existing groups in AdaptiveWork
  2. The value of the userName attribute of users, which will be provisioned by OKTA (defined by the mapping you define - see Set Up the Mappings), is identical to the User Name of the existing user accounts in AdaptiveWork

If required, you can create a custom action (“update field” action on User entity) in AdaptiveWork to update the user names of existing users.

Mapping to Objects in AdaptiveWork

The best practice around mapping OKTA’s user/group attributes to objects inside Clarien (e.g. Job Title, User Groups, etc.) is to do it in two stages:

  1. First, map the attribute to an intermediate textual custom field in AdaptiveWork.
    Note: For the “Title” attribute, there is a dedicated standard field (“Scim Sync Job Title”) that exists for this purpose.
  1. Every time the intermediate field in AdaptiveWork is updated with a new value from OKTA, it can trigger a workflow rule, which will further link the corresponding user to the desired object in AdaptiveWork.

Provisioning to Multiple AdaptiveWork Instances

It is possible to provision several AdaptiveWork instances from a single OKTA account. These are the basic guidelines to keep in mind:

  • There needs to be a dedicated enterprise application (connecter) in OKTA for each AdaptiveWork instance
  • You need to specify the correct URL and Secret Token for each AdaptiveWork Instance in its dedicated application (see Enabling Provisioning)

Gradual Rollout

Automatic user provisioning is very powerful at scale.

However, since it requires careful planning and quite an extensive configuration, we recommend starting small in a controlled environment (Sandbox, Testing, etc.) and checking every step, as well as every critical scenario (such as picking up existing accounts) you need to support.

Troubleshooting

Duplications and Conflicts

During provisioning cycles, the OKTA portal checks whether each assigned user already exists in the target AdaptiveWork instance. If a user does not exist in this particular AdaptiveWork instance, OKTA will try to create the user in AdaptiveWork.

However, it may happen that, when AdaptiveWork tries to create the user, it will become evident that such a User Name already exists in another AdaptiveWork instance. In this case, the user-creation process will fail. Such a failure will be listed in the provisioning log in OKTA.

Provisioning Logs

There are two ways to monitor/debug the user provisioning process:

  1. By viewing the provisioning log in OKTA:

clipboard_eda238241fab1da32e40e4acd438162ae.png

 

 

Example of an audit log from OKTA:

mceclip8.png

  1. By going to Change History in AdaptiveWork settings.