Automated User Provisioning with Active Directory

Overview

Clarizen Active Directory Sync Agent is a User Provisioning tool that automates the synchronization of your network’s selected Windows Server Active Directory groups and users into your Clarizen organization. It has not been designed or tested to work with “Azure AD” user provisioning services.

Once users have been provisioned (added to Clarizen), you may want them to authenticate (SSO) using Azure Active Directory. 

For more about SSO (Federated Authentication) setup and configuration, use one of the following links:

Watch a video tutorial

 

Contents

Architecture

Downloading and Installing the Sync Agent

Migrating Users from Active Directory Sync v1

Setting Up Connections to Clarizen and Active Directory

Connection to Clarizen

Connection to Active Directory

Setting up Field Mappings

Adding Additional Groups

Verifying Additional Settings

Selecting a Group to Test

License Types

New User Invitations

New User Added Notifications to Administrators

Sync Scenarios

How Active Directory User Sync initially matches Users & Groups

Sync Now

Recurring Scheduled Sync

Special Case Handling

Job Title Sync

Direct Manager Sync Setting

Deactivating Users in Clarizen

Viewing Log Files

Monitoring

Monitoring Sync Changes

Monitoring when the Sync Last Ran

Limitations

Supported Groups & Users

Duplicate Group Names & Users emails/SID’s

Users without an email address

Number of Groups

Group Size

User Management Settings in Clarizen 

 

Architecture

The Clarizen Active Directory User Sync Agent application is comprised of 2 functional elements:

  • Clarizen Active Directory User Sync Agent - the configuration screens
  • Clarizen Active Directory User Sync - the sync engine that can be scheduled

 

 

 

Downloading and Installing the Sync Agent:

Installation Pre-Requisites

Before configuring the integration, make sure that you have:

  1. Ability to install Programs on your Windows PC
  2. Administrative privileges for your Clarizen environment
  3. Privileges for your company’s Active Directory Federation Services.
  4. .Net 4.6.2 or above
  5. Network access to Clarizen API (port:443)
  6. Network access to you company's Active Directory 

 

Note: Whilst you do not need Active Directory Administrator privileges to run the Sync Agent, it is recommended to be accompanied by an Active Directory Administrator as some Active Directory fields have short names, which may not be recognizable to you should you want to add them to your sync mapping.

 

Installation

  1. Download the .msi file from the Clarizen Apps Marketplace  
  2. Run the .msi installer file to install the Clarizen Active Directory Sync Agent, which is comprised of 2 main elements:
    1. ClarizenADSyncSettings - Run this first to set up connections to Active Directory and Clarizen for Groups and field mappings
    2. ActiveDirectorySyncEngine- This is the engine that runs the sync and can be scheduled to run on an ongoing basis using Windows Task Scheduler




    3. Once you have installed the initial .msi package, navigate to
          Program Files (x86) > Clarizen > ActiveDirectorySync
      and run ClarizenADSyncSettings to finish the installation process.

  3. You can schedule the Sync using Window Task Manager (detailed later in this article).
    If you wish to do so, you should install the .msi package as the same user that you plan to run the scheduled sync with. 
  4. For advanced configuration details, please contact your Clarizen Customer Success Manager. 

Migrating Users from Active Directory Sync v1

If you have not previously set up Clarizen Active Directory User Sync, you may skip this section.

V2 introduces a number of key improvements including:

  • Simpler Install
  • Support for AD Forest (multiple AD domains)
  • Simpler User Interface
  • Sync of Direct Manager
  • Support User Re-Provisioning
  • Improved Performance & Scalability
  • Improved Stability
  • Improved Logging

 

If you are using v1 and are satisfied, there is no need to migrate immediately or change your processes and it will continue to sync. However, no further updates are planned for the v1 version.

 

 

Simpler Install

Previously the Active Directory sync relied on custom fields to work:

SSOKey, SSONotes, SSOUpdated.

 

v2 uses standard fields so no additional installations are required. 

Item Type

Old Custom Field

New Standard Field

User, User Group

SSOKey                           --------------->

User Sync ID

User, User Group

SSOUpdated                     --------------->

User Sync Updated

User, User Group

SSONotes                         --------------->

User Sync Notes

Organization

