On-Premise Integration Connector Setup

Shaun Richards

Updated August 02, 2023 15:58

Prerequisites

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

An on-premise directory with LDAPS access, such as Active Directory.
- Please refer to this Microsoft Tech Community article for details on setting up LDAPS on Windows Server,
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

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

Download the installer to your Windows machine.
Open the installer.
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

Google domains - https://mycloudpages.appspot.com/certs
Microsoft domains - https://manage365.cloudm.co/certs

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

Now the CloudM Connector is installed, you can:

Enable on-premise integration in CloudM Automate.
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
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.