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.
This package is designed for "on premise" Active Directory systems and has not been designed or tested to work with “Azure AD” user provisioning services which uses a SCIM (Simple Cloud Identity Management) standard.
However, once users have been provisioned (added to Clarizen), you can set up to authenticate (SSO) using Azure Active Directory as an Identity Provider.
For more about SSO (Federated Authentication) setup and configuration, use one of the following links:
Watch a video tutorial
Contents
Downloading and Installing the Sync Agent
Migrating Users from Active Directory Sync v1
Setting Up Connections to Clarizen and Active Directory
Connection to Active Directory
New User Added Notifications to Administrators
How Active Directory User Sync initially matches Users & Groups
Deactivating Users in Clarizen
Monitoring when the Sync Last Ran
Duplicate Group Names & Users emails/SID’s
Users without an email address
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:
- Ability to install Programs on your Windows PC
- Administrative privileges for your Clarizen environment
- Privileges for your company’s Active Directory Federation Services.
- .Net 4.6.2 or above
- Network access to Clarizen API (port:443)
- 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
- Download the .msi file from the Clarizen Apps Marketplace
- Run the .msi installer file to install the Clarizen Active Directory Sync Agent, which is comprised of 2 main elements:
- ClarizenADSyncSettings - Run this first to set up connections to Active Directory and Clarizen for Groups and field mappings
- ActiveDirectorySyncEngine- This is the engine that runs the sync and can be scheduled to run on an ongoing basis using Windows Task Scheduler
- Once you have installed the initial .msi package, navigate to
Program Files (x86) > Clarizen > ActiveDirectorySync
and run ClarizenADSyncSettings to finish the installation process.
- 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. - 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:
- You are currently using the v1 AD User Sync app,
and - 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
- Download the Migration App and activate it.
- 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
- Select the Users you currently sync by filtering on the SSOKey field.
- 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.
- Run Clarizen Active Directory Sync Agent on your Windows machine.
- Once you have verified results, you can delete the custom (“SSO”) fields from Clarizen.
- Remove any scheduled sync tasks of the old app from your Windows machine.
"Marooned" Deprovisioned Users
v2 adds the capability to 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 disabled (State: "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:
- 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. - 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).
- Click Account.
- Enter your Clarizen Username and Password. Click Check to validate the connection.
- Enter your Active Directory Domain, Username and Password. Click Check to validate the connection.
- If you want to add additional domains, click + Add Domain and enter your Active Directory credentials.
- Click Save.
Setting up Field Mappings
Add, remove and update Active Directory-to-Clarizen field mappings.
- Click Field Mapping.
- 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
- 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.
- To add a new field, click + Add Fields. Open the drop-down lists to select field values.
- To remove a field mapping, click the bin icon next to the mapping.
- Click Save.
Adding Additional Groups
Select which groups to sync and add groups.
- Click + Add Group
- Select the domain your groups are in.
- Select the groups that you want to sync. Use the search field to find a group(s).
Group Search and Selection
- Click UPDATE SYNC LIST and your selected Groups will be added to the sync set.
- Click [x] to close the Add Groups window.
- 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).
Deactivated users are "Suspended" in Clarizen and not fully deleted.
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 supports Global and Universal groups.
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:
- Divide the users into separate smaller Groups (e.g. Project Managers, Consultants, Team Members)
- 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:
- New user default license type Learn more
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
- Organization email domain Learn more
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.
Comments