LDAP Integration – Customer Support

Introduction

The LDAP Module provides the ability for NetX to authenticate users via an external LDAP-compliant Directory Server. Microsoft Active Directory, SunOne Directory Server, OpenLDAP, and Novell eDirectory are all examples of LDAP compliant directory servers.

Audience

The audience for this section includes System Administrators that are familiar with UNIX or Windows, XML usage, and LDAP and other Directory Server terms and concepts. It will be difficult to properly configure the communication to your Directory Server if you do not understand the role of a Directory Server, how your particular Directory Server is configured (such as schema specifics), and how you have organized your users (such as organizational units and the like).

This document assumes that the person responsible for connecting the application to an external Directory Server understands LDAP and Directory Server concepts. Further, each Directory Server is set up and configured differently than another. Different organizations will have very different hierarchies of users, organizational units, and role configurations. Also, Directory Server vendors use different schemas for how user data is maintained. This means that in order to successfully connect your Directory Server, it is helpful to be able to execute LDAP queries and view the internal schema so that you can test your configuration values.

While NetXposure fully supports this Module, it is your responsibility to understand and properly configure your application to communicate with your Directory Server. NetXposure can assist with examples, and will fix any identifiable bugs — but NetXposure will not be responsible for determining what valid property values are needed to match your Directory Server.

Assumed Resources (on-premise installations)

In order to utilize this section beyond just a general guide for understanding possible configurations, you will need some sort of text editor for making modifications to the exogen-config-LDAP.xml file. Any text editor should suffice, including Unix “vi”, Apple‘s TextEdit, and Microsoft‘s Notepad. Additionally, for your configuration changes to take affect, you will be required to restart your application. Therefore you will need to know how to accomplish this and have authority to do so. Please see Related Topics at the bottom of this article for more information on how to add/edit properties in NetX.

Configuration

This section details how to configure NetXposure to utilize an external Directory Server for its authentication service. This section will detail:

A list of the relevant configuration properties.
How the process works.
Different configuration types.
Technical notes on how to properly set the properties.

NetX Properties

The properties to note when activating the LDAP Module include the following (please refer elsewhere in this document for a detailed explanation of each property):

directory.authenticate_role_administrator
directory.authenticate_role_8 (Director)
directory.authenticate_role_manager
directory.authenticate_role_4 (Producer)
directory.authenticate_role_3 (Importer)
directory.authenticate_role_user (Consumer)
directory.authenticate_role_1 (Browser)
directory.authenticate_role_0 (No access)
directory.authenticate_role_1
directory.authenticate_role_3
directory.authenticate_role_4
directory.authentication
directory.connection_url
directory.connection_name
directory.connection_password
directory.email_field
directory.name_1_field
directory.name_3_field
directory.referrals
directory.role_base
directory.role_name
directory.role_search
directory.role_subtree
directory.user_base
directory.user_pattern
directory.user_search
directory.user_subtree
directory.accept_role_changes
user.directory_authentication
user.directory_auto_create_groups

The Process

When an external Directory Server is used for authentication, all logins will first authenticate against the Directory Server. If the credentials are properly authorized, then the following events occur:

The login and password are cached in the application database within the context of a User; if the User does not already exist, a new User is created.
All configured attributes — directory.email_field, directory.name_1_field, and directory.name_3_field —are copied over to the User‘s attributes.
If the “user.directory_auto_create_groups” property is not set to “false”, then any retrievable roles from the Directory Server are recreated as Groups in the Exogen-based application. Users are automatically linked to their respective Groups.
The username and password combination are added to a Login Cache, and are stored for 30 minutes, which reduces communication with the Directory Server.

If the application is configured with the “user.directory_authentication” property set to “any”, then the User database is also consulted for authentication is the Directory Server authentication fails (more details on this subject appear in the Configuration Types section of this document).

Verification Methods

The LDAP Module can be configured in one of two main ways in regards to how authentication is performed:

Each User‘s credentials is used to bind to the Directory Server; if the bind is successful, then the User is allowed to login, or
A single User‘s credentials are used to bind to the Directory Server, and then the authenticating User‘s credentials are verified; if the verification succeeds, then the User is allowed to login.

In the second case, the single user must be configured using the “directory.connection_name” and “directory.connection_password” properties. When setting these properties, they must correspond to an existing user in the Directory Server. Typically, the second scenario is best used for connecting to Active Directory. Other Directory Servers may find the first approach best.

Dual Authentication Configuration