SSO last update date         --------------->

User Sync Updated

 

You can migrate to the new app by installing a migration utility app that copies over the SSOKey to User Sync ID field if:

  1. You are currently using the v1 AD User Sync app,
    and
  2. you are using SID as the primary user key between AD and Clarizen, 

This is all that is needed to ensure the new sync does not create duplicate users and groups.

 

Note: If you have not been using SID as the primary user key, please discuss with your Customer Success Manager to explore your migration options.

 

Using the Migration App

To migrate SID from SSOKey to User Sync ID fields, install the Migration app and run it before running your sync

  1. Download the Migration App and activate it.
  2. 2 new Custom Actions will now be available:
    • People module: AD Sync v2 Migration Tool - Users
    • User Groups module: AD Sync v2 Migration Tool - Groups
  3. Select the Users you currently sync by filtering on the SSOKey field.
  4. Use the Custom Action to copy the field values for the users you want to continue to sync. It can be used on up to 50 users / groups at a time. If you have thousands of affected users, consider saving the Custom Action as a Scheduled Workflow Rule and run it before running the Clarizen Active Directory Sync Agent.
  5. Run Clarizen Active Directory Sync Agent on your Windows machine.
  6. Once you have verified results, you can delete the custom (“SSO”) fields from Clarizen.
  7. Remove any scheduled sync tasks of the old app from your Windows machine.

 

"Marooned" Deprovisioned Users

v2 adds the capability to delete or disable users in Clarizen.

If a user has a User Sync ID in Clarizen and is not found in a sync Group in Active Directory, they will be deleted/ suspended and their license released. 

If you have users that were previously synced by v1 and should now be disabled in Clarizen you can either: 

  1. take care to also use the Migration Tool to copy their SSO ID to User Sync ID field.
    Once this this is done, the Sync Process will correctly identify them to disable and will release any licenses still assigned to them. 
  2. Manually disable/ suspend the users in Clarizen

If you do not take either of these steps, these users will be left untouched by the sync process in Clarizen and will not be deprovisioned.

 

Setting Up Connections to Clarizen and Active Directory

Connection to Clarizen

User Management in Clarizen is performed by users with Administrator permissions. You will connect to Clarizen using your Administrator username and password.

You can only set 1 Clarizen connection, and it is recommended to first use a Sandbox connection to verify that the sync works as expected with all the relevant groups, users and field values.

Sandbox

Choose the Sandbox option in Account Credentials > Clarizen connection. Add your username and password, and check the connection.

 

Production

Choose the Production option in Account Credentials > Clarizen connection. Add your username and password, and check the connection.

 

Selecting Sandbox or Production account to connect

 

Selecting up all Account Credentials

 

Connection to Active Directory

Clarizen Active Directory User Sync connects directly to multiple Active Directory domains and does not connect to or use a Global Catalog.

Add one or more Microsoft Active Directory servers (domains).

  1. Click Account.
  2. Enter your Clarizen Username and Password. Click Check to validate the connection.
  3. Enter your Active Directory Domain, Username and Password. Click Check to validate the connection.
  4. If you want to add additional domains, click + Add Domain and enter your Active Directory credentials.
  5. Click Save.  

 

Setting up Field Mappings

Add, remove and update Active Directory-to-Clarizen field mappings.

  1. Click Field Mapping.
  2. The following default field mappings appear in the list. 

    User

    Active Directory

    Clarizen

    givenName

    FirstName

    sn

    LastName

    title

    JobTitle

    manager

    DirectManager

    telephoneNumber

    OfficePhone

    mobile

    MobilePhone

    displayName

    DisplayName

    Groups

    Active Directory

    Clarizen

    name

    name

    displayName

    DisplayName


    1. To edit a field, select the Users or Groups tab. Open the relevant drop-down list to select a field value for Active Directory and Clarzen.
    2. To add a new field, click + Add Fields. Open the drop-down lists to select field values.
    3. To remove a field mapping, click the bin icon next to the mapping.
  3. Click Save.

 

Adding Additional Groups

Select which groups to sync and add groups.

  1. Click + Add Group

  2. Select the domain your groups are in.
  3. Select the groups that you want to sync. Use the search field to find a group(s).

    Group Search and Selection

  4. Click UPDATE SYNC LIST and your selected Groups will be added to the sync set.
  5. Click [x] to close the Add Groups window.
  6. Click on a Group to verify its users.

    Viewing a Group Users

     

