CTP Authentication Using LDAP

This article describes how to configure CTP to use an LDAP server to authenticate users. The intended audience for this article is CTP administrators.

CTP's default authentication mechanism uses an XML file stored in the CTP directory. This file contains one element for each user, specifying the username, password, and the various roles assigned to the user. Roles determine the system functions available to the user. The LDAP authentication mechanism uses the same XML file to provide the roles, but it uses the LDAP server to authenticate the user's credentials (username and password). To be authenticated, a user must be known to both the LDAP server and the XML file. Any passwords contained in the XML file are ignored. The standard CTP User Manager can be used to create users and assign roles in the XML file, but CTP provides no way to update the LDAP server.

The authentication mechanism used by CTP is specified in the LDAP child element of the Server element in the CTP configuration file (config.xml). The Server element is described in the top-level CTP article. To configure CTP to use LDAP authentication, The usersClassName attribute of the Server element must be set to org.rsna.server.UsersLdapFileImpl, and the LDAP child element must be appended to the Server element. The LDAP child element is shown below:

        <LDAP
            initialContextFactory="com.sun.jndi.ldap.LdapCtxFactory"
            providerURL="ldaps://example.org"
            securityAuthentication="simple"
            securityPrincipal="cn=${username}, ou=people, dc=med, dc=university, dc=edu"
            ldapAdmin="adminUserName"
            referral="ignore"
            derefAliases="never" />

where:

• initialContextFactory specifies the Java class used to link to the LDAP server. The value shown above is the default. Unless there is a specific reason to specify a different class, it is best to omit this attribute.
• providerURL specifies the URL of the LDAP server. It typically begins with ldap:// or ldaps://. This URL can be obtained from the LDAP system administrator.
• securityAuthentication specifies the way the credentials are passed to the server. The default is shown above. Unless there is a reason to use a different value, it is best to omit this attribute.
• securityPrincipal specifies a string that itentifies where in the LDAP directory to find the user. The string must correspond to the organization of the information in the LDAP server. The example shown above is for one particular university's LDAP implementation. The string is sent to the LDAP server after substituting the username of the user being authenticated for the ${username} token. Other implementations may require different strings. The required string can be obtained from the LDAP system administrator.
• ldapAdmin specifies the name of a user known to LDAP who is to be given admin privileges in CTP when it starts. There must be at least one user with admin privileges known to LDAP and the XML file in order for anyone to manage the CTP application. When CTP starts, it ensures that a user exists with the specified name in the XML file and it assigns that user the admin role. It does not check that the user exists in the LDAP server nor does it modify any other user in the XML file.
• referral specifies how to respond to referrals in LDAP searches. The options are ignore and follow. The default is to ignore referrals. In some LDAP systems, it may be necessary to enable following referrals.
• derefAliases specifies how to whether to dereference aliases in LDAP searches. The options are never and always. The default is never to dereference aliases.

Note: The securityPrincipal attribute supports multiple security principals. For example, if multiple organizational units are to be searched, the attribute can be coded as:

securityPrincipal="cn=${username}, ou=(Radiology|Service), dc=med, dc=university, dc=edu"

This example produces two securityPrincipal values:

cn=${username}, ou=Radiology, dc=med, dc=university, dc=edu

cn=${username}, ou=Service, dc=med, dc=university, dc=edu

Only one set of alternatives is allowed, but there is no limit to the number of alternatives in the set.

Alternatives can encompass multiple values. For example:

securityPrincipal="cn=${username}, (ou=Radiology, dc=med|ou=Service, dc=admin), dc=university, dc=edu"

This example produces two securityPrincipal values:

cn=${username}, ou=Radiology, dc=med, dc=university, dc=edu

cn=${username}, ou=Service, dc=admin, dc=university, dc=edu

The securityPrincipal values are searched in order, left-to-right, until the authentication succeeds. For efficiency, it is best to put the most commonly used alternative first.

LDAPTest

There is a simple test program that may help in finding the right configuration for a specific LDAP server. The program is available at http://mirc.rsna.org/download/LDAPTest.jar. Run the program on any computer that has Java on it and that can communicate with the LDAP Server. It displays a window like this:

Error creating thumbnail: Unable to save thumbnail to destination

The default values are ones that were used at the University of Michigan when they set up their MIRC site to use LDAP, so they won’t necessarily be useful in your case.

1. Set the Provider URL field to point to your LDAP server.
2. In the Security Principal field, change username to a username known to the LDAP server. Change the rest of the Security Principal field to whatever is required on your server.
3. In the Security Credentials field, put in the user’s password.
4. Now try clicking the Connect button.

You may need to experiment with the Security Principal field and/or the Search Filter and Returned Attributes until you get something that looks like the server authenticated the user.

The LDAP authentication mechanism in CTP doesn’t use the passwords stored in the CTP/users.xml file. It only uses that file to obtain the roles that have been assigned to an authenticated user.