Documentation Nexus IQ Server 1.21

Our documentation site has moved. For the most current version, please see http://help.sonatype.com

5.4. LDAP Integration

Light Weight Directory Protocol, also known more commonly as LDAP, provides both a protocol and a directory for storing user information. In some ways LDAP has become a ubiquitous part of most organizations' efforts to create a single sign on environment, as well as streamline user management for various applications. While we will cover some LDAP basics, the information provided here is limited and should not be considered a full reference.

A single LDAP realm is supported, which simply means it is limited to a single LDAP server. This connection is configured via the IQ Server. There are essentially two parts to integrating with LDAP:

  • Configure the LDAP Server Connection
  • Map LDAP User and Group Elements

Our setup instructions provide an example using the Active Directory format, and represent only the most basic approach. What we provide in this chapter assumes a simple authentication method for LDAP. However, in a standard installation, you would likely not want to use Simple Authentication as it sends the password in clear text over the network. Additionally, we have indicated a search base which corresponds to our organization’s top-level domain components "dc=sonatype,dc=com". The structure can vary greatly based on your own LDAP server configuration.

[Note]

Once the LDAP server is configured and user attributes have been mapped, both LDAP users and users created in the CLM Realm will be able to login.

5.4.1. Configuring the LDAP Server Connection

The first step is to configure the LDAP Server connection. These instructions are pretty straightforward as long as you have the necessary information. For this example, let’s assume we have been provided the following:

Server Name

Test LDAP Server

Protocol

LDAP

Hostname

wind-son04

Port

389

Search Base

dc=sonatype,dc=com

Authentication Type

Simple

Username

testuser

Password

tester

[Note]

The information provide will not allow you to access an LDAP server, and is provided just for demonstration purposes. In addition, this is only a representation of a simple connection. For an explanation of all available parameters, please see the next section.

