Articles in this section

On-Premise Integration Connector Setup

  • Updated
Follow

Prerequisites

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

  • An on-premise directory with LDAPS access, such as Active Directory.
  • 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:

  1. Enable on-premise integration in CloudM Manage.
  2. 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.
  3. 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.

 

Comments

0 comments

Please sign in to leave a comment.