{inall}
{oss} has a Lightweight Directory Access Protocol (LDAP) Authentication realm which provides the repository manager with the capability to authenticate users against an LDAP server. In addition to handling authentication, the repository manager can be configured to map roles to LDAP user groups. If a user is a member of a LDAP group that matches the ID of a role, the repository manager grants that user the matching role. In addition to this highly configurable user and group mapping capability, the repository manager can augment LDAP group membership with specific user-role mapping.
In addition to the basic LDAP support from {oss}, {pro} offers LDAP support features for enterprise LDAP deployments. These include the ability to cache authentication information, support for multiple LDAP servers and backup mirrors, the ability to test user logins, support for common user/group mapping templates, and the ability to support more than one schema across multiple servers.
In order to use LDAP authentication in the repository manager, you will need to add the 'Nexus LDAP Authentication Realm' to the 'Selected Realms' in the 'Security' section of the 'Server' configuration panel. To load the 'Server' configuration panel, click on the 'Server' link under 'Administration' in the main menu. Once you have the 'Server' configuration panel loaded, select 'Enterprise LDAP Authentication Realm' (or 'OSS LDAP Authentication Realm') in the 'Available Realms' list under the 'Security Settings' section and click the 'Add' button (or 'Left Arrow') as shown in Adding the LDAP Authentication Realm to Available Realms and ensure that the LDAP realm is located below the XML realms in the list.
This is necessary, so that the repository manager can be used by 'anonymous', 'admin' and other users configured in the XML realms even with LDAP authentication offline or unavailable. Any user account not found in the XML realms, will be passed through to LDAP authentication.
Next, click on the 'Save' button at the bottom of the Server configuration panel to have the change applied.
To configure LDAP integration, click on the 'Enterprise LDAP' menu item in {pro} or the 'LDAP Configuration' menu item in {oss} in the 'Security' menu in the left-hand main menu.
Clicking on the Enterprise LDAP/LDAP Configuration menu item will load the LDAP Configuration panel. The following sections outline the configuration options available in the LDAP Configuration Panel.
A Simple LDAP Connection and Authentication Setup shows a simplified LDAP configuration for the repository manager configured to connect to an LDAP server running on localhost port 10389 using the search base of ou=system. On a more standard installation, you would likely not want to use Simple Authentication as it sends the password in clear text over the network, and you would also use a search base that corresponds to your organization’s top-level domain components such as dc=sonatype,dc=com.
The following parameters can be configured in the 'Connection' and 'Authentiation' sections of the 'LDAP Configuration' panel.
- 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.
- 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
-
The repository manager provides four distinct authentication methods to 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 the repository manager only needs read-only access to non protected entries and attributes when binding to the LDAP.
- 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) is 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 that 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 used to connect. It is only available if the authentication method is Digest-MD5 or CRAM-MD5.
- Username
-
Username of an LDAP user with which to connect (or bind). This is a 'Distinguished Name' of a user who has read access to all users and groups.
- Password
-
Password for an administrative LDAP user.
The 'LDAP Configuration' panel in {oss} contains sections to manage 'User Element Mapping' and 'Group Element Mapping' in the 'User' and 'Group Settings' tab. These configuration sections are located in a separate panel called 'User and Group Settings' in {pro}. This panel provided a 'User & Group Templates' drop-down displayed in User and Group Templates Selection Drop Down that will adjust the rest of the user interface based on your template selection.
The User Element Mapping displayed in User Element Mapping has been prepopulated by the Active Directory selection in the template drop-down and needs to be configured as required by your LDAP server. The available fields are:
- Base DN
-
Corresponds to the 'Base DN' containing user entries. This DN is going to be relative to the 'Search Base', specified in A Simple LDAP Connection and Authentication Setup. For example, if your users are all contained in ou=users,dc=sonatype,dc=com and you specified a Search Base of dc=sonatype,dc=com, you would use a value of ou=users.
- User Subtree
-
Values are 'True' if there is a tree below the Base DN that can contain user entries and 'False' if all users are contain within the specified Base 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 defaults to inetOrgPerson which is a standard object class defined in RFC 2798. This Object Class (inetOrgPerson) contains standard fields such as 'mail', 'uid'. Other possible values are 'posixAccount' or a custom class.
- User ID Attribute
-
This is the attribute of the Object class that supplies the User ID. The repository manager uses this attribute as the User ID.
- 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.
- E-Mail Attribute
-
This is the attribute of the Object class that supplies the email address of the user. The repository manager uses this attribute when it needs to send an email to a user.
- Password Attribute
-
This control is only available in {oss} and replaced by the 'Use Password Attribute' section from Password Attribute in {pro}. It can be used to configure the Object class, which supplies the password ("userPassword").
Once the checkbox for 'Use Password Attribute' has been selected, the interface from Password Attribute allows you to configure the optional attribute. 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.
The 'Group Type' drop-down displayed in Dynamic Group Element Mapping and Static Group Element Mapping determines which fields are available in the user interface. 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 a list of groups to which user belongs. In LDAP a static group would be captured in an entry with an Object class 'groupOfUniqueNames' that contains one or more 'uniqueMember' attributes. In a dynamic group configuration, each user entry in LDAP contains an attribute that lists group membership.
Dynamic groups are configured via the '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, a user entry would have an attribute that would contain the name of a group, such as 'memberOf'.
Static groups are configured with the following parameters:
- Base DN
-
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 be false. If a group can be defined in a tree of organizational units under the Base DN, then the field should be 'true'.
- Object Class
-
This value defaults to groupOfUniqueNames which is a standard object class defined in RFC 4519. This default ('groupOfUniqueNames') is simply a collection of references to unique entries in an LDAP directory and can be used to associate user entries with a group. Other possible values are 'posixGroup' or a custom class.
- Group ID Attribute
-
Specifies the attribute of the Object class that specifies the 'Group ID'. If the value of this field corresponds to the ID of a role, members of this group will have the corresponding privileges. Defaults to cn.
- Group Member Attribute
-
Specifies the attribute of the Object class which specifies a member of a group. A 'groupOfUniqueNames' has multiple 'uniqueMember' attributes for each member of a group. Defaults to '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. 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.
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.
Once you have configured the 'User & Group Settings' you can check the correctness of your user mapping by pressing the 'Check User Mapping' button visible in Static Group Element Mapping.
{pro} offers a button 'Check Login' to check an individual users login and can be used as documented in Testing a User Login.
Press the 'Save' button after successful configuration.
When mapping users and groups to an Active Directory installation, try the common configuration values listed in User Element Mapping Configuration for Active Directory and Group Element Mapping Configuration for Active Directory.
| Configuration Element | Configuration Value |
|---|---|
Protocol |
ldap |
Hostname |
Hostname of Active Directory Server |
Port |
389 (or port of AD server) |
Search Base |
DC=yourcompany,DC=com (customize for your organization) |
Authentication |
Simple Authentication |
Username |
CN=Administrator,CN=Users,DC=yourcompany,DC=com |
| Configuration Element | Configuration Value |
|---|---|
Base DN |
cn=users |
User Subtree |
false |
Object Class |
user |
User ID Attribute |
sAMAccountName |
Real Name Attribute |
cn |
E-Mail Attribute |
|
Password Attribute |
(Not Used) |
| Configuration Element | Configuration Value |
|---|---|
Group Type |
Dynamic Groups |
Member Of Attribute |
memberOf |
|
Warning
|
You should connect to the Active Directory through port 3268 if you have a multi domain, distributed Active Directory forest. Connecting directly to port 389 might lead to errors. Port 3268 exposes Global Catalog Server that exposes the distributed data. The SSL equivalent connection port is 3269. |
When mapping users and groups to LDAP entries of type posixAccount, try the common configuration values listed in User Element Mapping Configuration for posixAccount and Group Element Mapping Configuration for posixGroup.
| Configuration Element | Configuration Value |
|---|---|
Base DN |
(Not Standard) |
User Subtree |
false |
Object Class |
posixAccount |
User ID Attribute |
sAMAccountName |
Real Name Attribute |
uid |
E-Mail Attribute |
|
Password Attribute |
(Not Used) |
| Configuration Element | Configuration Value |
|---|---|
Group Type |
Static Groups |
Base DN |
(Not Standard) |
Group Subtree |
false |
Object Class |
posixGroup |
Group ID Attribute |
cn |
Group Member Attribute |
memberUid |
Group Member Format |
${username} |
Once 'User and Group Mapping' has been configured, you can start verifying how LDAP users and groups are mapped to roles. If a user is a member of an LDAP group that has a 'Group ID' corresponding to the ID of a role, that user is granted the appropriate permissions in the repository manager. For example, if the LDAP user entry in uid=brian,ou=users,dc=sonatype,dc=com is a member of a 'groupOfUniqueNames' attribute value of admin, when this user logs into the repository manager, he/she will be granted the administrator role if the 'Group Element Mapping' is configured properly. To verify the 'User Element Mapping' and 'Group Element Mapping', click on 'Check User Mapping' in the 'LDAP Configuration' panel directly below the 'Group Element Mapping' section, Checking the User and Group Mapping in LDAP Configuration shows the results of this check.
In Checking the User and Group Mapping in LDAP Configuration, LDAP Integration locates a user with a User ID of "brian" who is a member of the "admin" group. When brian logs in, he will have all of the rights that the admin role has.
If you are unable to map all of the roles to LDAP groups, you can always augment the role information by adding a specific user-role mapping for an external LDAP user in the repository manager. In other words, if you need to make sure that a specific user in LDAP gets a specific role and you don’t want to model this as a group membership, you can add a role mapping for an external user in the repository manager.
The repository manager keeps track of this association independent of your LDAP server. It continues to delegate authentication to the LDAP server for this user. The repository manager will continue to map the user to roles based on the group element mapping you have configured, but it will also add any roles specified in the User panel. You are augmenting the role information that the repository manager gathers from the group element mapping.
Once the user and group mapping has been configured, click on the 'Users' link under 'Security' in the main menu. The 'Users' tab is going to contain all of the configured users for this repository manager instance as shown in Viewing All Configured Users. A configured user is a user in a repository manager realm or an 'External User' that has an explicit mapping to a role. In Viewing All Configured Users, you can see the three default users in the default realm plus the brian user from LDAP. The brian user appears because this user has been mapped to an internal role.
The list of users in Viewing All Configured Users is a combination of all of the users in the default realm and all of the 'External Users' with role mappings. To explore these two sets of users, click on the 'All Configured Users' drop-down and choose 'Default Realm Users'. Once you select this, click in the search field and press Enter. Searching with a blank string in the 'Users' panel will return all of the users of the selected type. In All Default Realm Users you see a dialog containing all three default users from the default realm.
If you wanted to see a list of all LDAP users, select 'LDAP' from the 'All Configured Users' drop-down shown in Viewing All Configured Users and click on the search button (magnifying glass) with an empty search field. Clicking search with an empty search field will return all of the LDAP users as shown in All LDAP Users.
|
Note
|
Note that the user tobrien does not show up in the 'All Configured Users' list. This is by design. The repository manager is only going to show you information about users with external role mappings. If an organization has an LDAP directory with thousands of developers, the repository manager doesn’t need to retain any configuration information for users that don’t have custom role mappings. |
To add a mapping for an external LDAP user, you would click on the 'All Configured Users' drop-down and select 'LDAP'. Once you’ve selected LDAP, type in the user ID you are searching for and click the search button (magnifying glass icon to right of the search field). In Search LDAP Users, a search for "brian" yields one user from the LDAP server.
To add a role mapping for the external user brian shown in Search LDAP Users, click on the user in the results table and drag a role from 'Available Roles' to 'Selected Roles' as shown in Mapping the Deployment Role to an External User. In this case, the user "brian" is mapped to the Administrative group by virtue of his membership in an "admin" group in the LDAP server. In this use case, an administrator would like to grant Brian the Deployment Role without having to create a LDAP group for this role and modifying his group memberships in LDAP
The end result of this operation is to augment the Group-Role mapping that is provided by the LDAP integration. You can use LDAP groups to manage coarse-grained permissions to grant people administrative privileges and developer roles, and if you need to perform more targeted privilege assignments in the repository manager you can Map LDAP users to roles with the techniques shown in this section.
{oss} and {pro} make it very straightforward to map an external role to an internal role. This is something you would do, if you want to grant every member of an externally managed group (such as an LDAP group) a certain privilege in the repository manager. For example, assume that you have a group in LDAP named svn and you want to make sure that everyone in the svn group has administrative privileges. To do this, you would click on the 'Add..' drop-down in the 'Roles' panel as shown in Selecting External Role Mapping in the Role Management Panel. This drop-down can be found in the roles management panel which is opened by clicking on 'Roles' in the 'Security' menu.
Selecting 'External Role Mapping' under 'Add…' will show you a dialog containing a drop-down of 'External Realms'. Selecting an external realm such as LDAP will then bring up a list of roles managed by that external realm. The dialog shown in Selecting an Externally Managed Role to Map to an Internal Role shows the external realm LDAP selected and the role "svn" being selected to map to a role.
Once the external role has been selected, the repository manager creates a corresponding role. You can then assign other roles to this new externally mapped role. Mapping an External Role to an Internal Role shows that the SVN role from LDAP is being assigned the Administrator Role. This means that any user that is authenticated against the external LDAP Realm who is a member of the svn LDAP group will be assigned a role that maps to the Administrator Role.
{inrmonly}
When an LDAP server fails, the applications authenticating against it can also become unavailable. Because a central LDAP server is such a critical resource, many large software enterprises will install a series of primary and secondary LDAP servers to make sure that the organization can continue to operate in the case of an unforeseen failure. {pro}'s Enterprise LDAP plugin now provides you with the ability to define multiple LDAP servers for authentication. To configure multiple LDAP servers, click on Enterprise LDAP under Security in the main application menu. You should see the Enterprise LDAP panel shown in the following figure.
You can use the 'Backup Mirror' setting for an LDAP repository. This backup mirror is another LDAP server that will be consulted if the original LDAP server cannot be reached. {pro} assumes that the backup mirror is a carbon copy of the original LDAP server, and it will use the same user and group mapping configuration as the original LDAP server. Instead of using the backup mirror settings, you could also define multiple LDAP backup mirrors in the list of configured LDAP servers shown in the previous figure. When you configure more than one LDAP server, {pro} will consult the servers in the order they are listed in this panel. If the repository manager can’t authenticate against the first LDAP server, {pro} will move on to the next LDAP server until it either reaches the end of the list or finds an LDAP server to authenticate against.
The feature just described is one way to increase the reliability of your repository manager. In the previous case, both servers would have the same user and group information. The secondary would be a mirror of the primary. But, what if you wanted to connect to two LDAP servers that contained different data?
If you want to connect to two LDAP servers that contain different data, {pro} also provides support for multiple servers and LDAP schemas as described in Support for Multiple Servers and LDAP Schemas.
The same ability to list more than one LDAP server also allows you to support multiple LDAP servers that may or may not contain the same user authentication information. Assume that you had an LDAP server for the larger organization containing all of the user information across all of the departments. Now assume that your own department maintains a separate LDAP server that you use to supplement this larger LDAP installation. Maybe your department needs to create new users that are not a part of the larger organization, or maybe you have to support the integration of two separate LDAP servers that use different schema on each server.
A third possibility is that you need to support authentication against different schema within the same LDAP server. This is a common scenario for companies that have merged and whose infrastructures have not yet been merged. To support multiple servers with different user/group mappings or to support a single server with multiple user/group mappings, you can configure these servers in the Enterprise LDAP panel shown above. The repository manager will iterate through each LDAP server until it can successfully authenticate a user against an LDAP server.
If you are constantly authenticating against a large LDAP server, you may start to notice a significant performance degradation. With {pro} you can cache authentication information from LDAP. To configure caching, create a new server in the Enterprise LDAP panel, and scroll to the bottom of the Connect tab. You should see the following input field which contains the number of seconds to cache the results of LDAP queries.
You will also see options to alter the connection timeout and retry interval for an LDAP server. If you are configuring a number of different LDAP servers with different user and group mappings, you will want to make sure that you’ve configured low timeouts for LDAP servers at the beginning of your Enterprise LDAP server list. If you do this properly, it will take the repository manager next to no time to iterate through the list of configured LDAP servers.
We improved the overall caching in this release. The cache duration is configurable and applies to authentication and authorization, which translates into pure speed! Once you’ve configured LDAP caching in {pro}, authentication and other operations that involve permissions and credentials once retrieved from an external server will run in no time.
If you are configuring your {pro} instance to connect to an LDAP server there is a very good chance that your server follows one of several, well-established standards. {pro}'s LDAP server configuration includes these widely used user and group mapping templates that great simplify the setup and configuration of a new LDAP server. To configure user and group mapping using a template, select a LDAP server from the Enterprise LDAP panel, and choose the User and Group Settings. You will see a User & Group Templates section as shown in the following figure.
{pro} provides you with the ability to test a user login directly. To test a user login, go to the User and Group Settings tab for a server listed in the Enterprise LDAP panel. Scroll to the bottom of the form, and you should see a button named "Check Login".
If you click on Check Login, you will then be presented with the login credentials dialog shown below. You can use this dialog to login as an LDAP user and test the user and group mapping configuration for a particular server. This feature allows you to test user and group mapping configuration directly and to quickly diagnose and address difficult authentication and access control issues via the administrative interface.
