Introduction

Integrate LDAP as a way to handle permissions. An LDAP server address will be included in the configuration of the CmapServer. Whenever permissions need to be checked on the CmapServer, if an LDAP server is defined, it will use the user’s information in the LDAP server to determine whether the operation can be performed by the user.

Design Documentation

This document describes the integration of the CmapTools resource permissions architecture with an external LDAP user database.

LDAP and CmapTools

The LDAP user database stores users and groups which may act as principals in the CmapTools permissions architecture. When defining permissions on an LDAP-enabled CmapServer, the application allows users to select principals from the set stored in the LDAP directory. When checking permissions, a user’s credentials are verified with the LDAP directory to determine the corresponding principal, which is then matched with the principals in the permissions list. This is illustrated in Figure 1.

Figure 1. CmapTools and LDAP

The CmapServer supports three authentication modes:

• Standard permissions - Users can define their own User IDs and passwords

• LDAP permissions - Users must choose from the list of users and groups stored in the LDAP directory (only available for new CmapServer installations)

• Both - Users may choose from the list of users and groups in LDAP, or may create their own User IDs and passwords

The latter mode is useful when upgrading an existing CmapServer. The standard permissions will be maintained, while also allowing users to add LDAP permissions to new and existing folders.

Defining Permissions

When a user defines permissions for a folder using the CmapTools client, they may select from up to four types of users, as show in Figure 2.

Figure 2. Selecting the type of user

Existing user: Select users and groups from the set of principals in the LDAP directory. The user is able to select principals in two ways – either by typing in a User ID, or by searching.

If the user types in a User ID, the CmapTools client will verify it with the LDAP directory (via the CmapServer), and obtain the principal corresponding to that User ID. This is shown in Figure 3.

Figure 3. Adding a user by typing an LDAP User ID

By clicking the “Browse” button in the Add User dialog, the user may search for a principal, by entering all or part of a first name, last name, or User ID. He may then choose a user or group from the list of principals returned by the search query.

The LDAP principal is then stored in the permissions list for the folder. This is shown in Figure 4.

Figure 4. Searching for an LDAP user

User types (continued):

New User: Defines a new “standard” user, by supplying a User ID and password. This user is only stored in the folder’s permissions list, and is not added to the LDAP directory. This option is disabled on a CmapServer which is running in LDAP-only mode.

All Users in Directory: Includes all users in the LDAP directory.

Everyone: Includes everyone in the world, even those users not in the LDAP directory (e.g. anonymous). On a server which is in LDAP-only mode, the “Everyone” user is not allowed to add folders or be an administrator, since those operations require an LDAP account*. However, they can be granted other permissions.

* Although it is possible to allow “Everyone” to have these permissions, disabling these permissions protects users from inadvertently creating folders which anyone could modify and/or delete.

Checking Credentials

When a user tries to access a resource, his credentials are checked by the CmapServer. In the case of an LDAP-enabled CmapServer, the user’s credentials are sent to the LDAP server to verify his identity. In the current implementation, a user’s credentials consist of a User ID and password. However, in a future release, a user’s certificate may be used as the credentials to verify his identity, either by mapping the user’s name in the certificate to a principal in the LDAP directory, or by asking the LDAP server for the principal which has the given certificate. This option provides a stronger level of authentication for access to resources.

The LDAP server either rejects the credentials, or returns the corresponding principal. If the credentials are rejected, then the user’s request to access the resource is denied. Otherwise, the CmapServer compares the principal returned by the LDAP server to the principals in the permissions list for the folder. This step may also include group membership queries to the LDAP server as needed.

CmapServer Installation and Configuration

The installation program for the CmapServer leads the administrator through setting the parameters to enable LDAP authentication for permissions.

In the first step, the user selects the authentication mode: Standard permissions, LDAP permissions, or both.

Figure 5. Selecting the authentication mode

