On-Premise Integration Connector Setup – CloudM

NOTE: We currently only support Apache Tomcat 9 or earlier. We are looking into adding support for Apache Tomcat 10.

Prerequisites

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

An on-premise directory with LDAPS access, such as Active Directory.
The Password Policy in CloudM Manage must match the Password Policy in Active Directory, where required, in order for passwords to update and sync correctly.
Apache Tomcat installed on a server running Windows or Linux that can:
- Connect to the on-premise directory over LDAPS.
- Connect to CloudM Manage over HTTPS.
- Accept incoming HTTPS requests from CloudM Manage.
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 Manage installed for your domain.
The shared secret from the CloudM Manage On-Premise Integration page.

Setup

To install CloudM Manage On-Premise Integration version 2.00, download the installation script to your Apache Tomcat server and run it: connector-installer.ps1 (for a Windows server) or connector-installer.sh (for a Linux server). Alternatively, you can download cloudm-connector.war, manually install it to Tomcat and manually edit options.xml.

The script will prompt for:

Your CloudM Manage On-Premise Integration shared secret (e.g. 0123456789abcdef).
Your primary domain (e.g. example.com).
The IP address of your LDAPS server (e.g. 127.0.0.1).
The full DN and password of the admin account that can be used to create, update and delete user accounts over LDAPS.
The root DN containing the users that the connector should create, update and delete. Note that if your domain is on Google this container should mirror the OU tree of your users in G Suite. The way OU's are mapped can be changed later (see Further Configuration).
A template to be used to construct the CN of users that the connector should create, update and delete. This template must match the CN of existing users to allow them to be modified by the connector. The default of ${firstName}.${lastName} is usually appropriate.
The full path to the Tomcat installation folder. This folder should contain the webapps sub-folder.

The script will then download the CloudM Connector, configure it with the answers you provided and install it to Tomcat.

If your domain is on Microsoft, you will then need to edit the connector options which are stored in an XML file within the Tomcat installation folder: webapps/cloudm-connector/WEB-INF/classes/options.xml. Change the line <certUrl>https://mycloudpages.appspot.com/certs</certUrl> to <certUrl>https://manage365.cloudm.co/certs</certUrl> and reload the cloudm-connector application within Tomcat or restart Tomcat. If your domain is on Google, you do not need to change this line.

Now the CloudM Connector is installed, you can:

Enable on-premise integration in CloudM Manage.
Specify the endpoint as https://1.2.3.4:8443/cloudm-connector/connector where 1.2.3.4 is the IP address of the machine running Tomcat and 8443 is the port that Tomcat listens on.
Click the test button. CloudM Manage 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 Tomcat server. They should be available in the logs folder within the Tomcat installation folder. The CloudM Manage specific logs are prefixed with ‘cloudm-connector-’. 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 Manage 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 Tomcat installation folder: webapps/cloudm-connector/WEB-INF/classes/options.xml. Any changes made to this file will only take effect when the cloudm-connector application within Tomcat is reloaded or Tomcat is restarted.

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>
  <ldapId>cn=admin,o=example</ldapId>
  <ldapPassword>secret</ldapPassword>
  <ldapRootDn>o=example</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.
ldapId: the full DN to the admin account used to perform operations (not just the relative DN from the root DN). This is set by the installation script.
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 Manage. 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 Manage. 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 Manage respectively. If set to unicodePwd, then it will set the unicodePwd LDAP attribute if “Include AES Encrypted Password” is enabled in CloudM Manage. 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 Manage 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 Manage. Defaults to true.
onCreate: Include this attribute when a user is created in CloudM Manage. Defaults to true.
onRename: Replace the attribute when the user is renamed in CloudM Manage. Defaults to false.
onMove: Replace the attribute when the user is moved in CloudM Manage. Defaults to false.
onPassword: Include this attribute when a user's password is changed in CloudM Manage. 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 Manage 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 Manage 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 Manage. 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 Manage 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 Manage 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.