Inbound Provisioning from UltiPro

Source Target
UltiPro AD

You can define synchronization schedules to synchronize user data from source directory to target Active Directories.

Before you start configuring inbound provisioning to AD targets, you need to do the following:

  • Installed the CyberArk Identity Connector.

    The CyberArk Identity Connector is required to provision users to AD target directories.

    See Install the CyberArk Identity Connector.

  • Stored the domain administrator account to CyberArk Identity.

    This step is only required if the CyberArk Identity Connector is not run by a domain administrator. See Manage domain administrative accounts.

  • Populated the relevant user data in your data source.
  1. Log in to the Identity Administration portal.
  2. Click Settings > Users > Inbound Provisioning.

  3. Click Add Source (on the Sources tab) to define the UltiPro service information.

    The Provisioning Source window opens.

  4. Select UltiProfrom the Source drop-down menu.

  5. Select the Enable check box to enable the feature.

    You can configure the feature first, then enable it when you are ready.

  6. Enter a Name for this source.

  7. To obtain your UltiPro subdomain:

    1. In the UltiPro admin console, select Menu > System Configuration > Web Services.

    2. Copy the subdomain shown next to Business Intelligence web service endpoint and paste it into the the Identity Administration portal, using https:// as a prefix. For example, https://mysubdomain.ultipro.com.

    You will not be able to save this configuration without a valid subdomain.

  8. To obtain your UltiPro API key:

    1. In the UltiPro admin console, select Menu > System Configuration > Web Services.

    2. Copy the Customer API Key.

  9. Enter your UltiPro integration user name and password, then click Verify to verify the integration subdomain and API Key combination.

    1. Select the Enable New Hire Pre-Provisioning ckeckbox to provision a user prior to the user employment start date.

      For example, if you have users starting 2 days after your synchronization action, you can synchronize those user data to Active Directory by setting the Interval field to 120 hours. If you do not configure this option, the default value is eight hours.

      The maximum value is 8,760 hours (one year).

    2. Enable Run incremental sync automatically and specify the sync frequency in minutes.

      SeeInbound Provisioning from CyberArk Cloud Directory for more sync options.

    3. Specify the time offset between your CyberArk Identity tenant and UTC using the Tenant UTC Offset (minutes) option to prevent delayed or premature user data synchronization.

      Synchronizations are performed based on UTC time. If you need to compensate for time zone differences between your tenant and UTC, specify that offset here.

    4. Select Do not create new users (update existing user only) if you want the sync job to only update the existing user data and not create any new users in Active Directory.

    5. Select Ignore sync cache if you want to sync with the data source regardless of existing user data in Active Directory.

      CyberArk Identity keeps a cache of the data source's user data.

      If systems administrators update user data in Active Directory, then that data is out of sync from the data source. This option allows CyberArk Identity to ignore existing data in Active Directory and sync with the data source.

      Enabling this option makes available the Discard directory identifiers for cached entries. Enable this option if you want CyberArk Identity to discard existing user IDs stored in Active Directory and re-discovers users from UPN or samaaccount name.

  11. Click Save.

    Your configured source is listed in the Sources table.

Define provisioning rules to identify users, map user attributes, and other important provisioning configuration. You can define more than one rule for each source. For example, you might use a single rule if you are provisioning all users from UltiPro to a single AD OU, or multiple rules if you want logical groupings of users in UltiPro to have different target AD OUs.

You can mix rules that have different target directories. For example, you could create one rule that provisions full-time employees to AD and another rule that provisions contractors to another AD.

You must first add and configure a source before you can define the rules.

Step 1: Add a new rule

  1. From Settings > Users > Inbound Provisioning, select UltiPro and then click Actions > Add Rule.

  2. Enter a Name for this rule.

  3. Select a Provisioning Rule Mode.

    Mode Description
    Active Makes a rule active. Not recommended until you have finished all configurations. You must activate a rule before synchronizing.
    Preview Sets the rule in preview mode. Select this option for a production environment to verify the user mapping between UltiPro and the target directory before you make the rule Active.
    Inactive Sets the rule as inactive. Recommended until you have finished all configuration steps. You can come back to this option and activate the rule when you are ready.

Step 2: Define the users to which the rule(s) apply

Select the Source Selection Rule to define the users to which these rules apply.

