How to configure a new connection to integrate with, or import user details from, an LDAP directory, such as Active Directory (AD).
Halo allows you to configure, import from, and sync with an LDAP directory (such as Active Directory). This is mainly used to easily keep your user and/or agent list up to date with the users in Active Directory.
Adding a New Connection
To set up a new LDAP connection, browse to:
Configuration>Integrations>Active Directory
Here you will see a list of your current connections and a 'New' button to add a connection. Click the button and you'll see the connection configuration, which will include four tabs:
1. Details – the details that allow Halo to connect to the LDAP/AD and other settings specific to this connection.
2. Field Mappings – the association between fields in Halo and the LDAP/AD. These are pre-populated with common mappings for Active Directory.
3. Agent/User Mappings – the association between sites or agents in HALO and organizational units and/or containers in LDAP/AD.
4. CAB Mappings – the association between Change Advice Boards in HALO and organizational units and/or containers in LDAP/AD.
Details
First, let’s complete the connection credentials. Required fields are designated by a red asterisk *
• Host Name/IP Address * ‘Hostname’ or IP Address of your Domain Controller (DC) where the LDAP/AD resides.
• Domain Name * The name of the domain that LDAP/AD is associated with for example: "MyCompany.local"
• Authentication Type * The authentication method used by your LDAP. Basic is the most common choice.
• Username * This is the username for the service account used to access the Domain Controller.
• Password * Password for the service account.
• Port Blank unless you're using a non-default LDAP port.
• SSL Unchecked unless you're using an encrypted LDAP connection (LDAPS).
• Base DN * for the MyCompany.local example:"DC=Local,DC=MyCompany"
If you don’t know any of these then your LDAP/AD administrator should be able to advise. Once you have all the required fields populated, you can use the ‘Test’ button to confirm that the credentials you’ve entered work. Note that this test runs from the web server, not your browser, so if the web server is blocked from connecting to the LDAP/AD then the test will fail. This would often be the case for hosted customers. However, it is possible to use the Integrator application to run the LDAP/AD sync locally to avoid this issue. More on this later.
If the credentials do not test correctly then it is likely that a network problem or an issue with the credentials. It would be best to check with your LDAP/AD or network administrator to make sure everything is correct.
Under 'AD Authentication' you can select whether you want your Halo Agents and Users to be able to login using Active Directory rather than the standard Halo login method. Note that this doesn't mean that Halo will sync and store the agent/user passwords from AD (this is not possible) but rather that authentication will be passed through to AD when the user logs in.
You can also choose if you want to enable this AD connection to be synced by the Integrator application. You can find more information about this in our Halo Integrator guide.
Field Mappings
The Field Mappings tab is where you configure the link between data fields in Active Directory and and Halo. A list of default mappings will pre-populate in here, which are suitable for most integrations, but you may wish to make some adjustment. In the 'Helpful Information' section at the bottom of this guide you'll find a listing of most of the LDAP/AD fields and a description of their content, as well as the Halo agent and user fields.
Agent/User Mappings
This tab allows you to specify which containers and organisational units in LDAP/AD map to which sites (or as an agent) in Halo. If you have the page in Edit mode, then you'll see a button for 'Create Mappings Using AD Explorer'. This function will only work if the LDAP/AD is accessible and makes it much easier to create your Agent/User mappings. Otherwise, you can add mappings manually, but you'd have to type out the AD object reference for each mapping and you won't be able to verify it's correct before saving, so this guide will assume you're using the AD Explorer.
Opening the AD Explorer will load a list of all currently mapped containers/objects from the LDAP/AD. Checking the 'Show All Containers' checkbox will allow you to select other containers to add new mappings. When adding a mapping, you will be asked to select a:
• Site * This is the site/location in Halo that the LDAP/AD object will map to. I.e. the users in the LDAP/AD container will be created under this site. You can also select *Agent* which will cause users in the container to be created as Agents in Halo, rather than Users.
• Mapping Type * This defines which users associated with the object in LDAP/AD are to be created in Halo. You can specify that just users directly in the object are synced, all users within objects that are within the selected object, or even all users that have a 'Member of' relationship with the selected object, but don't necessarily exist within the object.
• Role for Agents This is only used for Agent mappings and specifies the default Role permissions that Agents created from LDAP/AD sync should be given.
• LDAP filter You can also add an LDAP filter here, which can be used to filter out users within (or members of) the object that you don't want to import into Halo. This filter uses standard LDAP filter syntax so you'll find plenty of other resources online that will assist in writing an LDAP filter.
CAB Mappings
The CAB (Change Advice Board) mappings allow you to relate a CAB (used in Change Management processes) in Halo to objects in LDAP/AD in the same way that they can be related to Sites/Locations mentioned above.
That's it! Hit save and you've now set up an LDAP/AD connection and can initiate a sync in your browser from the Details tab. You can also schedule the sync using the Integrator application. See our integrator guide on how to set this up.
Helpful Information
LDAP field names
PLEASE NOTE: The label seen in active directory is often different to the field name.
|
LDAP Attribute |
Example |
|
CN – Common Name |
CN=Guy Thomas. Actually, this LDAP attribute is made up from givenName joined to SN |
|
description |
What you see in Active Directory Users and Computers. Not to be confused with displayName on the Users property sheet. |
|
displayName |
displayName = Guy Thomas. Avoid this attribute if possible, as it can be confused with CN or description. |
|
DN – also distinguishedName |
DN is simply the most important LDAP attribute. CN=Jay Jamieson, OU= Newport,DC=cp,DC=com |
|
givenName |
First name |
|
homeDrive |
Home Folder : connect. |
|
name |
name = Guy Thomas. Exactly the same as CN. |
|
objectCategory |
Defines the Active Directory Schema category. For example, objectClass = Person |
|
objectClass |
objectClass = User. Also used for Computer, organizationalUnit, even container. Important top level container. |
|
physicalDeliveryOfficeName |
Office on the user's General property sheet |
|
profilePath |
Roaming profile path: connect |
|
sAMAccountName |
sAMAccountName = guyt. Old NT 4.0 logon name, must be unique in the forest. Can be confused with CN. |
|
SN |
SN = Thomas. This would be referred to as last name or surname. |
|
userAccountControl |
Used to disable an account. A value of 514 disables the account, while 512 makes the account ready for logon. |
|
userPrincipalName |
userPrincipalName = guyt@CP.com Often abbreviated to UPN, and looks like an e-mail address. Very useful for logging on especially in a large Forest. Note UPN must be unique in the forest. |
Exchange Specific LDAP attributes
|
LDAP Attribute |
Example |
|
homeMDB |
Here is where you set the MailStore |
|
|
An easy, but important attribute. A simple SMTP address is all that is required billyn@ourdom.com |
|
mAPIRecipient – FALSE |
Indicates that a contact is not a domain user. |
|
mailNickname |
Normally this is the same value as the sAMAccountName, but could be different if you wished. Needed for mail enabled contacts |
|
mDBUseDefaults |
Another straightforward field, just the value to:True |
|
msExchHomeServerName |
Exchange needs to know which server to deliver the mail. e.g: /o=YourOrg/ou=First Administrative Group/cn=Configuration/cn=Servers/cn=MailSrv |
|
legacyExchangeDN |
Legacy distinguished name for creating Contacts. In the following example, Guy Thomas is a Contact in the first administrative group of GUYDOMAIN: /o=GUYDOMAIN/ou=first administrativegroup/cn=Recipients/cn=Guy Thomas |
|
proxyAddresses |
As the name 'proxy' suggests, it is possible for one recipient to have more than one e-mail address. Note the plural spelling of proxyAddresses. |
|
targetAddress |
SMTP:@ e-mail address. Note that SMTP is case sensitive. All capitals means the default address. |
|
showInAddressBook |
Displays the contact in the Global Address List. |
Other LDAP attributes
|
c |
Country or Region |
|
company |
Company or organization name |
|
department |
Useful category to fill in and use for filtering |
|
homephone |
Home Phone number, (Lots more phone LDAPs) |
|
l (Lower case L) |
L = Location. City (Maybe Office) |
|
location |
Important, particularly for printers. |
|
manager |
Boss, manager |
|
mobile |
Mobile/Cell Phone number |
|
ObjectClass |
Usually User, or Computer |
|
OU |
Organizational unit. See also DN |
|
postalCode |
Zip or post code |
|
st |
State, Province or County |
|
streetAddress |
First line of address |
|
telephoneNumber |
Office Phone |
Halo Agent Fields for LDAP Sync
|
Agent Field |
Database Field Name |
|
Agent / Technician Name |
Uname |
|
Email Address |
USMTP |
|
IP Address / PC Name |
UPC |
|
Telephone Number |
USMS |
|
Job Title |
UJobTitle |
|
Secondary Telephone Number (Used on Call Screens) |
UExtensionNumber |
Halo User Fields for LDAP Sync
|
User Field |
Database Field Name |
|
Username |
Uusername |
|
Title |
Utitle |
|
Email Address |
Uemail |
|
Additional Emails |
Uemail2 |
|
LDAP Proxy Email |
Uemail3 |
|
Network Login |
Ulogin |
|
Work Direct/Extn. |
Uextn |
|
Work General |
(set at site level) |
|
Work Mobile/Cell |
Umobile2 |
|
Home Mobile/Cell |
Umobile |
|
Home Fixed |
Utelhome |
|
Fax Number |
Ufax |
|
User Defined 1 |
Uother1 |
|
User Defined 2 |
Uother2 |
|
User Defined 3 |
Uother3 |
|
User Defined 4 |
Uother4 |
|
User Defined 5 |
Uother5 |
|
Notes |
Unotes |
|
Twitter Screen Name |
Utwitterscreenname |
|
Disclaimer Matching String |
Ufacebookid |
Issue with Child Domains
When logged into one domain, if you try and do an LDAP sync to a child domain, then no users are listed. There is no error message.
This is because the default domain context is taken to be the domain into which you are logged. This can probably be fixed by logging into the child domain.
Alternatively, specify the FDQN of the domain in the LDAP string. For example, it is possible to explicitly specify the FDQN of the LDAP server in the string. So instead of:
LDAP://CN=Users,DC=adw2k1,DC=co,DC=uk
You can say:
LDAP://adw2k1.co.uk/CN=Users,DC=adw2k1,DC=co,DC=uk
Put the child domains FQDN in the string instead to query the child domain.
