# LDAP Nexus Repository uses the Lightweight Directory Access Protocol (LDAP) for authentication with external systems. Nexus Repository roles may also be mapped to LDAP user groups to grant authorization to members of the LDAP group. **Access Control Best Practices** Delegating authentication to LDAP systems and authorization to LDAP group greatly simplifies user management for Nexus Repository administrators and is a best practice. Permissions to view and edit LDAP configurations are granted by the _nx-ldap-all_ privilege. Configuring LDAP is done with a few steps: 1. Enable LDAP Authentication Realm 2. Create LDAP server configuration with connections and user/group mapping details 3. Create external role mappings to adapt LDAP roles to repository manager-specific usage Nexus Repository maintains a local cache of authentication information to reducing server to server requests and supports multiple LDAP servers and user/group mappings. ## Enabling the LDAP Authentication Realm Activate your _LDAP Realm_ by following these steps: 1. Navigate to the _Realms_ in the _Security_ section of the _Settings_ menu. 2. Select the _LDAP Realm_ and add it to the list of _Active_ realms. 3. Move the _LDAP Realm_ beneath the _Local Authenticating Realm_ in the list. 4. Select _Save_. **Local Authenticating Realm Best Practice** Set the _Local Authenticating Realm_ as the first (primary) realm on the list to compare with local accounts before making a request to external systems. This improve performance when authenticating specifically for administrator access. ## LDAP Connection and Authentication The _LDAP_ view is in the _Security_ section of the _Settings_ menu. The order determines the priority of LDAP servers when authenticating a user. The name and URL columns are set when configuring your LDAP servers. - #### Create connection Add a new LDAP server configuration. Multiple configurations are accessible in the list. - #### Change order Change the order of requests to the LDAP servers. - #### Clear cache Purge the locally cached authentications. Successful authentications are locally cached to reduce load on LDAP servers. ### Create LDAP Connection Profile Contact your LDAP administrator for connection information. You will need the following parameters to create an LDAP connection: - #### Name Enter a unique name for the new configuration. - #### LDAP server address Enter the Protocol, Hostname, and Port of the LDAP server. - #### Protocol Valid values in this drop-down are `ldap` and `ldaps` that 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`. - #### Search base DN This field further qualifies the connection to the LDAP server. It usually corresponds to the domain name of an organization. For example: `dc=example,dc=com`. Escape spaces in the search base DN using `%20` ``` dc=example%20corp,dc=com ``` #### LDAP Authentication Methods Configure the _Authentication Method_ to use when connecting to the LDAP Server. Adjust the _Connection rules_ to change the default timeouts and retry attempts. - #### Simple Authentication Simple authentication consists of a _Username_ and _Password_. 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 The anonymous authentication uses the server address and search base without further authentication. - #### Digest-MD5 This is an improvement on the CRAM-MD5 authentication method. - #### CRAM-MD5 The Challenge-Response Authentication Method (CRAM) is based on the HMAC-MD5 MAC algorithm. - #### SASL Realm - The Simple Authentication and Security Layer (SASL) realm is used to connect to the LDAP server. It is only available if the authentication method is Digest-MD5 or CRAM-MD5. - #### Username or DN - _Username_ or _DN_ (Distinguished Name) of an LDAP user with read access to all necessary users and groups. It is used to connect to the LDAP server. - #### Password - _Password_ for the Username or DN configured above. ## User and Group Mapping The LDAP connection panel contains a section to manage user and group mappings. This configuration is the next step after you configure and verify the LDAP Connection. It is a separate panel called _Choose Users and Groups_. This panel provides a _Configuration template_ drop-down, shown in _Figure: “Configuration Template for Users and Groups”_. Based on your template selection the rest of the field inputs will adjust to the appropriate user and group template requirements. These templates are suggestions for typical configurations used on servers such as _Active Directory_, _Generic Ldap Server_, _Posix with Dynamic Groups,_ and _Posix with Static Groups_. The values are suggestions only and have to be adjusted to your specific needs based on your LDAP server configuration. The following parameters allow you to configure your user and group elements with the repository manager: **User relative DN** Corresponds to the collection of distinguished names used as the base for user entries. This DN is relative to the _Search Base DN_. For example, if your users are all contained in `ou=users,dc=sonatype,dc=com` and you specified a Search Base DN of `dc=sonatype,dc=com`, you use a value of `ou=users`. **User subtree** Check the box if _True_. Uncheck if _False_. Values are true if there is a tree below the User relative DN field that can contain user entries and false if all users are contained within the specified User relative DN. For example, if all users are in `ou=users,dc=sonatype,dc=com` this field should be _False_. If users can appear in organizational units within organizational units such as `ou=development,ou=users,dc=sonatype,dc=com`, this field should be _True_. **Object class** This value is a standard object class defined in RFC-2798. It specifies the object class for users. Common values are `inetOrgPerson`, `person`, `user`, or `posixAccount`. **User filter** This allows you to configure a filter to limit the search for user records. It can be used as a performance improvement. **User ID attribute** This is the attribute of the object class specified above, that supplies the identifier for the user from the LDAP server. The repository manager uses this attribute as the _User ID_ value. **Real name attribute** This is the attribute of the Object class that supplies the real name of the user. The repository manager uses this attribute when it needs to display the real name of a user similar to usage of the internal _First name_ and _Last name_ attributes. **Email attribute** This is the attribute of the Object class that supplies the email address of the user. The repository manager uses this attribute for the _Email attribute_ of the user. It is used for email notifications of the user. **Password attribute** It can be used to configure the Object class, which supplies the password ("userPassword"). If this field is blank the user will be authenticated against a bind with the LDAP server. The password attribute is optional. When not configured authentication will occur as a bind to the LDAP server. Otherwise this is the attribute of the Object class that supplies the password of the user. The repository manager uses this attribute when it is authenticating a user against an LDAP server. An automatically checked box will allow you to Map LDAP groups as roles. With the configuration, any LDAP group configured for a specific user is used to query the roles in the repository manager. Identical names trigger the user to be granted the privileges of the roles. Groups in LDAP systems are configured to be dynamic or static. A dynamic group is a list of groups to which users belong. A static group contains a list of users. Select _Dynamic Groups_ or _Static Groups_ from the _Group type_ drop-down to proceed with the appropriate configuration. | | | --- | | | Static groups, for example as displayed in _Figure: “Static Group Element Mapping”_, are configured with the following parameters: **Group relative DN** This field is similar to the _User Relative DN_ field described for User Element Mapping, but applies to groups instead of users. For example, 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, but configures groups instead of users. If all groups are defined under the entry defined in Group relative DN, set the field to false. If a group can be defined in a tree of organizational units under the Group relative DN, set the field to true. **Group object class** This value in this field is a standard object class defined in RFC-2307. The class is simply a collection of references to unique entries in an LDAP directory and can be used to associate user entries with a group. Examples are `groupOfUniqueNames`, `posixGroup` or custom values. **Group ID attribute** Specifies the attribute of the object class that specifies the group identifier. If the value of this field corresponds to the ID of a role, members of this group will have the corresponding privileges. **Group member attribute** Specifies the attribute of the object class which specifies a member of a group. An example value is `uniqueMember`. **Group member format** This field captures the format of the _Group Member Attribute_, and is used by the repository manager to extract a username from this attribute. An example value is `${dn}`. If your installation does not use static groups, you can configure the LDAP connection to refer to an attribute on the user entry to derive group membership. To do this, select _Dynamic Groups_ in the _Group type_ drop-down. Dynamic groups are configured via the _Group member of attribute_ parameter. The repository manager inspects this attribute of the user entry to get a list of groups of which the user is a member. In this configuration, seen in _Figure: “Dynamic Group Element Mapping”_, a user entry would have an attribute that would contain the name of a group, such as _memberOf_. Once you have configured the user and group settings on the _Choose Users and Groups_ form, you can check the correctness of your user mapping by pressing the _Verify user mapping_ button. A successful mapping will result in the retrieval of a list of user records, which will be shown in the _User Mapping Test Result_ dialog. Note that the user mapping result dialog is limited to 20 records. You can go to "security → users" in the settings UI and search in the LDAP realm to search for specific users and verify their information. The repository manager provides you with the ability to test a user log in directly. To test a user log in, go to the _Choose Users_ and _Groups_ page after all appropriate field inputs of the form are filled. Scroll to the bottom and click the _Verify login_ button. The _Verify login_ button can be used to check if authentication and user/group mappings work as expected for a specific user account besides the global account used for the LDAP configuration. After the successful configuration of your LDAP connection and user and group mappings, you can proceed to configure external role mappings and assign them to users. This allows you to define the repository manager-specific security for an LDAP group. More details are available in [Roles](https://help.sonatype.com/en/roles.html "Roles") and [Users](https://help.sonatype.com/en/users.html "Users"). ## Improve LDAP Performance for External Role Mapping The UI for mapping external LDAP roles shows matching roles after 3 characters have been entered, by default. When there are a large number of LDAP roles or too many roles starting with the same 3 characters, the roles dropdown may experience poor performance degrading the user experience. The following property is used to set the limit for the number of characters that need to be typed before any existing LDAP-mapped roles are shown in the drop-down. Add the property and desired value to your `nexus.properties` configuration and restart the server: ``` nexus.ldap.mapped.role.query.character.limit=3 ``` ## Configuring SSL Certificates for LDAPS Connections When you configure Nexus Repository to use a Lightweight Directory Access Protocol over SSL (LDAPS), Nexus Repository must trust the LDAP server’s SSL certificate. You can add and manage these certificates directly from the user interface. To add an LDAP server’s SSL certificate to your instance’s list of trusted SSL certificates for use with the Nexus truststore, complete the following steps: 1. Sign in as an administrator. 2. Go to _Administration_ → _Security_→ _SSL Certificates_. 3. Click _Add Certificate_. 4. Choose one of the following options: - **Load from server:** Enter the LDAP server’s hostname and port. Example: `ldaps.internal.salesforce.com:636` - **Paste PEM:** Paste the PEM-encoded certificate. The text must start with `-----BEGIN CERTIFICATE-----` and end with `-----END CERTIFICATE-----`. For more details, refer to [Configuring SSL](https://help.sonatype.com/en/configuring-ssl.html "Configuring SSL"). 5. Click _Load Certificate_. Review the details and click _Add Certificate_. 6. Go to _Administration_ → _Security_→ _LDAP_and edit or create an LDAP connection. 7. In your LDAP configuration, select _Use certificates stored in the Nexus Repository truststore to connect to external systems_. 8. Test the connection to verify that the certificate is trusted and the LDAPS connection succeeds.