If you are provisioning all UltiPro users (by selecting All Companies from the drop-down list) to one Organizational Unit (OU) in AD, then you do not need to perform the following sub-steps.

If you are provisioning specific companies and organizational levels to specific OUs in AD, then do the following:

  1. Select one of the following from the Source Selection Rule drop-down:

    1. All Users - Select this option to choose all users.

    1. Specific Organization - Select this option to choose a specific organization. Click Add to select the required organization.

  2. Select one of the following from the Second Level Source Selection Rule drop-down:

    1. All Roles - Select this option to choose all roles. The roles will be based on the first Source Selection Rule. For example, if you select any specific Org(s), all roles will be related to the selected Orgs.

    2. Specific Roles- Select this option to choose a specific role. Click Add to select the required role.

      1. Repeat above sub-steps until you have added all relevant roles and click Next.

  1. Select Specific Companies from the Source Selection Rule drop-down menu, then click Add.

    A new drop-down menu displays.

  2. Select a company from the new drop-down menu, then click Add to add the company.

    Repeat this procedure for as many companies as you want to add.

  3. (Optional) If you don't want to provision all users in the selected company, select an Organizational Level from the Second Level Source Selection Rule drop-down menu, then click Add.

    A new drop-down menu displays.

  4. Select an organizational level, then click Add to add the organizational level.

    Repeat this procedure for as many organizational levels as you want to add.

  5. Click Next.

  1. Click Add to select the specific group.

  2. Select a source group from the drop-down list and click the associated Add button.

  3. Repeat these sub-steps until you have added all relevant groups, then click Next.

Step 3: Define the target directory that you want to provision to.

  1. Select the relevant forest from the Target drop-down menu.

    When you select the forest, CyberArk Identity looks for the stored domain administrator account and shows a warning message if one is not available (unless the CyberArk Identity Connector is run by a domain administrator). See Manage domain administrative accounts.

  2. Select the relevant Domain.

  3. Select the relevant Domain Controller.

  4. Select the relevant and click Next.

Select CyberArk Cloud Directory ({CyberArk_tenantID}) from the Target drop-down menu, then click Next.

Step 4: Map the attributes

  1. Review the required and automatically mapped attributes.

    You can delete optional attributes. You also have the option to map additional attributes.

  2. (Optional) Click Add and select the Target Attribute (attribute name in Active Directory or CyberArk Cloud Directory) to add more attributes.

    • If there is only one match in UltiPro, then no corresponding source attributes are displayed; click Add again to add the attribute and view the mapping in the table.

    • If more than one source attribute can be mapped to the selected target attribute, then select a corresponding Source Attribute (attribute name in the data source) from the drop-down list; click Add again to add the attribute and view the mapping in the table.

      Continue mapping attributes until all necessary attributes are mapped.

    • Some attributes (for example, jobTitle, jobDescription, dateOfBirth, preferredName) might not have suitable target attributes in AD. You have to expand your AD schema to accommodate these attributes.

      Refer to Microsoft documentation for more information on expanding your AD schema.

    • You can edit the attribute in the Target Attribute column to map custom AD attributes to source attributes.

Step 5: Configure additional provisioning rule options

  1. Click Next to configure additional provisioning rule options.

  2. (Optional) Configure the following attribute options.

    Option Description
    Set user’s manager attribute If enabled, users’ manager attributes in UltiPro are synchronized to the target directory.
    Disable user in AD if user account status is suspended. If enabled, users with the terminated employment status in UltiPro are automatically disabled in the target directory source.

  3. Specify the Password Type for new user accounts.

    If you select Static Password from the drop-down list, then the system uses the same password for all new users.

    Make sure the password meets the complexity requirements set via policy for the target groups. If the password does not meet the complexity requirements, you will see the error UnableToSetPassword in the sync report.

    Provide the following information:

    Field/Option Description
    Password Specify the password to be used for all users.
    Require password change at next login

    If enabled, new users will be required to change their passwords after the initial log in. Disabled by default.

    See Password Synchronization for more details.

    If you select Generated Password from the drop-down list, then the system randomly generates different passwords for each new user.

    Provide the following information:

    Field/Option Description
    Require password change at next login If enabled, new users will be required to change their passwords after the initial log in. Disabled by default.
    Delivery Options

    Select the email address to which you want the auto-generated password sent.

    This is to help in your new employee onboarding process. When new users are created in Active Directory, an email will be sent to the specified address with the credentials for those users.

    • Send password to email address

      Enter the email address to which you want the password sent.

    • Send password to user’s manager

      Sends the password to the manager’s email address. Ensure that you have the email address specified in the data source.

    • Send password to user’s personal email

      Sends the password to the user’s email address specified in the data source.

      If Password sync feature is enabled then the password is not sent to the user's email.

      If you have more than one option selected, the password is sent to all the selected email addresses.