Verifying Additional Settings

Click Settings to change the default sync settings.

 

Settings screen

The settings:

  • New User Invite Policy - Send standard Clarizen invitation to notify new users that they have access, or manually send at a later time
  • Direct Manager Sync - When a synced user's Direct Manager is not already synced to Clarizen as part of a synced Group
  • Ungrouped User De-Provisioning - When a synced user is no longer a Member of a sync Group Admins will always be notified
  • Disable User Policy - When a synced user is Disabled in Active Directory
  • Deleted User Policy - When a synced user is no longer found in Active Directory 

 

Selecting a Group to Test

Before running a major initial sync, it’s worth creating a small Group to sync to Clarizen with a test user to verify that the fields are mapped correctly.

Organizational Units

Active Directory Groups can be labelled as Organizational Units (OUs) to model organization hierarchy and simplify policy management. Whilst this field value (TRUE/ FALSE) can be synced over from AD Groups to the Organizational Unit field on Clarizen User Groups, it is for informational purposes only in Clarizen. In Clarizen this field has no functional purpose for permission levels or anything else.

License Types

License administration is not handled by the Sync Agent.

Clarizen Licenses are assigned based on the User Type property for Users (Groups do not have this field). New users' user type is based on your Clarizen System setting: New user default license type

New User Invitations

You may want to send invitations later if you have additional setup steps to do in Clarizen or if you want to send them out manually as part of an Onboarding / Training process.

The New User Invite Policy setting allows you to decide whether to send the standard Clarizen invitation email to new Users immediately upon provisioning or not. 

New User Added Notifications to Administrators

Clarizen System Settings provides 2 options for notifications for adding new users.

As the Active Directory User Sync Agent can add large quantities of users, it is highly recommended to set these as follows:

  • Alert Super Users on new user creation - FALSE (OFF)
  • Suppress new user emails to Administrators -  TRUE (ON)

 

Sync Scenarios

How Active Directory User Sync initially matches Users and Groups

User Sync Agent works by pairing Active Directory groups (as set by you in the Agent itself) with User Groups in Clarizen (initially matching by group name), identifying their users in Clarizen (initially by email address), and then pairing them by storing users’ and groups’ Active Directory SIDs in Clarizen's User Sync ID field.

All mapped data fields are synced one way from Active Directory to Clarizen. No data is synced back to Active Directory.

Users in Active Directory can be members of multiple groups and likewise in Clarizen.

Active Directory User Sync does not create or sync Discussion Groups.

 

Initial Sync Testing with Sandbox

Clarizen Sandbox Refresh process resets all Sandbox User emails to a common  no_reply@clarizen.com email address. 

If you already have users in your Sandbox account, the duplicate detection will work inconsistently and you may see duplicate users created.

 

Sync Now

Click Sync Now to trigger a sync between Active Directory and Clarizen. All changes to Active Directory users and groups since the last sync will be updated. If it is your initial sync, all users in the added Groups will be synced to Clarizen.

Recurring Scheduled Sync

To create a scheduled sync, you can use the Windows Task Scheduler to set a daily sync that runs the ActiveDirectorySyncEngine.exe application.

 

IMPORTANT

The Task Scheduler job should run as the same user that installed and setup the Active Directory User Sync.

 

 

 

Special Case Handling

Job Title Sync

Users’ Job Titles are only set by the sync if they already exist in Clarizen. This is because Job Titles can have billing rate implications and in AD they are free text fields that can be prone to typos.

If the AD User has a Job Title that does not exist in Clarizen, no matching can be done and Job Title is not added and matched.

Direct Manager Sync Setting

According to this setting, if the Direct Manager is not part of a synced group, the Direct Manager will be created, but without a Group. The Sync Agent does not recursively add their Direct Managers to users added this way. 

Deactivating Users in Clarizen

Users in Clarizen can be deactivated if:

  • Deleted User Policy: They are deleted in Active Directory
  • Disable User Policy: They are disabled in Active Directory
  • UnGrouped User Deprovisioning: They are active in Active Directory but no longer a member of any synced Groups (meaning: they are a member of other groups, but those Groups are not synced with Clarizen).

 

