Configuring Fusion for LDAP

You can create security realms that use external LDAP servers for authentication. Optionally, Fusion can search in the LDAP for groups to which a user belongs, and then map those groups to Fusion roles. Fusion performs authorization using permissions stored in Fusion users and Fusion roles.

Note: Fusion doesn’t use permissions from the LDAP for authorization of UI access or API requests. It only obtains group names (optionally), which are mapped to role names. If an Active Directory Security Query Trimming Stage is used, then directory-service permissions are used for trimming. If a connector supports security trimming, then connector permissions are used for trimming.

To configure Fusion to use an external LDAP as an authentication provider, you’ll need to get information about the LDAP server(s) running on your system, either from your system or your sysadmin.

1. Add an LDAP Security Realm

  1. Log into the Fusion UI as the user admin, or as a different user with corresponding permissions.

  2. Click Devops > Access Control > Security Realms > Add Security Realm.

    add security realm

  3. Specify info for the new realm:

    • name – Name of the security realm. It must be unique. It should be descriptive but short.

    • type – Choose ldap from the pulldown menu.

    • enabled checkbox – Whether Fusion allows user logins for this security realm. The default is yes (checked).

    • auto-create users checkbox – Whether a user account is created automatically upon initial authentication. The default is yes (checked). If the checkbox is unchecked, then a Fusion user with admin permissions must create Fusion users.

    new realm info

2. Specify Static Roles (Optional)

Specify one or more Fusion roles for the security realm. These roles are always considered. They don’t depend on searching for LDAP groups and mapping group names to Fusion role names.

In a security realm, you can specify these static roles, add to the list of roles dynamically through an LDAP search, or both. If you do neither, Fusion uses only the role(s) and permissions defined for the user.

specify static roles

3. Specify LDAP Connection Details

Specify the hostname and port of the LDAP server. Check the checkbox if the server is running over SSL.

specify LDAP connection details

4. Specify the Authentication Method

Specify the authentication method:

  • Bind - LDAP authentication 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.

Bind

Use the Bind authentication method when the Fusion login username matches a part of the LDAP distinguished name (DN). Specify the remainder of the LDAP DN in the "DN Template" configuration entry, which uses a single pair of curly brackets ("\{}") as a placeholder for the value of the Fusion username.

specify bind authentication

Use the Search authentication method 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 then used together with the user password for authentication via a Bind request.

  1. Construct a search 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 constructing a search request. There are two parts to the request. The first part is the base DN of the LDAP directory tree that contains user account objects. The second part of the request is a Search Filter object that restricts the results to a matching subset of the information.

    specify search authentication

  2. Provide the administrator bind DN:

    specify bind information for the superuser

Kerberos

Use the Kerberos authentication method when Kerberos is the authentication provider.

specify Kerberos authentication

5. Search for LDAP Groups (Optional)

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.

search for LDAP groups

6. Map LDAP Groups to Fusion Roles (Optional)

If LDAP group names returned by the search for groups match Fusion role names, you don’t need to map the group names to role names. You must map any LDAP group names that don’t match to Fusion role names (if you don’t, they won’t be used).

map LDAP groups to security realms

7. Save and Test the Security Realm Configuration

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

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.

save and test security realm

Fusion reports whether or not authentication was successful:

LDAP connection success

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.