Step 6: (Optional ) Map users to AD groups or CyberArk Cloud Directory Roles.

  1. Enable the Add users to groups check box.

  2. Select the Add button within the Active Directory Group Options area. The Add Active Directory Group window opens.

  3. Confirm that the appropriate target group is selected.

  4. (Optional for AD) Select Assign user to an OU upon termination if you want to specify the organizational unit (OU) in which terminated users will be placed.

    If you do not enable this check box, then terminated users will remain in the current OU.

    Selecting this option requires enabling the Disable user in AD if worker employment status is terminated option. Both options must be enabled to successfully assign users to an OU upon termination.
    Selecting this option requires enabling the Disable user in AD if user account status is suspended option. Both options must be enabled to successfully assign users to an OU upon termination.

    Enter the group name into the Search box to find the group.

  5. Select the group and click Add.

  6. Select Re-evaluate Group Memberships to remove users satisfying the inbound provisioning rule from previous group assignments and add the users only to the groups specified.

    For example, you might have separate inbound provisioning rules configured to provision users in a sales source group to a sales AD group, and a marketing source group to a marketing AD group. If a user moves from the sales organization to the marketing organization, the user should be removed from the AD sales group so that the user's access is appropriate for just marketing, not marketing and sales. Selecting Re-evaluate Group Memberships would remove the user from the sales group when the inbound provisioning rule for the marketing source group runs.

    Re-evaluate Group Memberships removes users from all previous AD group assignments, regardless of whether the assignment was from inbound provisioning or configured manually. This might have unintended consequences for application access, authentication policies, device management, etc. Verify that your users only need the access granted to the AD groups specified in the inbound provisioning rule.

  1. Enable the Add users to roles check box.

  2. Select the Add button within the CyberArk Cloud Role Options area. The Add Role window opens.

  3. Confirm that the appropriate source is selected.

  4. Start entering the role name into the Search box to find the role.

  5. Select the role and click Add.

  6. Select Re-evaluate Role Memberships to remove users satisfying the inbound provisioning rule from previous role assignments and add the users only to the roles specified.

    For example, you might have separate inbound provisioning rules configured to provision users in a sales source group to a sales role, and a marketing source group to a marketing role. If a user moves from the sales organization to the marketing organization, the user should be removed from the sales role so that the user's access is appropriate for just marketing, not marketing and sales. Selecting Re-evaluate Role Memberships would remove the user from the sales role when the inbound provisioning rule for the marketing source group runs.

    Re-evaluate Role Memberships removes users from all previous role assignments, regardless of whether the assignment was from inbound provisioning or configured manually. This might have unintended consequences for application access, authentication policies, device management, etc. Verify that your users only need the access granted to the roles specified in the inbound provisioning rule.

Step 7: Map Provisioning Groups to Active Directory Groups or CyberArk Cloud Directory Roles.

Provisioning Groups can be used to collect users and map them to specific AD Groups or CyberArk Cloud Directory Roles.

  1. Enable the Map Provisioning Roles to Active Directory Groups check box.

  2. Select the associated Add button.

  3. Select the Provisioning Role Name from the drop-down.

  4. Confirm that the appropriate target is selected.

  5. Enter the group name into the Search box to find the group.

  6. Select the group and click Add.

Step 8: Map Provisioning Groups to Active Directory Groups or CyberArk Cloud Directory Roles.

Provisioning Groups can be used to collect users across different supervisory organizations in UltiPro and map them to specific AD Groups or CyberArk Cloud Directory Roles.

  1. Enable the Map Workday Provisioning Groups to Active Directory Groups check box.

  2. Select the associated Add button.

  3. Select the Provisioning Group Name from the drop-down list.

  4. Confirm that the appropriate source is selected.

  5. Start entering the group name into the Search box to find the group.

  6. Select the group and click Add.

  1. Enable the Map Workday Provisioning Groups to CyberArk Cloud Directory Roles check box.

  2. Select the associated Add button.

  3. Select the Provisioning Group Name from the drop-down list.

  4. Confirm that the appropriate source is selected.

  5. Start entering the group name into the Search box to find the group.

  6. Select the group and click Add.

