Configuring Fusion for LDAP

Fusion can be configured to use an external LDAP server for authentication and authorization. To configure Fusion for LDAP, you’ll need to get information about the LDAP server(s) running on your system, either from your system or your sysadmin.

A common use case for an LDAP security realm is for search over a collection of documents with ACLs that restrict access to specific users or groups, e.g. indexing a MS Sharepoint repository managed by Active Directory. In order to make sure that search respects the access permissions on these documents, when indexing those documents, you must the access permissions as well as the document contents. At query time, the user account information sent along with the search query and Fusion restricts the search results set to only those documents that the user is allowed to access.

Fusion Configuration for an LDAP Realm

To configure an LDAP realm from the Fusion UI, you must be logged in as a user with admin-level privileges. From the "Applications" menu, menu item "Access Control", panel "Security Realms", click on the "Add Security Realm" button:

add new realm

This opens an editor panel for a new Security Realm, containing controls and inputs for all required and optional configuration information.

Required Configuration Step One: Name and Type

The first step in setting up an LDAP security realm is filling out the required information at the top of the realm config panel:

choose name

The first three required configuration items are:

  • name - must be unique, should be descriptive yet short.

  • type - choose "LDAP" from the pulldown menu.

  • "enabled" checkbox - default is true (i.e., the box is checked). The "enabled" setting controls whether or not Fusion allows user logins for this security realm.

  • "auto-create users" checkbox - default is true (i.e., the box is checked). This controls whether or not a user account is created automatically upon initial authentication. If false, the user accounts can only be created by a Fusion user with admin privileges.

Required Configuration Step Two: Server and Port

The name and port of the LDAP server are required, along with whether or not the server is running over SSL.

connection details

Required Configuration Step Three: Authentication Method and DN Templates

There are three possible authentication methods:

  • Bind - the LDAP authentication operation is carried out via a single "Bind" operation.

  • Search - LDAP authentication is carried out indirectly via a Search operation followed by a Bind operation.

  • Kerberos - Kerberos authenticates Fusion and an LDAP Search operation is carried out to find group-level authorizations.

The Bind authentication method is used when the Fusion login username matches a part of the LDAP DN. The rest of the LDAP DN is specified in the "DN Template" configuration entry, which uses a single pair of curly brackets ("\{}") as a placeholder for the value of the Fusion username.

The Search authentication method is used when the username used for Fusion login doesn’t match a part of the LDAP DN. The search request returns a valid user DN, which is used together with the user password for authentication via a Bind request.

The Search authentication method is generally required when working with Microsoft Active Directory servers. In this case, you need to know the username and password of some user who has sufficient privileges to query the LDAP server for user and group memberships; this user doesn’t have to be the superuser. In addition to a privileged user DN and password, the Search authentication method requires crafting a search request. There are two parts to the request: the first part is the base DN of the LDAP directory tree which contains user account objects. The second part of the request is a Search Filter object which restricts the results to a matching subset of the information.

Testing the Configured Connection

The last part of the form allows you to test the LDAP realm config using a valid username and password:

test connection

When the "Update and test settings" button is clicked, the username from the form is turned into a DN according to the DN template, and a Bind operation request is sent to the configured LDAP server. Fusion reports whether or not authentication was successful:

test success

Optional Configuration: Roles and Groups Mappings

A Fusion role is a bundle of permissions tailored to the access needs of different kinds of users. Access to services and data for LDAP-managed users is controlled by mappings from LDAP users and groups to Fusion roles.

Roles can be assigned globally or restricted to specific LDAP groups. The security realm configuration panel contains a list of all Fusion roles with a checkbox for each, used to assign that role to all users in that realm. LDAP group names can be mapped directly to specific Fusion roles and LDAP group search and filter queries can also be used to map kinds of LDAP users to specific Fusion roles.

Basic LDAP Concepts and Terminology

The LDAP protocol is used to share information about users, systems, networks, and services between servers on the internet. LDAP servers are used as a central store for usernames, passwords, and user and group permissions. Applications and services use the LDAP protocol to send user login and password information to the LDAP server. The server performs name lookup and password validation. LDAP servers also store Access Control Lists (ACLs) for file and directory objects which specify the users and groups and kinds of access allowed for those objects.

LDAP is an open standard protocol and there are many commercial and open-source LDAP servers available. Microsoft environments generally use Active Directory. *nix servers use AD or other LDAP systems such as OpenLDAP, although many *nix systems don’t use LDAP at all. To configure Fusion for LDAP, you’ll need to get information about the LDAP server(s) running on your system either from your sysadmin or via system utilities.

Directories and Distinguished Names

An LDAP information store is a Directory Information Tree (DIT). The tree is composed of entry nodes; each node has a single parent and zero or more child nodes. Every node must have at least one attribute which uniquely distinguishes it from its siblings which is used as the node’s Relative Distinguished Name (RDN). A node’s Distinguished Name (DN) is a globally unique identifier.

The string representation of a DN is specified in RFC 4514. It consists of the node’s RDN followed by a comma, followed by the parent node’s DN. The string representation of the RDN is the attribute-value pair name, connected by an equals ("=") sign. This recursive definition means that the DN of a node is composed by working from the node back through its parent and ancestor nodes up to the root node.

Here is a small example of a DIT:

example

The person entry in this tree has the DN: "uid=babs, ou=people, dc=example, dc=com".

Attribute names include many short strings based on English words and abbreviations, e.g.:

Name Description

cn

commonName

dc

domainComponent

mail

email address

ou

organizationalUnitName

sn

surname

uid

userId

LDAP entry attributes can refer to other LDAP entries by using the DN of the entry as value of that attribute. The following example of a directory which contains user and groups information shows how this works:

example 2

This tree contains two organizational units: "ou=people" and "ou=groups". The children of the "group" organizational unit are specific named groups, just as the child nodes of organization unit "people" are specific users. There are three user entries with RDNs "uid=bob", "uid=alice", "uid=bill" and two groups with RDNs "cn=user" and "cn=admin". The dotted lines and group labels around the person nodes indicates group membership. This relationship is declared on the groups nodes by adding an attributes named "member" whose value is a users DN. In the LDAP data interchange format (LDIF), this is written:

cn=user,ou=groups,dc=acme,dc=org
    member: uid=bob,ou=people,dc=acme,dc=org
    member: uid=alice,ou=people,dc=acme,dc=org
cn=admin,ou=groups,dc=acme,dc=org
    member: uid=bill,ou=people,dc=acme,dc=org

See the Wikipedia’s LDAP entry for details.

LDAP Protocol Operations

For authentication purposes, Fusion sends Bind operation requests to the LDAP server. The Bind operation authenticates clients (and the users or applications behind them) to the directory server, establishes authorization identity used for subsequent operations on that connection, and specifies the LDAP protocol version that the client will use.

Depending on the way that the host system uses LDAP to store login information about users and groups, it may be necessary to send Search operation requests to the LDAP server as well. The Search operation retrieves partial or complete copies of entries matching a given set of criteria.

LDAP filters specify which entries should be returned. These are specified using prefix notation. Boolean operators are "&" for logical AND, "|" for logical OR, e.g., "A AND B" is written "(&(A)(B))". To tune and test search filters for a *nix-based LDAP system, see the ldapsearch command line utility documentation. For Active Directory systems, see AD Syntax Filters.