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
- Simple LDAP Synchronisation with one domain looking at all users
- Using LDAP to retrieve alias email addresses
- Using LDAP to retrieve sibling email address
- Targeting specific users only in your domain controller
- 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
Contoso.local
>Users
>>SBSUsers
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
ATTRIBUTE = mail
REG.EXPR. = ([^@]+)@(.+)$
FORMATTER = {0}@<domain name>
So in this example all we would need to enter is
ATTRIBUTE = mail
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
colin@myprimarydomain.com
CM@myprimarydomain.com
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
ATTRIBUTE:
mail
REG.EXPR.:
([^@]+)@(.+)$
FORMATTER:
{0}@<domain>
For
this specific example we would then enter
ATTRIBUTE = mail
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:
(&(|(objectClass=User)(objectClass=person)(objectclass=group)(objectclass=PublicFolder))(mail=*)(!(userAccountControl:dn:1.2.840.113556.1.4.803:=2))(!(memberOf=cn=GrouptoExclude,ou=XXXX,ou=XXXX,DC=domain,DC=local)))
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 :)