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 Clarizen One.
Provisioning tools are used to automate onboarding, offboarding, and other administration workforce processes, for example; new hires, transfers, promotions, and terminations.
Clarizen One has previously offered an AD User Sync installable Windows package to automate the provisioning of groups of users to Clarizen One.
Benefits
With Clarizen’s cloud-based user provisioning it is possible to create users and groups directly inside OKTA and “push” (provision) them to Clarizen using the SCIM (System for Cross-Domain Identity Management) protocol.
This functionality complements Clarizen’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 Clarizen
- Picking up existing Clarizen 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
- 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 Clarizen.
- 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 Clarizen - 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 Clarizen
- When a synced user is removed from a sync group, suspend such a user in Clarizen
- When a synced user is disabled in OKTA, suspend such a user in Clarizen
- When a synced user is deleted from OKTA, delete such a user in Clarizen
- Currently, Clarizen 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 Clarizen customers.
Configuration Instructions in Okta
Adding the Clarizen One App
Log into your Okta admin portal and complete the following steps:
- In OKTA, go to Applications.
- Click Add Application.
- Search for the Clarizen One application:
- Click Add.
- Inside the newly created app, begin the setup wizard.
- Under Advanced Sign-on Settings, enter the Base URL as follows:
- For the US Production data center: https://servicesapp2.clarizen.com/scim/v2
- For the EU Production data center: https://serviceseu1.clarizen.com/scim/v2
- For the US Sandbox data center: https://servicesapp.clarizentb.com/scim/v2
- For the EU Sandbox data center: https://serviceseu.clarizentb.com/scim/v2
- Click Done.
- Open the Provisioning tab, and click Configure API Integration.
- Click Enable API Integration.
- Enter the Base URL (see above).
- Enter the API Token.
Clarizen provides a dedicated API Key mechanism to authenticate SCIM-based user provisioning service. Refer to the API Key article on success.clarizen.com for instructions on how to generate an API Key for your newly created application. Once you get a key, simply paste it inside the OAuth Bearer Token field. - Click Test API Credentials Connection and verify that the connection is working.
Click Save.
Best Practices
- Creation of users and groups in Clarizen 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 Clarizen instance, where the key was generated. This way Clarizen knows which instance to provision users and groups to. If you use multiple OKTA applications to provision several Clarizen instances, make sure you use the right key in each application.
Enable Provisioning Functionality
- Under the Provisioning tab, for Provisioning to App, click Edit.
- Enable Create Users, Update User Attributes, and Deactivate to allow users to be automatically provisioned, updated, and deprovisioned in Clarizen.
- Click Save.
Set Up Mappings
Under the Provisioning tab, scroll down to the Clarizen One Attribute Mappings section and click Go to Profile Editor.
Although Clarizen supports the entire list of default attributes (see Initial Setup in Clarizen for more details), it is recommended to review the list of attributes and delete those that you won’t be using in your integration:
Once you have finished reviewing the attributes, click Mappings at the top.
Click Okta User to Clarizen One 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 Clarizen instance. Save any changes you make:
Refer to the Best Practices section below for more information about picking up existing Clarizen 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:
Initial Setup in Clarizen
Predefined standard fields (see Features section above) are automatically mapped. However, Clarizen allows changing some of the predefined mappings or adding new ones.
In Clarizen, log in with an admin account, and go to Settings → Extensions. Locate the User Provisioning section:
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 Clarizen:
The first few mappings are read-only and cannot be changed.
The rest of the mappings can be changed by clicking the corresponding item (on both sides) and selecting an alternative value from the list:
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 Clarizen.
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 Clarizen using an intermediate mapping to a textual custom field, which triggers a workflow rule to map it further to an object in Clarizen
You can also delete unnecessary mappings or restore default mappings if needed:
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 Clarizen
- When a synced user is removed from a sync group, suspend such a user in Clarizen
- When a synced user is disabled in OKTA, suspend such a user in Clarizen
- When a synced user is deleted from OKTA, delete such a user in Clarizen
Best Practices
Picking up Existing Accounts in Clarizen
There can already be existing users or groups in Clarizen 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:
- 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 Clarizen
- 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 Clarizen
If required, you can create a custom action (“update field” action on User entity) in Clarizen to update the user names of existing users.
Mapping to Objects in Clarizen
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:
- First, map the attribute to an intermediate textual custom field in Clarizen.
Note: For the “Title” attribute, there is a dedicated standard field (“Scim Sync Job Title”) that exists for this purpose.
- Every time the intermediate field in Clarizen 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 Clarizen.
Provisioning to Multiple Clarizen Instances
It is possible to provision several Clarizen 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 Clarizen instance
- You need to specify the correct URL and Secret Token for each Clarizen Instance in its dedicated application (see Setting Up 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 Clarizen instance. If a user does not exist in this particular Clarizen instance, OKTA will try to create the user in Clarizen.
However, it may happen that, when Clarizen tries to create the user, it will become evident that such a User Name already exists in another Clarizen 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:
- By viewing the provisioning log in OKTA:
Example of an audit log from OKTA:
- By going to Change History in Clarizen settings:
Comments