Step 9: (Optional for AD) Select Assign user to an OU upon termination if you want to specify the organizational unit (OU) in which terminated users will be placed.

If you do not enable this check box, then terminated users will remain in the current OU.

Selecting this option requires enabling the Disable user in AD if user account status is suspended check box. You need to enable both options to successfully assign users to an OU when the user is suspended in the Cloud directory or disabled in the source AD.

Step 10: Finalize the rule(s)

  1. Click Save to save the rule configuration.

    The provisioning rule has been configured and the rule is listed in the Sources table.

  2. Click the rule to change its status if you did not already set the rule to Active.

  3. Click Save.

  4. Define additional provisioning rules as needed.

    You can define more than one rule for each source.

  1. Log in to the Identity Administration portal.

  2. Click Settings > Users > Inbound Provisioning.

  3. Click the row associated with UltiPro.

    The Provisioning Source page opens for edits. Complete your edits and return to the Inbound Provisioning page.

  4. Click a rule associated with UltiPro.

    The Inbound Provisioning Rule page opens for edits. Complete your edits as needed.

After you have configured the data source and provisioning rule, you are ready to synchronize user data from UltiPro to your target directory. You have the option to manually trigger a full or incremental sync or schedule incremental syncs. Full syncs are time and resource intensive so it must be triggered manually; we recommend doing it only when necessary.

For the initial sync, you must perform a full one.

  1. Log in to the Identity Administration portal.

  2. Click Settings > Users > Inbound Provisioning.

  3. Confirm that you have the source and provisioning rule configured and click the Sync Options tab next to Sources.

  4. Select either Incremental or Full in the Manual Sync Options area.

    For the initial sync, you must perform a full one.

  5. Select the source (a specific source or all configured sources) that you want to synchronize.

  6. Click Run Sync.

  1. Log in to the Identity Administration portal.

  2. Click Settings > Users > Inbound Provisioning.

  3. Confirm that you have the source and provisioning rule configured and click the source for which you want to schedule an incremental sync.

  4. Click Sync Settings.

  5. Select the Run incremental sync automatically check box.

  6. Specify how frequently you want to run the sync in the Frequency text box.

  7. Click Save.

You can configure CyberArk Identity to send reports via email after each sync completion.

To view the detailed job report using the link provided, you must log in with full administrator privileges or read only administrator privilege.

  1. Enable Send report on sync completion check box if you want to receive a sync report.

  2. Select the type of syncs to include in the report.

    • All Syncs

    • Incremental Syncs

    • Full Syncs

  3. Select Send only failed reports to limit reports to failed syncs of the selected sync type.

    For example, if you select All Syncs and Send only failed reports, then you send reports for failed incremental syncs and failed full syncs.

  4. Under Distribution, click Add to specify an email address to send reports to.

    The default email address is that of the logged in system administrator. You can enter a new email address by editing the default address.

  5. Click Save.

You can use the Identity Administration portal to run a script mapping UltiPro fields to relevant Active Directory attributes, or to manually assign target attributes.

In the event of a conflict between the attribute mapping table and the script, the script has priority.

  1. Log in to the Identity Administration portal.

  2. Click Settings > Users > Inbound Provisioning.

  3. Select the provisioning rule for which you want to add the script.

  4. Click the Attributes tab.

  5. Confirm that the Use Attribute Mapping Script checkbox is enabled.

  1. Create the script.

    Although a sample script is not currently available, you can use Closedthe following sample script from a similar data source as the starting point.

    trace("Starting script...");

var sc = SyncContext;
sc.SkipUserSync = false;

trace(sc.SourceUserRecord.CustomProperties.Dump());

sc.TargetUserRecord.Company = "My company name";
sc.TargetUserRecord.DisplayName = sc.SourceUserRecord.displayName;
sc.TargetUserRecord.Division = sc.SourceUserRecord.CustomProperties.Get("division");
if(sc.SourceUserRecord.address2 != null) {
    sc.TargetUserRecord.StreetAddress = sc.SourceUserRecord.address1 + ", " + sc.SourceUserRecord.address2;
} else {
    sc.TargetUserRecord.StreetAddress = sc.SourceUserRecord.address1;
}