Setting the user.directory_authentication to “true” will active the LDAP Module and Users will exclusively authenticate against the Directory Server. If the credentials are valid and if they match one of the roles, then that information is copied to the internal application User database for storage. While Administrators can update this stored information, the Directory Server data will overwrite the internal database information during successful logins.

However, you can utilize a hybrid approach — allowing authentication with Directory Server users and allowing other users to login who are only stored in the application database. In other words, you can authenticate against two separate user databases. To activate this type of LDAP configuration, please set the “user.directory_authentication” property value to “any” . In this case, all users in the Directory Server configured to authenticate can login; plus you can manually add users to the application, allowing users to login who are not stored in the Directory Server. This can be useful if you want to quickly add a User without having to add the user to the Directory Server.

Groups Management

While the Directory Server can dictate which User level to assign users, Group permissions are still controlled within the application. Adding users to the internal database prior to the information automatically transferring during logins will not cause any issues and can be helpful in setting up Group permissions prior to use.

Setting the “user.directory_auto_create_groups” property to “true” can help automate the construction and maintenance of Groups. When this property is set to “true”, all user roles within the Directory Server are copied as Groups within the application, and Users are linked to those copied Groups. In other words, all User roles are reflected as Groups within the application. This synchronization occurs every time a User logins, so updates to the Directory Server can be reflected in the application‘s Group database. However, this system can also produce a fair amount of clutter if users have many roles in the Directory Server.

Setting the "directory.accept_role_changes" to true will enable NetX to reflect a LDAP users removal from a group in LDAP

Speaking as Plainly as Possible

The fact is, setting up NetXposure Core with a Directory Server can be challenging because of how flexible and different all Directory Servers are. Different vendors — like Sun, Novell, and Microsoft — have divergent schemas. But this is only the start of the challenge; additionally, each vendor often allows for various configurations that make this integration less straight-forward than anyone would like.

This section hopes to speak plainly, then, about how all this works generally so you can understand the process clearly. Hopefully this will clear up some of the confusion created by the very technical nature of this chapter.

URL

First, the LDAP URL simply must point to an available Directory Server. Additionally a username and password is required so that NetXposure Core can properly bind (connect) to the Directory Server. Perhaps obviously, a Directory Server must be running at this provided address, and NetXposure must be capable of communicating to that server over the network. By default, standard LDAP runs on port 389, and with SSL on port 636.

Users

In order for a user to successfully login to NetXposure, the login credentials are passed to the Directory Server for verification. So, you have provide a configuration that provides a map for NetXposure to search and find the User object in the Directory Server so that the login credentials can be verified. And there are two, distinct ways to set this up:

User Pattern Search (directory.user_pattern)
User Base and Search (directory.user_base and directory.user_search)

These approaches are distinct and separate. But, they both are patterns to search and find user objects. So in the Sun example, the approach is a pattern:

directory.user_pattern

uid={0},ou=yourcompany,o=internal

This is a pattern where the {0} is replaced with the login username.

Or, you can use the other method provided in the Active Directory example:

directory.user_base

CN=Users,DC=www,DC=yourcompany,DC=com

directory.user_search

(samAccountName={0})

Here, this is saying, “search the base (CN=Users,DC=www,DC=yourcompany,DC=com) for objects that match the search (samAccountName={0}). Again, where {0} is replaced with the login username.

Assuming this search successfully found a user object, then the password is used to verify the credentials. Assuming this is also successful, then the object is asked for the users’s email, first and lastname. The fields in the LDAP user object that are used to define these data, are defined in these properties:

directory.email_field
directory.name_1_field
directory.name_3_field

And examples for these are provided below. These property values must correspond to attributes of user objects in your Directory Server.

Roles

In order to obtain roles from the Directory Server — used to create Groups in NetXposure Core — you need to set-up role searching in a similar manner as the user search above. In this case, there is a base (search point), a search (match pattern), and a name (attribute of returned objects). For example:

directory.role_base

CN=Users,DC=www,DC=yourcompany,DC=com

directory.role_name

memberOf

directory.role_search

(cn={1})

This defines the search point to begin at the defined CN. Next, the search defines the pattern to match. Eg:

(cn={1})

or perhaps:

(samAccountName={1})

In this case, the {1} is replaced with the username.

So far, we should have objects that match the pattern above under the base defined. Lastly, the “directory.role_name” defines the object attribute that provides the name of the role (which will then become a Group in NetXposure).

