Using Active Directory and LDAP for AAA in Unimus
In this guide, we would like to show you how to pair your Active Directory with Unimus and use LDAP for the AAA.
We will be focusing on AD running on Windows Server, and we will assume you have your server already set up with Active Directory.
Preparing for LDAP - Organizational structure in Active Directory
As LDAP is integrated and available in Active Directory by default, let's start by briefly showcasing the simple, exemplary organizational structure we created in Active Directory Users and Computers:
We created a simple structure of a couple of child Organizational Units (OUs) under the unimus.local domain, more specifically unimus.local > Unimus > Unimus Admins.
Let's take another look at them in the ADSI Edit utility, where we can have a better view of their Distinguished Names (DNs):
ADSI Edit gives us a more useful (for us in this context) view of our organizational structure. We can see how each object chains and contributes to the DN of our target OU Unimus Admins.
OU=Unimus Admins,OU=Unimus,DC=unimus,DC=local
This DN will serve as a Base DN in Unimus for the lookup of the objects (users) based on an User Identifier attribute we will choose. As per Unimus' LDAP documentation (more on this later), we need to specify a Base DN which will serve as the root point for Unimus to search users from.
The last thing to look at is one of our users. Let's pick Jane Doe as an example and see how this user's DN looks:
CN=Jane Doe,OU=Unimus Admins,OU=Unimus,DC=unimus,DC=local
This is Jane Doe's DN; however, we don't have to use this full DN to identify Jane Doe. We can choose whichever of the available attributes of this account to use - assuming these attributes exist and do not have blank values. By right-clicking Jane Doe's record and choosing Properties, we can see the Attribute Editor, where we can examine and edit existing attributes or add new values to other unused attributes:
In this view, we can sort values so that we see all non-blank attributes together. In typical Windows AD deployments, you usually use the sAMAccountName attribute to lookup AD users instead of the DN. This is typically the username for Windows AD logins, so we will use this for the configuration in Unimus as well.
LDAP integration in Unimus
Before we jump into the configuration section, let's start with some details on how LDAP auth works in Unimus. The process of authenticating a local user in Unimus against an external LDAP is done in two stages.
1) In the first stage, the Unimus LDAP client logs into the LDAP directory using the provided server details and accesses user credentials (DN and password). If the login is successful, Unimus will search for the provided user (the user attempting to log into Unimus) in the target directory tree defined by a base DN. If the user is matched using any configurable attribute (the User Identifier), Unimus proceeds to the second stage.
2) In the second stage, Unimus uses the previously matched provided username to retrieve the full user DN and attempts to authenticate the user with the provided password. If the authentication succeeds, the user is logged into Unimus.
For more details about authentication, security options, and OpenLDAP / AD configuration examples, we recommend taking a minute to check out our Wiki article, which goes over all of the above and more: https://wiki.unimus.net/display/UNPUB/LDAP+Auth
The LDAP Access User
As mentioned above, we need an Access User which will be used to find the exact account trying to log in to Unimus. The Access User can be any LDAP account that has access (read-only access is sufficient) to the LDAP tree under which your login users exist. More info in the Wiki articled mentioned above.
The Access User of course also needs to be able to "see" the user account objects as well, not just the OUs in your directory.
Unimus configuration - Configuring LDAP
You can configure LDAP in User management > LDAP configuration:
Where:
LDAP server address - the address of your domain controller.
LDAP port - the default port is 389.
LDAP access user DN - full DN of the user able to access AD records.
LDAP access password - a password for the access user.
Security - an optional security measure for LDAP transmission. Both LDAPS and StartTLS require respective server-side (the LDAP server) configurations.
Note, if you opt to use LDAPS or StartTLS including certificate validation, you can follow our guide on importing CA certificates in Unimus; both require importing your CA to the system's Java KeyStore. You don't need to do this if you enable Do not check certificate to skip LDAP cert validation.
LDAP base DN - the DN of the root of the tree storing user records, which Unimus will be authenticating login attempts against.
User identifier - an identifier that Unimus uses to match users in LDAP to retrieve user's full DN for auth purposes. You can use any attribute that suits your needs. For example, you can use CN, sAMAccountName, uid, etc.
LDAP filter - an optional LDAP filter to further filter matches in the given base DN. Standard LDAP filter syntax is supported.
Unimus configuration - Adding LDAP accounts to Unimus
Unimus currently requires every external user account to have a matching account in Unimus. You can create a user in User management > Users:
Where:
Username - the matching username for the external account in Active Directory.
Authentication method - LDAP.
Select access role - select which role the user will represent.
At this point, users should be able to log into Unimus using LDAP and their external account credentials.
Troubleshooting
There are generally two troubleshooting sources for any issue with LDAP AAA. Unimus log and AD debug logging on Windows Server. We actually recommend focusing on Unimus log, as it features full LDAP error codes without any additional configuration, which is not the case with AD debug logging (which requires manually specifying logging levels for all AD components).
Let's take a closer look at a couple of exemplary error messages you could encounter and their likely cause:
Ldap authentication failed: '10.20.30.40:389; nested exception is javax.naming.CommunicationException: 10.20.30.40:389 [Root exception is java.net.ConnectException: Connection refused (Connection refused)]'This error indicates a wrong configuration (wrongly specified IP and / or port) or a network issue (likely a firewall).
Ldap authentication failed: '10.20.30.40:636; nested exception is javax.naming.CommunicationException: 10.20.30.40:636 [Root exception is javax.net.ssl.SSLHandshakeException: Remote host terminated the handshake]'This error indicates an issue with LDAPS or StartTLS configuration, e.g. Unimus has LDAPS or StartTLS checked, but the server doesn't use either or is not set up for either, or the server is missing an SSL certificate for the LDAP server. In the latter case, refer to the section above where we mention what is required for a certificate to be recognized.
Ldap authentication failed: '[LDAP: error code 49 - 80090308: LdapErr: DSID-0C09041C, comment: AcceptSecurityContext error, data 52e, v4563]This error indicates incorrect credentials. These can indicate any combination of wrong credentials (DN or password) for the access user or a wrong password provided for the Unimus user to be authenticated.
Ldap authentication failed: 'Incorrect result size: expected 1, actual 0'This error indicates the access to LDAP was successful, but given the base DN and input in the username field, no match for the given user was found. Possible causes include:
- Wrong username input and / or the user was not found when searching under the Base DN. Check the username and / or the Base DN.
- The User Identifier is incorrectly configured. Check if the identifier is correct for your LDAP objects.
- The provided base DN does not contain a user identified by the configured User Identifier (similar to the 2 points above). Check if the user you want to auth has the identifier you are using.
- An LDAP filter specifying conditions the user does not comply with. Check if your filter properly returns the user you want to auth.
Final words
Hopefully this article can guide you through connecting Unimus with Active Directory via LDAP. If you have any questions, or you run into any issues, please feel free to post in the Support section of our forums, or contact us through our usual support channels.