// Enumerating & updating group guids
// if(sc.TargetUserRecord.MemberObjectGuids){
//     var newGroupList = [];

//     for(var idx = 0; idx < sc.TargetUserRecord.MemberObjectGuids.Length; ++idx){
//         trace("Group guid is " +  sc.TargetUserRecord.MemberObjectGuids[idx]);
//         newGroupList.push(sc.TargetUserRecord.MemberObjectGuids[idx]);
//     }

//     newGroupList.push("f1a7e28aa5bb4f59a3e6566fc69545e8");
//     sc.TargetUserRecord.MemberObjectGuids = newGroupList;
// } else {
//     trace("MemberObjectGuids is empty or not defined.");
// }


/********************************************************************************
USAGE
    This is a test script that shows scripting capabilities for attribute mapping.

    Script is passed in a context variable called SyncContext.
    SyncContext has three objects - SourceUserRecord, TargetUserRecord, SkipUserSync.
      1. SourceUserRecord contains attributes calculated from UltiPro sourceUser and CustomProperties.
      2. TargetUserRecord contains values for AD attributes calculated from UltiPro sourceUser. You can override these attributes.
      3. Set SkipUserSync to false to skip worker sync.

    SyncContext {
        // UltiPro
        SourceUserRecord {
            id,               // string
            employeeNumber,   // string
            firstName,        // string
            middleName,       // string
            lastName,         // string
            displayName,      // string
            workEmail,        // string
            workPhone,        // string
            mobilePhone,      // string
            jobTitle,         // string
            department,       // string
            employmentHistoryStatus, // string
            country,          // string
            state,            // string
            zipcode,          // string
            city,             // string
            address1,         // string
            address2,         // string
            supervisorEId,    // string
            terminated,       // bool
            CustomProperties, // object - To read an attribute from CustomProperties, do SyncContext.SourceUserRecord.CustomProperties.Get("my_attribute").
        },
        // ActiveDirectory
        TargetUserRecord {
            SamAccountName,     // string - The logon name used to support clients and servers running earlier versions of the operating system
            UserPrincipalName,  // string - Internet-style login name. my_sam_account_name@my_domain.com
            OrganizationUnit,   // string
            Cn,                 // string - The name that represents an object. Used to perform searches in AD
            EmployeeId,         // string
            DisplayName,        // string - The display name for an object. This is usually the combination of the users first name, middle initial, and last name.
            Mail,               // string - Email
            Title,              // string - Job Title
            EmployeeType,       // string - The job category for an employee.
            GivenName,          // string - First Name
            Sn,                 // string - Last Name
            MiddleName,         // string
            Department,         // string
            C,                  // string - 2 letter country code, e.g.) US
            Co,                 // string - country name, e.g.) United States
            CountryCode,        // string - Numeric country code, e.g.) 840 for US
            St,                 // string - State
            PostalCode,         // string - Zip Code
            L,                  // string - City
            StreetAddress,      // string
            PhysicalDeliveryOfficeName,// string
            TelephoneNumber,    // string
            Mobile,             // string - The primary mobile phone number
            Company,            // string
            Disabled,           // bool
            MemberObjectGuids,  // array of group objectGuids. - Group objectGuid must belong to domain that user belongs to
            ManagerObjectGuid,  // string
            PersonalTitle,      // string
            PostOfficeBox,      // string array of PO Boxes
            Division,           // string
            IpPhone,            // string
            DepartmentNumber,   // array of strings
            DisplayNamePrintable,// string
        },
        SkipUserSync // bool
    }
********************************************************************************/
    1. Enter an UserID for an employee with relevant attributes.
    2. Click Next.
      Attribute values associated with the UserID are displayed.

  3. Update the script as necessary for your purpose.

    For example, resolve DisplayName conflicts by using the checkValueExists function to see if the DisplayName already exists in AD. If checkValueExists returns True, create a new function to create a unique DisplayName for the user you are trying to provision.

    Refer to Conflict resolution for more information about resolving conflicts with scripting.

  4. Click Save.

    When a synchronization between UltiPro and Active Directory is triggered, the script runs automatically.