In Active Directory, the roles are listed with the user. So the provided example has a role search that is essentially the same as the user search — the role search returns user objects. And those objects are then queried about their “memberOf” attribute, should will be a list of all linked roles in Active Directory.

Hopefully it’s becoming clear how many configurations are possible to essentially do the same thing, and why each Directory Server deployment will require a slightly different NetXposure configuration.

User Levels

The last piece of the puzzle is properly defining the “authenticated_role” properties:

directory.authenticate_role_administrator
directory.authenticate_role_consumer
directory.authenticate_role_manager
directory.authenticate_role_1
directory.authenticate_role_3
directory.authenticate_role_4

The values for these properties must be roles of the user, and these define the user level (eg “Consumer” or “Administrator”). If an “authenticate_role” match is not found, then the user is denied access to NetXposure.

So, to get here, you have to have successfully configured user and role searching and matching. Assuming this is true, now, one of the returned role names must be in one of these defined user levels.

An example will probably help. So, we have user “Jason” and Jason has three returned roles: “Role 1”, Role 2”, and Role 3”. So, assuming Jason logs in correctly, then those roles are automatically added as Groups into NetXposure (assuming there are not already present). But the last part is what user level will Jason access NetXposure as? So let’s assume that the value of the “directory.authenticate_role_administrator” property is “Role 2”. This will mean that “Jason” will login to NetXposure as an Administrator-level user.

In cases of overlap — a user’s roles match more than one “authenticated role” — then the highest level user is applied to the login.

Good luck!

Technical Notes on Properties

The LDAP module works with a directory server accessed via the Java Naming and Directory Interface (JNDI) APIs. The following constraints are imposed on the data structure in the underlying directory server:

Each user that can be authenticated is represented by an individual element in the top level DirContext that is accessed via the directory.connection_url property.
Each user element has a distinguished name that can be formed by substituting the presented username into a pattern configured by the directory.user_pattern property.
Alternatively, if the directory.user_pattern property is not specified, a unique element can be located by searching the directory context. In this case:
The directory.user_search pattern specifies the search filter after substitution of the username.
The directory.user_base property can be set to the element that is the base of the subtree containing users. If not specified, the search base is the top-level context.
The directory.user_subtree property can be set to true if you wish to search the entire subtree of the directory context. The default value of false requests a search of only the current level.
The user may be authenticated by binding to the directory with the username and password presented. This method is used when the directory.connection_password property is not specified.
The user may be authenticated by retrieving the value of an attribute from the directory and comparing it explicitly with the value presented by the user. This method is used when the directory.connection_password property is specified, in which case the element for this user must contain an attribute named by the directory.connection_password property.
The user is considered to be authenticated if the presented credentials (after being passed through RealmBase.digest()) are equal to the retrieved value for the user password attribute.
Each group of users that has been assigned a particular role may be represented by an individual element in the top level DirContext that is accessed via the directory.connection_url property. This element has the following characteristics:
The set of all possible groups of interest can be selected by a search pattern configured by the directory.role_search property.
The directory.role_search pattern optionally includes pattern replacements “{0}” for the distinguished name, and/or “{1}” for the username, of the authenticated user for which roles will be retrieved.
The directory.role_base property can be set to the element that is the base of the search for matching roles. If not specified, the entire context will be searched.
The directory.role_subtree property can be set to true if you wish to search the entire subtree of the directory context. The default value of false requests a search of only the current level.
The element includes an attribute (whose name is configured by the roleName property) containing the name of the role represented by this element.
In addition, roles may be represented by the values of an attribute in the user‘s element whose name is configured by the directory.user_role_name property.

Active Directory Example

Configuring communication with Microsoft Active Directory can be a bit complicated. This section attempts to alleviate this work as much as possible. In fact, some of the Directory-specific properties listed above only apply to Active Directory.

The directory.connection_name and directory.connection_password provide the ability to authenticate against Active Directory as a single user. All queries are performed with this user account. Additionally, Active Directory can‘t handle the default referrals case in JNDI , so an application authenticating against Active Directory must set the “directory.referrals” property value to “follow”. The following properties and values are slightly modified from an actual working configuration with Active Directory. This example is provided to assist with your understanding of what each property value might look like:

directory.authentication

simple

directory.connection_url

ldap://www.yourcompany.com:389

directory.connection_name

CN=catest,CN=Users,DC=www,DC=yourcompany,DC=com

directory.connection_password

changeme

directory.name_1_field

givenName

directory.name_3_field

sn

directory.email_field

mail

directory.referrals

follow