LDAP Integration

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.

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  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:

    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:
    1. NONE (Anonymous Authentication): Used when you only need read-only access to non-protected entries and attributes when binding to the LDAP server.
    2. 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.
    3. DIGESTMD5: This is an improvement on the CRAM-MD5 authentication method. For more information, see http://www.ietf.org/rfc/rfc2831.txt.
    4. 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).
  6. Click Test Connection to verify a connection can be made to the LDAP server.
  7. Click Save when finished.

Mapping LDAP Users

After configuring an LDAP server connection, the next 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:

    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. Note: This field very rarely needs to be set, and setting it in cases where it is not required will likely lead to authentication failures.
  3. Click Save when finished.

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.

After configuring an LDAP server and mapping LDAP users, the last 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.
  3. Click Save when finished.

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

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.

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}.


Static Group LDAP Mapping

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.

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

Dynamic Group LDAP Mapping

Verifying LDAP Configuration

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

Test Connection

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.

Check User and Group Mapping

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

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.

Reordering LDAP Servers

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

Need more information?

We have a technical guide on the Sonatype Guides site that goes over several options for authorization and authentication in IQ Server. Check out IQ Server Authentication and Authorization to learn more.



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}.