Viewing Log Files

At the end of a sync run, a daily Sync Report log file is created to help you monitor success and any issues it may encounter. On your Windows machine running the sync, the log files are accessible from:

       C:\ClarizenADSyncLogs

The sync report gives you a summary of how many groups and users were created, disabled and if any errors were encountered. The messages are aimed to be as self-explanatory as possible so that you can resolve issues yourself. Open a support ticket if you need assistance with the logs.

At the end of each sync run, a copy of the daily Sync Report will also be uploaded and attached to the sync user in Clarizen.
Note: The daily Sync Report contains details of all syncs from that day, so on initial syncs while you are getting set up, you can see summaries of multiple syncs.

In Clarizen you can build workflow rules to attach or make additional posts, for example you might want to reply to the post and @mention users who are affected by any issues. You can also automate this by creating a workflow rule on Post to run when $Via = 'Active Directory User Sync'

 

Sync Report Notification Post in Clarizen.

 

Sync Report viewed in Clarizen

 

Workflow Rule for Sync Report Notification Post in Clarizen

 

Example of an automatic reply to the Log File post with CC to another Clarizen Group

Monitoring

Monitoring Sync Changes

The following Clarizen fields describe sync updates:

  • User Sync ID - Set as the SID from Active Directory
  • User Sync Updated - Shows the date on which the record was last updated in Active Directory
  • User Sync Notes - Shows the date and time (in UTC) when the user/user group was last updated by the AD Sync Agent

Reports

The above fields can be added to Clarizen reports and are also available in the following reports:

  • Active Directory Sync: Users
  • Active Directory Sync: User Groups

The reports are available in an App Package

Monitoring when the Sync Last Ran

At the end of the AD User Sync Agent run, the date field Organization > User Sync Updated is updated and can be seen in Global Settings.

This field is always updated, whether or not the Sync Agent makes any changes to Users and User Groups in Clarizen. You can add the field to the Global Settings layout via Profiles > Organization > Property Card, or find it via the Property Card search.

 

User Sync Updated viewed via Search

Limitations

1. Supported Groups & Users

Active Directory sync only supports Global groups.

Universal and Domain Local groups are currently not supported.

The Active Directory Sync Agent does not sync sub-groups or non-human resources (such as printers, meeting rooms etc…)

 

2. Duplicate Group Names & Users Emails/SID’s

User Group names in Clarizen are unique. If you have Groups with the same name in different domains, you will not be able to sync them both. You should ensure that Groups have unique names.

Whilst Clarizen User email addresses are not unique, the Sync Agent will only sync users from Active Directory with unique email addresses. 

 

3. Users without an email address

You can only sync users that have a valid email address. Users that do not have a valid email address will not be synced. 

 

4. Number of Groups

There is no limit for the number of Groups you can map and sync into Clarizen, as the Sync Agent syncs each group and then its members (users) separately.

 

5. Group Size

The User Sync Agent has been tested to work with Groups of up to 5,000 new users.

Above that number, you may encounter timeouts from Clarizen web service APIs.

If you need to create larger numbers of users in a single sync, you can:

  1. Divide the users into separate smaller Groups (e.g. Project Managers, Consultants, Team Members)
  2. Run the sync repeatedly.
    Users who were successfully created on previous syncs will then be skipped on subsequent sync runs. Repeat the process until no new users are created by the sync.

 

6. User Management Settings in Clarizen 

Active Directory Users Sync Agent sets some basic user settings specific to the sync process. However, most Advanced user settings managed in Clarizen are also relevant to the users added by the sync process: 

For Users, the User Type setting defines which license the system will assign them on first login. For the initial 14 days, this will be a trial license before they are auto-assigned a license of the relevant type from your organization’s available licenses. 

The Default license type system setting sets which type of license new users should get: Full, Team Member, Time & Expense, None 

This setting lets you define your organization’s email domain. 

  • Mark users from other domains as External Users automatically   Learn more

If users have different email domains than the Organization email domain, this setting allows you to control whether they should automatically be flagged as External Users, which limits their access to items they’re specifically assigned to. 

Have more questions? Submit a request

Comments