• Note: When upgrading an existing server, the installer will only list authentication modes which are less restrictive than the current mode, to avoid locking out users from using the current permissions. For example, you can upgrade from “Standard” mode to “Both”, but not “Standard” to “LDAP”. This restriction may be removed in a later version.

• Note: When installing a new CmapServer in LDAP-only mode, the administrator’s User ID and password (entered during a previous step in the installation, as shown in Figure 6) must match the User ID and password of an LDAP user, or the server’s root folder will not have a valid administrator and the server will fail to start.

Figure 6. For LDAP-only mode, User ID/Password (in previous step) must match an LDAP user

In the next step, the address and port number of the LDAP server are entered.

Figure 7. Setting the address of the LDAP server

The protocol for communicating with the LDAP server is then selected. Three modes are supported – Normal (unsecure), TLS (Transport Layer Security), and SSL (Secure Socket Layer).

If a secure mode is selected, the PKI authentication settings will be used, if they have been specified. Otherwise, the CmapServer will establish a secure LDAP connection without PKI authentication. Please see the PKI documentation for more details.

Figure 8. Selecting the LDAP communication protocol

The following step requests the Distinguished Name (DN) of the LDAP containers where individuals and groups are stored.

These containers will be searched with ‘subtree’ scope to determine the list of users and groups shown to the CmapTools client. Both static and dynamic (or role-based) groups are supported.

Figure 9. Setting the DN of the containers for users and groups

The next step asks for the name of the LDAP attribute which holds the user’s ID. The value of this attribute will correspond to the notion of “User ID” in the CmapTools client. For example, “uid” is a commonly used attribute for this purpose.

Figure 10. Setting the name of the attribute which holds the user's ID

The final step asks for the name of the LDAP attribute which holds the group’s ID. The value of this attribute will again correspond to the “User ID” in the CmapTools client. In most cases, the attribute “cn” is appropriate for this case.

Figure 11. Setting the name of the attribute which holds the group's ID

After installation, these settings can be modified by editing the file “serverconfig.txt” which is located under “bin” in the installation directory of the application. The relevant LDAP parameters for the CmapServer are explained in the following table:

Parameter Name	Description
root.folder.account	For LDAP-only configurations, the value for this parameter must be a user ID that is present in the LDAP user directory.
root.folder.password	For LDAP-only configurations, the value for this parameter must be the password stored in the LDAP server of the LDAP user who was specified as the root folder administrator.
user.authentication	Authentication mode: standard, LDAP, or both Possible values: authentication.standard,authentication.ldap (for both, include both values separated by a comma)**
ldap.root.folder.account	For LDAP-only and “both” configurations, the value for this parameter must be a user ID that is present in the LDAP user directory.
ldap.root.folder.password	For LDAP-only and “both” configurations, the value for this parameter must be the password stored in the LDAP server of an LDAP user who was specified to be a root folder administrator.
ldap.user.directory.ip	IP address or hostname of the LDAP server
ldap.user.directory.port	Port number of the LDAP server
ldap.user.directory.connection.mode	Protocol that the CmapServer uses to communicate with the LDAP server.  If a secure mode is selected, the certificate from the PKI settings (specified earlier in the serverconfig.txt file) will be used if present and unrevoked.
ldap.user.directory.usersBaseDN	Distinguished Name (DN) of the container where individual users are stored Example: ou=People,dc=mydomain,dc=com
ldap.user.directory.groupsBaseDN	Distinguished Name (DN) of the container where groups are stored Example: ou=Groups,dc=mydomain,dc=com
ldap.user.directory.userAttr	Name of the attribute which holds the user's ID Example: uid
ldap.user.directory.groupAttr	Name of the attribute which holds the group's ID Example: cn

Figure 12. CmapServer LDAP Parameters

** Changing a server’s authentication mode from standard to LDAP, or vice-versa, is not recommended, as it may result in the server’s root folder not having a valid administrator for the selected authentication mode. In these cases, it is recommended that the mode be changed to “both”. This restriction may be removed in a later version.