Tuesday, October 4, 2016

Dealing with LDAP in MAX Mail

Supporting all product for LogicNow one of the areas that people tend to find challenging is setting up LDAP for MAX Mail.  As a result I wanted to write an article to help guide people through the various setup options and troubleshooting LDAP.     

LDAP is a great way to auto manage your users in MAX Mail with minimal input required from an admin perspective.  If you have only one domain and intend to sync all users in that domain the process is not overly complicated but as part of this article we will look at the following

  1. Simple LDAP Synchronisation with one domain looking at all users
  2. Using LDAP to retrieve alias email addresses
  3. Using LDAP to retrieve sibling email address
  4. Targeting specific users only in your domain controller
  5. Troubleshooting LDAP 

So let’s run through each of these topics and hopefully provide a bit of insight into how LDAP works with MAX Mail

 Simple LDAP Synchronisation with one domain looking at all users

First of all let’s look at the most basic type of LDAP sync where we only have one domain to deal with and we want to synchronise all users and distribution groups.  

For the purpose of this section I am going to refer to the domain name as ‘myprimarydomain.com’ and we will assume that all of the inbound and outbound filtering settings have been configured.  We now want to add users via LDAP and in order to access these settings we would need to follow through these steps in MAX Mail

  • Click on Management in the upper right hand corner
  • Choose Users from the black menu bar
  • In the left hand side menu choose Synchronisation (LDAP, etc.)
  • Select LDAP Synchronisation from the drop down menu and click Save Changes
If all goes well you should see the LDAP configuration page.

Now that we are at the LDAP settings we can look our domain controller and decide which containers to target in Active Directory.  In this LDAP sync we are going to target ‘SBSUsers’ 

Getting back to MAX Mail we need to run through these LDAP config fields entering the following information

LDAP Connection Settings:

HOST (IP ADDRESS OR NAME): This is where you enter the IP address or public hostname of your domain controller

PORT: Choose port 389 for a standard LDAP connection or port 636 for a secure LDAP connection

USE SSL TO CONNECT: Choose whether to enable SSL when connecting via LDAP (not required)

LDAP Login/Query Settings:

BIND DN (LDAP USERNAME): This is where you enter a username which has domain admin rights on the local domain.  Check the membership of this user and ensure they are an admin otherwise the LDAP sync will fail

PASSWORD: The password for the domain admin account you intend on using

SYNCHRONISATION INTERVAL: How often MAX Mail will connect to your domain controller and synchronise users

BASEDN: Configure your target container in Active Directory here.  The format of this field is in reverse order so you put the lowest level container first and work your way up to domain level.  Using the screenshot provided earlier we can confirm the target as


This would result in the following being entered into the BASEDN field

OU=SBSUsers, OU=Users, DC=contoso, DC=local

TYPE OF LDAP SERVER: Choose your LDAP server type.  In most instances this will just be ‘Active Directory’

Override Existing Records:

ALLOW UPDATES?:  This will update existing user settings e.g. pulling in any new alias email addresses that were added to a user within their local mail environment

ALLOW DEACTIVATIONS?: Any users that get removed or disabled from Active Directory will automatically be removed from MAX Mail as a result

Advanced LDAP Query Settings:

These are the filter settings for MAX Mail and in the vast majority of cases you can just click on the prepopulate link to automatically populate this for you (shown below) 

Prepopulate the filter and attribute settings below based on my LDAP server type.

The only time you would need to enter information manually into this section would be to retrieve alias and sibling email addresses which are covered in the next sections.

Let’s assume we have our LDAP setup the settings should now look like this

All we need to do now is click on the ‘Preview and Save Changes’ button at the bottom to start the sync.  You will know if this is successful as you will see a preview of the users found.  If any errors appear please see the last section for more info on troubleshooting LDAP.

 Using LDAP to retrieve alias email addresses

The previous method outlines how to synchronise users if they have one email address but what happens if a user has alias email addresses attached to their account as well?  The only thing we need to look at here is changing the LDAP filter settings to target these other addresses.

In this example we will assume the following details

Domain: myprimarydomain.com
User Primary Email Address:  colin@myprimarydomain.com
User Alias Email Address: col@myprimarydomain.com

Previously we would have needed the following LDAP filter settings

But now we need change the following fields in the row called MAIL to target alias email addresses of the same domain

REG.EXPR. = ([^@]+)@(.+)$
FORMATTER = {0}@<domain name>

So in this example all we would need to enter is

REG.EXPR. = ([^@]+)@(.+)$
FORMATTER = {0}@myprimarydomain.com

The resulting filter in this instance can be seen below

From there just run your ‘Preview and Save Changes’ button at the bottom and columns for alias email addresses should now appear. 

Using LDAP to retrieve sibling email addresses that are aliases

So far we have looked at LDAP synchronisation with one domain only.  What happens when you want to introduce 2 domains into the mix?   2 particular scenarios are

      a)   I have a user who doesn’t have an email address for the primary domain.  The main email address on their mailbox is one of the sibling domains in MAX Mail

      b)   My user has an alias email address for a sibling domain

In this section we will have a look at how to manage primary and sibling domains as part of the LDAP synchronisation process but before we look at how to configure LDAP for sibling domains we need to understand how sibling domains work in MAX Mail.    I’ve put a little explanation of this below to help you better understand how these sibling domains and email addresses are managed.