Now, access the IQ Server:

  1. Log into the IQ Server (by default this is available at http://localhost:8070) with a user account assigned to the System Administrator role.
  2. Click the system preferences icon figs/web/clm-server-system-preferences-icon.png located in the top right of the IQ Server (resembles a cog/gear).
  3. Choose LDAP from the available option. The LDAP Administration area will be displayed.
  4. Enter the various parameters, and then use the Test Connection button to ensure a connection can be made to the configured LDAP Server.
  5. Click the Save button when finished.

Using the information from the table above, our configuration should look something like this:

figs/web/ldap-configuration-server-configuration.png

Figure 5.5. Sample LDAP Server Configuration


[Note]

If at any point you wish to reset the form, click the reset button and any value that have been entered will be removed.

5.4.2. LDAP Configuration Parameters

As mentioned, the example above is a basic setup. Given this, there are a number of parameters not utilized. This section provides descriptions for all available parameters that can be configured in the Connection section of the LDAP Configuration area on the IQ Server. When applicable, required fields have been noted.

General
Protocol
Valid values in this drop-down are LDAP and LDAPS, which correspond to the Lightweight Directory Access Protocol and the Lightweight Directory Access Protocol over SSL.
Hostname
The hostname or IP address of the LDAP.
Port
The port on which the LDAP server is listening. Port 389 is the default port for the LDAP protocol and port 636 is the default port for the LDAPS.
Search Base
The search base is the Distinguished Name (DN) to be appended to the LDAP query. The search base usually corresponds to the domain name of an organization. For example, the search base on the Sonatype LDAP server could be "dc=sonatype,dc=com".
Authentication
Method

Four distinct authentication methods can be used when connecting to the LDAP Server:

  • Simple Authentication - Simple authentication is not recommended for production deployments not using the secure LDAPS protocol as it sends a clear-text password over the network.
  • Anonymous Authentication - Used when you only need read-only access to non-protected entries and attributes when binding to the LDAP server.
  • Digest-MD5 - This is an improvement on the CRAM-MD5 authentication method. For more information, see http://www.ietf.org/rfc/rfc2831.txt.
  • CRAM-MD5 - The Challenge-Response Authentication Method (CRAM) based on the HMAC-MD5 MAC algorithm. In this authentication method, the server sends a challenge string to the client, the client responds with a username followed by a Hex digest which the server compares to an expected value. For more information, see RFC 2195. For a full discussion of LDAP authentication approaches, see http://www.ietf.org/rfc/rfc2829.txt and http://www.ietf.org/rfc/rfc2251.txt.
SASL Realm
The Simple Authentication and Security Layer (SASL) Realm to connect with. The SASL Realm is only available if the authentication method is Digest-MD5.
Username
Username of an LDAP User to connect (or bind) with. This is a Distinguished Name of a user who has read access to all users and groups.
Password
Password for an Administrative LDAP User.
Timeouts

Two configuration options are available.

Connection
The number of seconds to try and connect to the configured server before returning an error.
Retry Delay
The number of seconds to wait before attempting to connect to the configured server again (after an error).

5.4.3. Mapping LDAP Users

Once the LDAP Server has been configured, you can map information attributes of an LDAP user. Similar to configuring the LDAP Server, this will require that you have information related to the location of various user attributes. Here is a sample set of data, that you would likely see:

Base DN

cn=users

Object Class

user

Username Attribute

sAMAccountName

Real Name Attribute

cn

Email Attribute

mail

Once you have gathered this information, access the IQ Server LDAP Configuration:

  1. Log into the IQ Server (by default this is available at http://localhost:8070) with a user account assigned to the System Administrator role.
  2. Click the system preferences icon figs/web/clm-server-system-preferences-icon.png located in the top right of the IQ Server (resembles a cog/gear).
  3. Choose LDAP from the available option. The LDAP Administration area will be displayed.
  4. Click on the Second Tab, just below the Server Name, User and Group Settings.
  5. Enter the various settings, using the Test Mapping button to ensure the correct information has been mapped.
  6. Click the Save button when finished.
[Note]

If at any point you wish to reset the form, click the reset button; Any values that have been entered will be removed.

Using the information from the table above, our configuration would look like this:

figs/web/ldap-configuration-user-mapping.png

Figure 5.6. User Mapping


5.4.4. LDAP User Parameters

As mentioned, the example above is a basic setup. Specifically, we do not turn on the User Subtree option or utilize the User Filter. Descriptions for those fields, as well as all available parameters for mapping LDAP User Attributes, have been provided below. When applicable, required fields have been noted.

Base DN (required)
Corresponds to the Base DN (Distinguished Name) containing user entries. This DN is going to be relative to the Search Base. For example, if your users are all contained in "cn=users,dc=sonatype,dc=com" and you specified a Search Base of "dc=sonatype,dc=com" you would use a value of "cn=users"
User Subtree
Enable this parameter if there is a tree below the Base DN which can contain user entries. For example, if all users are in "cn=users" this field should not be toggled. However, if users can appear in organizational units below "cn=users", such as "ou=development,cn=users,dc=sonatype,dc=com" this field should be toggled
Object Class (required)
The object class defines what attributes are expected for a given object. What is entered here must be the object class for the Username Attribute, Real Name Attribute, Email Attribute, and the Password Attribute.
User Filter
The user filter allows you to isolate a specific set of users under the Base DN.
Username Attribute (required)
This is the attribute of the Object class which supplies the username.
Real Name Attribute (required)
This is the attribute of the Object class which supplies the real name of the user.
E-Mail Attribute (required)
This is the attribute of the Object class which supplies the email address of the user.
Password Attribute
This is the attribute of the Object class which supplies the User Password. By default it is not toggled, which means authentication will occur as a bind to the LDAP server. Otherwise this is the attribute of the Object class which supplies the password of the user.

5.4.5. Mapping LDAP Groups

In most LDAP implementations users are collected into various groups. This allows for better organization of a larger numbers of users, as well as provides a mechanism to isolate particular groups for specific permissions and integration into other systems. If LDAP groups are not mapped, all LDAP users will be pulled in from the Base DN. This isn’t so much an issue for a small number of users. However, for larger ones it may be a concern and might grant unintended access.

As we’ve done with the other configuration areas, let’s look at a sample set of data. In example below we’ll be configuring a static LDAP group.

Group Type

Static

Base DN

ou=groups

Object Class

group

Group ID Attribute

sAMAccountName

Group Member Attribute

member

Group Member Format

Once you have gathered this information, access the LDAP Configuration area on the IQ Server:

  1. Log into the IQ Server (by default this is available at http://localhost:8070) with a user account assigned to the System Administrator role.
  2. Click the system preferences icon figs/web/clm-server-system-preferences-icon.png located in the top right of the IQ Server header (resembles a cog/gear).
  3. Choose LDAP from the available option. The LDAP Administration area will be displayed.
  4. Click on the Second Tab, just below the Server Name, User and Group Settings.
  5. Just below the User Element mapping, you will see Group Element Mapping. The Group Type field will be set to none. Change this to static or dynamic based on the parameter descriptions below.
  6. Enter the various settings.
  7. Click the Save button when finished.
[Note]

If at any point you wish to reset the form, click the reset button; Any values that have been entered will be removed.

Using the information from the table above our configuration would look like this:

figs/web/ldap-configuration-group-mapping.png

Figure 5.7. Group Mapping


5.4.6. LDAP Group Parameters

Groups are generally one of two types in LDAP systems - static or dynamic. A static group contains a list of users. A dynamic group is where the user contains a list of groups the user belongs to. In LDAP a static group would be captured in an entry with an Object class groupOfUniqueNames which contains one or more uniqueMember attributes. In a dynamic group configuration, each user entry in LDAP contains an attribute which lists group membership. This means the available parameters will be different based on whether you’ve chosen static or dynamic.

[Tip]

Static groups are preferred over dynamic ones, and will generally perform better if you have a large number of LDAP users.

Static Groups

Static groups are configured with the following parameters:

Base DN (required)
This field is similar to the Base DN field described for User Element Mapping. If your groups were defined under "ou=groups,dc=sonatype,dc=com", this field would have a value of "ou=groups"
Group Subtree
This field is similar to the User Subtree field described for User Element Mapping. If all groups are defined under the entry defined in Base DN, this field should not be selected. If a group can be defined in a tree of organizational units under the Base DN, this field should be selected.
Object Class (required)
This is a standard object class defined as a collection of references to unique entries in an LDAP directory, and can be used to associate user entries with a group.
Group ID Attribute (required)
This field specifies the attribute of the Object class that defines the Group ID.
Group Member Attribute (required)
This field specifies the attribute of the Object class that defines a member of a group.
Group Member Format (required)
This field captures the format of the Group Member Attribute, and is used to extract a username from this attribute. For example, if the Group Member Attribute has the format uid=brian,ou=users,dc=sonatype,dc=com, then the Group Member Format would be uid=${username},ou=users,dc=sonatype,dc=com. If the Group Member Attribute had the format "brian", then the Group Member Format would be ${username}.

Dynamic Groups

If your installation does not use Static Groups, you can configure LDAP integration to refer to an attribute on the User entry to derive group membership. To do this, select Dynamic Groups in the Group Type field in Group Element Mapping.

Dynamic groups are configured via the Member of Attribute parameter. This attribute of the user entry will provide list of LDAP groups that the user is a member of. In this configuration, a user entry would have an attribute such as memberOf which would contain the name of a group.

figs/web/ldap-configuration-dynamic-groups.png

Figure 5.8. Dynamic Group Options


[Tip]

Depending on the size of your enterprise, LDAP search could be slow. If you find this is the case, uncheck the option to "Include in Search". This will exclude groups from search results when assigning users to roles. Searching for users will remain unaffected.

5.4.7. Verifying LDAP Configuration

It’s easy to make a typo, or even have entered the wrong information when mapping LDAP users or groups. There are a number of tools provided within the LDAP configuration area to assist in making sure everything has been mapped correctly. Each of these is discussed below.

Test Connection

Testing the LDAP connection is the first step. If you can’t connect to your LDAP server, user and group mapping will fail as well.

figs/web/ldap-configuration-test-server.png

Figure 5.9. Testing LDAP Server


Check User and Group Mapping

Making sure that usernames, real names, email addresses, and groups have been mapped correctly can be verified with the Check User Mapping.

figs/web/ldap-configuration-check-user-mapping.png

Figure 5.10. Checking User Mapping


Check Login

As a final test to ensure users can log in, the Check Login allows you to enter a username and password, and ensure ensure that this can be authenticated with the LDAP server.

figs/web/ldap-configuration-check-user-login.png

Figure 5.11. Checking User Login