On-Premise Integration Connector Setup

Exclamation.png

After careful consideration and analysis of feature usage, we have decided to retire our On-Premise Integration. This feature will no longer be supported as of 31st March 2024. If you have any concerns or suggestions regarding this change, please don't hesitate to reach out to our support team or your dedicated Customer Success Manager.

 

Prerequisites

Before installing the on-premise integration connector service, you will need:

  • An on-premise directory with LDAPS access, such as Active Directory.
  • A Windows machine to install and configure the connector service (Windows Server 2008 R2, Windows 7 or greater.
  • The Password Policy in CloudM Automate must match the Password Policy in Active Directory, where required, in order for passwords to update and sync correctly.
  • .Net Framework runtime version 4.6.2 or higher installed
  • NET 5.0 runtime installed 
  • Connect to the on-premise Active Directory over LDAPS.
  • Connect to CloudM Automate over HTTPS.
  • Accept incoming HTTP/HTTPS requests from CloudM Automate.
  • The IP and port (usually 636) required to connect to the on-premise directory over LDAPS.
  • The full DN and password of an admin account that can be used to create, update and delete user accounts over LDAPS.
  • CloudM Automate installed for your domain.
  • The shared secret from the CloudM Automate On-Premise Integration page.

 

Setup

Exclamation.png

If you already have the ADSync Connector version 1.0.318 (or earlier) installed, you will need to uninstall this version before installing the current version.

Upgrading to a version after v1.0.318 is required for Microsoft domains that want to use the Group Synchronization functionality (released in CloudM Automate v2.3).

 

To install CloudM Automate On-Premise Integration 

  1. Download the installer to your Windows machine.
  2. Open the installer.
  3. Follow the instructions in the Installation Wizard (including accepting the terms in the License Agreement). 

 

N.B if you are migrating from the previous Tomcat version of the connector application, you can import the options.xml file directly into the installer using the user interface, and the installer will notify you of any changes required to the configuration.

  

The installer will start with the default configuration preloaded.  You will need to populate the following configuration properties:

  • CertUrl - Url to be used to obtain public certificates to be used when authenticating with CloudM Automate
  • PrimaryDomain - You can find this on the Directory / Org Units page on CloudM Automate
  • SharedSecret - You can find this on the Settings / On-premise integration page
  • Ldap
    • Default location can be specified by leaving the OU element empty 
    • Template forms the full distinguished name of objects (e.g. cn=${firstName}.${lastName},CN=Users,DC=example,DC=com)
    • LdapDomain - Fully qualified domain name of which the account that you want to use to interact with Active Directory is registered (e.g. if user is admin@example.com then this would be example.com)
    • LdapUser - User name of the account that you want to use to interact with Active Directory (e.g. if user is admin@example.com then this would be admin)
    • LdapPassword - Password used to login to Active Directory
    • LdapServer - Active Directory Server IP address or fully qualified domain name 
    • LdapRootDn - Root distinguished name of the LDAP instance (e.g. for example.com this would be DC=example,DC=com
    • DnTemplates - This property can be used to define placement of objects on Active Directory

AD_Sync_2.PNG

 

Now the CloudM Connector is installed, you can:

  1. Enable on-premise integration in CloudM Automate.
  2. Specify the endpoint as https://1.2.3.4:8443/cloudm-connector/connector where http or http is specified depending upon your installation, 1.2.3.4 is the IP address of the machine running the connector and 8443 is the port specified when installing the connector
  3. Click the test button. CloudM Automate will attempt to contact the connector and the connector will attempt to connect to your on-premise directory via LDAPS. You should see a message indicating the test was successful. See Integration Test Error Codes for details on the possible errors.

If the test fails, check the error message and check the logs on your server. They should be available in the%ProgramData%/CloudM/ADSync/Logsfolder.Examine the logs carefully and correct any mistakes indicated by the logs.

 

Further Configuration

You can specify the events that will be synced to your on-premise directory via the connector in the CloudM Automate on-premise integration page.

The specifics of how users are synced including the attribute mappings are defined in the connector options which are stored in an XML file within the program data folder: %ProgramData%/CloudM/ADSync/options.xml. Any changes made to this file will only take effect when the “CloudM ADSync” Windows service is restarted.  You can amend this file by re-running the installer or selecting change from Windows Control Panel > Programs and Features > “CloudM ADSync x.x.x.x”.

The default configuration of the connector is set up to be suitable for syncing to Active Directory:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<options>

<sharedSecret>0123456789abcdef</sharedSecret>

<primaryDomain>example.com</primaryDomain>

<certUrl>https://mycloudpages.appspot.com/certs</certUrl>

<publicKeyType>RSA</publicKeyType>

<ldap>

 <useLdapServer>true</useLdapServer>

 <ldapServer>127.0.0.1</ldapServer>

 <ldapPort>636</ldapPort>

 <useSSL>true</useSSL>

 <ldapUsername>admin</ldapUser>

 <ldapDomain>example.com</ldapDomain>

 <ldapPassword>secret</ldapPassword>

 <ldapRootDn>DC=example,DC=com</ldapRootDn>

 <cn>${firstName}.${lastName}</cn>

 <objectClass>top,person,organizationalPerson,user</objectClass>

 <passwordType>unicodePwd</passwordType>

 <updateGroups>false</updateGroups>

 <attribute name="mail" onUpdate="false" onRename="true">$!{primaryEmail}</attribute>

 <attribute name="userPrincipalName" onUpdate="false" onRename="true">$!{primaryEmail}</attribute>

 <attribute name="sAMAccountName" onUpdate="false" onRename="true">$!{username}</attribute>

 <attribute name="name" onUpdate="false">$!{firstName} $!{lastName}</attribute>

 <attribute name="givenName" onUpdate="false" onRename="true">$!{firstName}</attribute>

 <attribute name="sn" onUpdate="false" onRename="true">$!{lastName}</attribute>

 <attribute name="title" emptyAllowed="false" trimWhiteSpace="true">$!{jobTitle}</attribute>

 <attribute name="department" emptyAllowed="false" trimWhiteSpace="true">$!{department}</attribute>

 <attribute name="company" emptyAllowed="false" trimWhiteSpace="true">$!{company}</attribute>

 <attribute name="description" emptyAllowed="false" trimWhiteSpace="true">$!{orgDescription}</attribute>

 <attribute name="physicalDeliveryOfficeName" emptyAllowed="false" trimWhiteSpace="true">$!{officeLocation}</attribute>

 <attribute name="streetAddress" emptyAllowed="false" trimWhiteSpace="true">$!{street}</attribute>

 <attribute name="l" emptyAllowed="false" trimWhiteSpace="true">$!{city}</attribute>

 <attribute name="st" emptyAllowed="false" trimWhiteSpace="true">$!{state}</attribute>

 <attribute name="co" emptyAllowed="false" trimWhiteSpace="true">$!{country}</attribute>

 <attribute name="postalCode" emptyAllowed="false" trimWhiteSpace="true">$!{postCode}</attribute>

 <attribute name="mobile" emptyAllowed="false" trimWhiteSpace="true">$!{firstNumber_mobile}</attribute>

 <attribute name="telephoneNumber" emptyAllowed="false" trimWhiteSpace="true">$!{firstNumber_work}</attribute>

 <attribute name="homePhone" emptyAllowed="false" trimWhiteSpace="true">$!{firstNumber_home}</attribute>

 <attribute name="facsimileTelephoneNumber" emptyAllowed="false" trimWhiteSpace="true">$!{firstNumber_fax}</attribute>

 <attribute name="wWWHomePage" emptyAllowed="false" trimWhiteSpace="true">$!{primaryWebsite}</attribute>

 <attribute name="manager" emptyAllowed="false" trimWhiteSpace="true">#if(${manager}) $ldap.findDn("userPrincipalName", $manager) #end</attribute>

 <attribute name="userAccountControl" emptyAllowed="false" trimWhiteSpace="true">#if(${suspended} == "true") 514 #else 512 #end</attribute>

 <attribute name="pwdLastSet" emptyAllowed="false" trimWhiteSpace="true" onPassword="true">#if(${forcePasswordChange} == "true") 0 #else -1 #end</attribute>

</ldap>

</options>

The options are:

  • ldapServer: The IP or hostname of the LDAP server (e.g. Active Directory). This is set by the installation script.
  • ldapPort: The port of the LDAP server (usually 636). This is set by the installation script.
  • useSSL: True for secure (LDAPS) connections or false for in-secure (LDAP) connections.
  • ldapDomain : Domain to use when authenticating with Active Directory.
  • ldapUsername:Username to use when authenticating with Active Directory.
  • ldapPassword: The admin account password. This is set by the installation script.
  • ldapRootDn: The DN to the root of the tree containing the users that the connector should create, update and delete. This is set by the installation script.
  • sharedSecret: The shared secret from CloudM Automate. This is set by the installation script.
  • cn: The template (see below) used to determine the CN of the user. This template must match the CN of existing users to allow them to be modified by the connector. This is set by the installation script.
  • objectClass: The template (see below) used to determine which objectClasses will be used when a user is created in CloudM Automate. Multiple objectClasses can be specified separated by commas. Defaults to top,person,organizationalPerson,user.
  • passwordType: The type of password attribute to update. Valid values are unicodePwd or userPassword. If set to userPassword then it will set the userPassword and/or userPasswordAD LDAP attributes depending on if “Include SHA-1 Password Hash” or “Include AES Encrypted Password” are enabled in CloudM Automate respectively. If set to unicodePwd, then it will set the unicodePwd LDAP attribute if “Include AES Encrypted Password” is enabled in CloudM Automate . Defaults to unicodePwd.
  • updateGroups: Set to true to update the member attribute of any group entry listed in the user’s groupMembership attribute when the user is deleted, moved or renamed. Defaults to false.
  • attribute: Specifies how and when to populate an ldap attribute based on a template which can reference the CloudM Automate user. Any number of attribute options can be set. Each attribute option must specify the ldap attribute name using the name xml attribute and the value template. The following xml attributes may also be used:
    • onUpdate: Replace the attribute when the user is updated in CloudM Automate. Defaults to true.
    • onCreate: Include this attribute when a user is created in CloudM Automate. Defaults to true.
    • onRename: Replace the attribute when the user is renamed in CloudM Automate. Defaults to false.
    • onMove: Replace the attribute when the user is moved in CloudM Automate. Defaults to false.
    • onPassword: Include this attribute when a user's password is changed in CloudM Automate. Defaults to false.
    • emptyAllowed: Include/replace this attribute even when it is empty. Defaults to true. If false, the attribute will be removed when it is empty.
    • trimWhiteSpace: Remove any leading and trailing whitespace around the value before it is saved. Defaults to true.
    • modType: Defines how the attribute will be modified. Set to add to add a value, delete to delete a matching value, increment to increment the existing attribute integer value or replace to replace any existing values. Defaults to replace.
    • multivalued: Specifies a separator to split the evaluated value to multiple LDAP attribute values. By default the LDAP attribute is treated as single valued.
  • dn: Specifies how users are located in the LDAP directory. By default a user's DN is evaluated using template cn=$cn,#foreach($part in $ouPath)ou=$part,#end$rootDn - (where $cn and $rootDN are the respective options) meaning that if user Joe Bloggs is in OU /MyCompany/Sales/Renewals they would be synced to the LDAP entry with DN cn=Joe.Bloggs,ou=Renewals,ou=Sales,ou=MyCompany,o=example. If there is a dn option specified with an ou xml attribute matching the user's OU then the user's DN is the evaluated template.
    • To ignore (not sync) users from a given OU:
      • <dn ou="/MyCompany/Sales/Renewals"></dn>
    • To map users in a given OU to a different location in the LDAP directory, overriding the cn and ldapRootDn options:
      • <dn ou="/MyCompany/Finance">cn=${firstName},ou=money,o=example</dn>

 

Templates

Apache Velocity is used for the CN and attribute templates. The syntax is documented at https://velocity.apache.org/engine/1.7/user-guide.html

Most of the time the only syntax you need is the ability to reference the provided CloudM Automate user variables with $!{variableName}. Basic concatenation of variables with constant text is also simple: ${firstName}-${lastName} would result in a value like “joe-bloggs”.

The available CloudM Automate user variables are:

  • firstName
  • lastName
  • fullName
  • primaryEmail
  • username: The username part of the primary email address
  • primaryEmailDomain: The domain part of the primary email address
  • domain
  • ou
  • notes
  • jobTitle
  • orgDescription
  • company
  • department
  • employmentType
  • officeLocation: Microsoft domains only.
  • manager (but see Configuration Tips)
  • suspended: True if the user is suspended, false otherwise.
  • alias
  • primaryPerson_assistant
  • primaryNumber
  • firstNumber_work
  • firstNumber_mobile
  • firstNumber_main
  • firstNumber_home
  • firstNumber_work_mobile
  • firstNumber_callback
  • firstNumber_assistant
  • firstNumber_company_main
  • firstNumber_other_fax
  • firstNumber_home_fax
  • firstNumber_work_fax
  • firstNumber_pager
  • firstNumber_work_pager
  • firstNumber_car
  • firstNumber_radio
  • firstNumber_tty_tdd
  • firstNumber_isdn
  • firstNumber_telex
  • firstNumber_other
  • firstNumber_grand_central
  • primaryEmail
  • firstEmail_work
  • firstEmail_other
  • firstEmail_general
  • firstEmail_home
  • primaryImAddress
  • firstImAddress_aim
  • firstImAddress_google_talk
  • firstImAddress_icq
  • firstImAddress_jabber
  • firstImAddress_msn
  • firstImAddress_netmeeting
  • firstImAddress_qq
  • firstImAddress_skype
  • firstImAddress_yahoo
  • primaryWebsite
  • firstWebsite_blog
  • firstWebsite_ftp
  • firstWebsite_home
  • firstWebsite_home_page
  • firstWebsite_other
  • firstWebsite_profile
  • firstWebsite_work
  • primaryAddress
  • firstAddress_work
  • firstAddress_home
  • firstAddress_other
  • city: Microsoft domains only.
  • city_work: Microsoft domains only.
  • city_home: Microsoft domains only.
  • city_other: Microsoft domains only.
  • state: Microsoft domains only.
  • state_work: Microsoft domains only.
  • state_home: Microsoft domains only.
  • state_other: Microsoft domains only.
  • country: Microsoft domains only.
  • country_work: Microsoft domains only.
  • country_home: Microsoft domains only.
  • country_other: Microsoft domains only.
  • postCode: Microsoft domains only.
  • postCode_work: Microsoft domains only.
  • postCode_home: Microsoft domains only.
  • postCode_other: Microsoft domains only.
  • street: Microsoft domains only.
  • street_work: Microsoft domains only.
  • street_home: Microsoft domains only.
  • street_other: Microsoft domains only.

There are also lists of values for the user sent from CloudM Automate. These can be used in Velocity templates like:

#foreach($tag in $allTags)$tag,#end

The multivalued option can be useful to map these lists to multiple attribute values in LDAP:

<attribute name="homePostalAddress" multivalued="|||" emptyAllowed="false" trimWhiteSpace="true">#foreach( $i in $allAddress_home )$i|||#end</attribute>
  • allTags
  • allAlias
  • allPerson_assistant
  • allNumber
  • allNumber_work
  • allNumber_mobile
  • allNumber_main
  • allNumber_home
  • allNumber_work_mobile
  • allNumber_callback
  • allNumber_assistant
  • allNumber_company_main
  • allNumber_other_fax
  • allNumber_home_fax
  • allNumber_work_fax
  • allNumber_pager
  • allNumber_work_pager
  • allNumber_car
  • allNumber_radio
  • allNumber_tty_tdd
  • allNumber_isdn
  • allNumber_telex
  • allNumber_other
  • allNumber_grand_central
  • allEmail
  • allEmail_work
  • allEmail_other
  • allEmail_general
  • allEmail_home
  • allImAddress
  • allImAddress_aim
  • allImAddress_google_talk
  • allImAddress_icq
  • allImAddress_jabber
  • allImAddress_msn
  • allImAddress_netmeeting
  • allImAddress_qq
  • allImAddress_skype
  • allImAddress_yahoo
  • allWebsite
  • allWebsite_blog
  • allWebsite_ftp
  • allWebsite_home
  • allWebsite_home_page
  • allWebsite_other
  • allWebsite_profile
  • allWebsite_work
  • allAddress
  • allAddress_work
  • allAddress_home
  • allAddress_other
  • allCity: Microsoft domains only.
  • allCity_work: Microsoft domains only.
  • allCity_home: Microsoft domains only.
  • allCity_other: Microsoft domains only.
  • allState: Microsoft domains only.
  • allState_work: Microsoft domains only.
  • allState_home: Microsoft domains only.
  • allState_other: Microsoft domains only.
  • allCountry: Microsoft domains only.
  • allCountry_work: Microsoft domains only.
  • allCountry_home: Microsoft domains only.
  • allCountry_other: Microsoft domains only.
  • allPostCode: Microsoft domains only.
  • allPostCode_work: Microsoft domains only.
  • allPostCode_home: Microsoft domains only.
  • allPostCode_other: Microsoft domains only.
  • allStreet: Microsoft domains only.
  • allStreet_work: Microsoft domains only.
  • allStreet_home: Microsoft domains only.
  • allStreet_other: Microsoft domains only.
  • ouPath: Reversed (immediate parent first) list of OU path components. Google domains only.

 

Configuration Tips

The CloudM Automate user variables available to the cn and attribute templates are not automatically mapped to a format suitable for LDAP. One example where this may be a problem is the manager attribute, which is an email address in CloudM Automate but might need to be a DN in the LDAP entry. To map this, you can use:

<attribute name="manager" emptyAllowed="false" trimWhiteSpace="true">#if(${manager}) $ldap.FindDn("userPrincipalName", $manager) #end</attribute>

This will attempt to search the LDAP directory from the configured root DN for an entry with attribute userPrincipalName equal to the user’s manager email address.

 

Kestrel Certificate Configuration

If you are using a HTTPS connection for the connector, it will be necessary to configure the Kestrel settings stored in the appsettings.json file. 

It is possible to set the connector to use HTTP, although this is not recommended if accessed externally. If HTTP is used, there is no need to provide the Kestrel certificate settings.

This will be located in the install directory, which by default, will be C:\Program Files\CloudM\ADSync.

Go to this directory and edit appsettings.json

 

At the top of the Settings file, after the initial “{“ add the following:

"Kestrel": { 

   "Certificates": { 

     "Default": { 

       "Path": "c:\\ADsync\\Certs\\adsyncexample.pfx", 

    "Password" : "examplepassword", 

       "AllowInvalid": "true" 

     } 

   } 

 },

 

You will need to update the Path to your certificate file and the certificate Password.

If you are using self-signed certificates, you will need to set AllowInvalid to true. Otherwise, this can be removed or set to false.

Was this article helpful?
0 out of 0 found this helpful