How Sibling Domains work:

When adding a sibling domain to an account you do not need to make any other configuration changes as for every user that exists in your control panel the sibling email address will automatically be included as part of that account.  Unfortunately you cannot add a new user account with the sibling email address as the primary email address.  If you wanted to add a user with the sibling domain address (even though it has not email address for the primary domain) the best way to do this is to create the email address using the primary domain of the account.  This would mean the sibling email address would automatically add to the account e.g.

If you have 2 domains

Primary – myprimarydomain.com
Sibling – mysiblingdomain.com

And if you just want to add the user test@mysiblingdomain.com what you would have to do is add the user test@myprimarydomain.com to your account.  Even though you may not use the test@myprimarydomain.com account mail would still flow for the test@mysiblingdomain.com.  Basically you are creating a dormant primary email address in order to add the sibling email address.

In short you will not need to make any changes for scenario A that was previously mentioned as Max Mail will automatically retrieve their email address and re-write it as an email address for the primary MAX Mail domain.

For scenario B where the user has an alias at the sibling we are going retrieve the sibling email addresses and re-write their domain to the primary one (much in the same fashion as scenario A).  If we have a user with the following email addresses

User Primary Email Address: colin@myprimarydomain.com
User Sibling Alias: CM@mysiblingdomain.com

After performing an LDAP sync MAX Mail would pull in this user’s email addresses as


The reason for this is that MAX Mail needs to have every email address showing as the primary domain and just assumes the sibling exists (as per the ‘How do Sibling Domains work’ section).

The configuration for this is exactly the same as targeting alias email addresses so we would enter the following information

REG.EXPR.: ([^@]+)@(.+)$
FORMATTER: {0}@<domain>

For this specific example we would then enter

REG.EXPR. = ([^@]+)@(.+)$
FORMATTER = {0}@myprimarydomain.com

What would happen is every sibling email address that is pulled in (whether a primary or alias email address) will be re-written so that it appears as an alias of the primary domain.  Remember that even though the email addresses all appear to show as the primary domain only MAX Mail will also assume there is an equivalent email address for each sibling domain you enter

Targeting specific users only in your domain

When it comes to using LDAP an IT Admin may not want to synchronise all users across to MAX Mail.   A couple of common examples I see related to this are

          a)   What happens if we want to target a specific container in Active Directory and only synchronise half of the users in that container

          b)   What happens if we want to target a top level container but there is one sub container we do not want to sync to MAX Mail

The easiest method here is create a security group and add in any members that you do not want included as part of the LDAP search.  We will then use the MAX Mail LDAP filters to exclude any users in this group from the LDAP sync. 

A typical LDAP filter string for targeting all users would look like the following:


In order to exclude your security group from the filter you would change the following

memberOf=cn=GrouptoExclude - change the 'GrouptoExclude' to the name of the security group you set up for exclusions

ou=XXXX,ou=XXXX = This is where you set the OU of your security group

DC=domain,DC=local - Enter the local domain of the domain controller

So using this if I would create a group called ‘NotMaxMailUsers’ and put them in the following container

colin.local/MyBusiness/Security Groups/

Making all of the changes mentioned above the new filter would look like this

(&(|(objectClass=User)(objectClass=person)(objectclass=group)(objectclass=PublicFolder))(mail=*)(!(userAccountControl:dn:1.2.840.113556.1.4.803:=2))(!(memberOf=cn=NotMaxMailUsers,ou=Security Groups,ou=MyBusiness,DC=colin,DC=local)))

Now you can actively add or remove users to the security group as a means of controlling who will get pulled in as part of the security group. 

Troubleshooting LDAP

Hopefully now you should all be LDAP sync masters but inevitably errors may appear at points.  When you run an LDAP sync in MAX Mail you will know if this is successful straight away as you will get a preview of the users.  Where this has not been successful MAX Mail throw an error message at you that whilst initially not appearing that helpful it does actually contain useful info.

I want to first have a look at an example error message from the LDAP sync

Users are unable to log in. The following appears in the atlassian-confluence.log:
javax.naming.AuthenticationException: [LDAP: error code 49 - 80090308: LdapErr: DSID-0C0903A9, comment: AcceptSecurityContext error, data 701, v1db0]

It does initially appear as though there is any helpful information here but the LDAP error code is exactly the info we need to troubleshoot this.  We have 2 key bits of information here which are

LDAP:error code 49
data 701

With regards to the first error we can see this is 49 and looking at a list of the errors (link here) we can see this is appears to be an authentication problem. 

The 701 message that displays is linked to another set of LDAP codes which I have put below

525 - User not found
52e - invalid credentials
530 - not permitted to logon at this time
531 - not permitted to logon at this workstation
532 - password expired (remember to check the user set in osuser.xml also)
533 - account disabled
701 - account expired
773 - user must reset password
775 - user account locked

This once again confirms the problem is with the user account so we now know where to troubleshoot to resolve this problem.

Hopefully after this you will be a bit more comfortable with LDAP and managing it with multiple domains but if anyone has questions please feel free to put them in the comments and I'll get back to you asap.

Happy LDAP'ing everyone :)