Documentation Nexus IQ Server 1.34

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

7.4. LDAP Integration

[Note]

This section assumes you are familiar with LDAP (Lightweight Directory Access Protocol), and have an LDAP server currently in use.

You can configure IQ Server to work with an LDAP server for the purposes of authenticating users and managing users and groups. The integration process is discussed below in three parts:

  • Configuring LDAP Server Connection
  • Mapping LDAP Users
  • Mapping LDAP Groups

7.4.1. Configuring LDAP Server Connection

The first step in integrating IQ Server and LDAP is to configure the LDAP server connection as follows:

  1. Log into the IQ Server using a user account assigned to the System Administrator role.
  2. In the System Preferences menu figs/web/clm-server-system-preferences-icon.png on the IQ Server toolbar, click LDAP.
  3. In the LDAP Servers view, click Add a Server.
  4. In the Enter Server Name box, type a name to identify the LDAP server. Click Save. The LDAP editor is displayed.
  5. Enter the following parameters using values specific to your LDAP server. More information about these parameters is available in LDAP Configuration Parameters below.

    1. Protocol
    2. Hostname
    3. Port
    4. Search Base
    5. Authentication Type
    6. Username
    7. Password
    8. Connection
    9. Retry Delay
  6. Click Test Connection to verify a connection can be made to the LDAP server.
  7. Click Save when finished.
figs/web/ldap-configuration-server-configuration.png

Figure 7.5. Sample LDAP Server Configuration


7.4.2. LDAP Configuration Parameters

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 server.
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 protocol.
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".
Method

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

  • NONE (Anonymous Authentication) - Used when you only need read-only access to non-protected entries and attributes when binding to the LDAP server.
  • SIMPLE - Simple authentication is not recommended for production deployments not using the secure LDAPS protocol as it sends a clear-text password over the network.
  • DIGESTMD5 - This is an improvement on the CRAM-MD5 authentication method. For more information, see http://www.ietf.org/rfc/rfc2831.txt.
  • CRAMMD5 - 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. Not available if authentication method is NONE.
Username
Username of the Administrative 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.
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).

7.4.3. Mapping LDAP Users

The second step in integrating IQ Server and LDAP is to map LDAP users as follows:

  1. In the LDAP editor, click the User & Group Settings tab.
  2. Enter the following parameters under User Element Mapping using values specific to your LDAP server. More information about these parameters is available in LDAP User Parameters below.

    1. Base DN
    2. User Subtree
    3. Object Class
    4. User Filter
    5. Username Attribute
    6. Real Name Attribute
    7. E-mail Attribute
    8. Password Attribute
  3. Click Check User Mapping to verify the correct information is mapped.
  4. Click Save when finished.
figs/web/ldap-configuration-user-mapping.png

Figure 7.6. User Mapping Example


7.4.4. LDAP User Parameters

When you map LDAP users, some parameters are required and some optional. The required parameters are noted below.

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 required, 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.

7.4.5. Mapping LDAP Groups

In most LDAP implementations, users are mapped into groups with different permissions. If LDAP groups are not mapped, then all LDAP users are pulled in from the Base DN, which may give unintended access to some users.

The third step in integrating IQ Server and LDAP is to map the LDAP groups as follows:

  1. In the LDAP editor, click the User & Group Settings tab.
  2. In the Group Element Mapping section, select a Group Type.

    1. For a Dynamic group, enter a Member of Attribute and use the slider to enable or disable Group Search.
    2. For a Static group, enter the following parameters using values specific to your LDAP server: Base DN, Object Class, Group ID Attribute, Group Member Attribute, and Group Member Format.
[Tip]

Disabling group search for Dynamic Groups may improve performance but will not return group results when searching IQ Server users.

  1. Click Save when finished.

For more information about these group parameters, see LDAP Group Parameters below.

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

Figure 7.7. Group Mapping Example


7.4.6. LDAP Group Parameters

Groups are generally one of two types in LDAP systems: static or dynamic. For static groups, users are explicitly assigned to the group. For dynamic groups, users are assigned to the group based on a set of common attributes.

[Tip]

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

When you map LDAP groups, some parameters are required and some are optional. The required parameters are noted below.

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.

Member of Attribute (required)
Dynamic groups are configured via the Member of Attribute parameter. This attribute of the user entry will provide a 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.
Group Search
Depending on the size of your enterprise, LDAP search could be slow. If you find this is the case, click the Enabled slider below Group Search to disable group search.
[Tip]

Disabling group search will exclude groups from search results when assigning users to roles. Searching for users will remain unaffected.

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

Figure 7.8. Dynamic Group Options


7.4.7. Verifying LDAP Configuration

The LDAP editor provides several ways to verify your LDAP configuration in IQ Server.

Test Connection

You can click Test Connection to verify your LDAP configuration. 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 7.9. Testing LDAP Server


Check User and Group Mapping

You can click Check User Mapping to verify that usernames, real names, email addresses, and groups have been mapped correctly.

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

Figure 7.10. Checking User Mapping


Check Login

To ensure users can log in, click Check Login to open the "Test LDAP Login Credentials" dialog box. Enter a username and password, and click Test Login.

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

Figure 7.11. Checking User Login


7.4.8. Reordering LDAP Servers

[Note]

Reordering LDAP servers may impact user authentication and/or authorization.

When authenticating a user, IQ Server connects to LDAP servers in the order displayed in the LDAP Servers view. To manage the order, perform the following steps:

  1. In the LDAP Servers view, click Reorder List. The Reorder LDAP Servers modal opens (see Figure 7.12, “Reordering LDAP Servers Modal”).
  2. Click on a server and use the up and down arrow buttons to reorder the list. Double arrow buttons move the selection to the top or bottom of the list.
  3. Click Save when you are finished.

The server list in the LDAP Servers view updates to reflect the new order.

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

Figure 7.12. Reordering LDAP Servers Modal