CTP Authentication Using OpenAM
This article describes how to configure CTP to use an OpenAM server to authenticate users. The intended audience for this article is CTP administrators.
The CTP OpenAM authentication mechanism uses an external OpenAM server to authenticate users' sessions and to obtain users' roles. This mechanism is different from the LDAP mechanism in that no user information is stored locally.
The OpenAM authentication mechanism is configured in the OpenAM 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 OpenAM authentication, The usersClassName attribute of the Server element must be set to org.rsna.server.UsersOpenAMImpl, and the OpenAM child element must be appended to the Server element. The OpenAM child element is shown below:
<OpenAM
openAMURL="http://myOpenAMServer.myUniversity.edu:80" />
where:
- openAMURL specifies the full URL of the OpenAM server, including the protocol and the port.
A brief description of the authentication process may be helpful in testing.
A user establishes a Single-Sign-On (SSO) session with the OpenAM server by accessing the server's login page. In CTP installations (including ISN), the login page URL includes the URL of the target system to which the user wishes to be redirected (CTP or the Edge Server). For example, to be authenticated and then redirected to a CTP server, the login URL might be:
The OpenAM server returns a page containing a form allowing the user to enter the username and password.
When the Log In button is clicked on the page, the browser posts the form to the OpenAM server, which authenticates the user and, if the credentials are accepted, redirects the browser to the URL specified in the goto query parameter. The redirect response sent by the OpenAM server to the browser includes a Set-Cookie header setting a domain cookie for the SSO session. The browser then provides that cookie in all subsequent requests to servers in that domain.
- Note: All testing has been done with the OpenAM server and the destination CTP server in the same domain. It's not clear whether the SSO session cookie is set on the domain of the destination URL or on the domain of the OpenAM server. A test with the two servers in different domains did not result in the destination server receiving the SSO cookie.
When the destination system receives the HTTP connection from the browser, it sees the session cookie and validates it with the OpenAM server. With a valid cookie, the system can obtain the user's attributes from the OpenAM server.
For efficiency, CTP maintains an internal session table. When a connection is received, CTP gets the SSO cookie and validates it against its internal table. If the session is present (and matches certain other criteria designed to prevent poaching), the connection is considered to be authenticated, and the connection is assigned to the user associated with the session. If the SSO cookie does not correspond to a session in the internal session table, CTP validates the cookie with the OpenAM server. If the OpenAM server accepts the cookie, CTP creates an internal session for the user and assigns the user the username and roles that it obtains from the attributes for the session provided by the OpenAM server.
CTP gets the user's username from the uid attribute and the roles from the role attribute.
1 OpenAMTest
There is a simple test program that may help in testing a connection to an OpenAM server. The program is available at http://mirc.rsna.org/download/OpenAMTest.jar. Run the program on any computer that has Java 1.6 or better on it and that can communicate with the OpenAM server. (As noted above, the computer should be in the same domain as the OpenAM server.) It displays a window like this:
The default values are ones that were used at the Mallinckrodt Institute of Radiology during ISN testing, so they are useful only as examples.
- Set the OpenAM Server field to point to your OpenAM server.
- Set the Test Server field to point to an unused port on your test computer. The program will open a server on this port to receive the connections from the browser after it has been redirected by the OpenAM server.
- Click the SSO Cookie button. The program will contact the OpenAM server to get the name of the SSO cookie and display it.
- Click the Login button. The program will launch your browser and go to the OpenAM login page.
- Enter the credentials of a user and click the Log In button on the page. The program will display any connections it subsequently receives from the browser. In most cases there will be two connections. The first will be the browser's attempt to access the resource in the redirect. The second, if present, will be a request to obtain the favicon.ico resource, which the browser uses to display an icon in a favorites list. The key thing to note is whether there is an SSO session cookie in the request:
Connection received from 10.242.100.63 Headers received by the server: GET /favicon.ico HTTP/1.1 Host: nibib-3.wustl.edu:9999 User-Agent: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9.2.18) Gecko/20110628 Ubuntu/10.04 (lucid) Firefox/3.6.18 Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8 Accept-Language: en-us,en;q=0.5 Accept-Encoding: gzip,deflate Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7 Keep-Alive: 115 Connection: keep-alive Cookie: amlbcookie=01; RSNASSO=AQIC5wM2LY4SfczZ-TiwCvOSEJ1no0jGxPQ9aNSOVgFXymA.*AAJTSQACMDE.*; Content received by the server: [none]
- Click the Validate button. The program will validate the cookie against the OpenAM server and display the result. If the session is valid, the result will be true.
- Click the Attributes button. The program will obtain the attributes of the session from the OpenAM server and display them in two lists. The first shows exactly what was obtained from the OpenAM server; the second shows how the attributes were parsed. Check that there is a uid attribute and a role attribute. The latter might be multi-valued, with one value for each role assigned to the user.
- The Logout button doesn't work, but it looks nice.
2 DEBUG Logging
When configuring CTP to use an OpenAM server for authentication, if may be helpful to turn on DEBUG logging in the classes that are used by the authentication mechanism. The best way to do that is to edit the CTP/log4j.properties file. Add these two lines to the bottom of the file:
log4j.logger.org.rsna.server.UsersOpenAMImpl = DEBUG log4j.logger.org.rsna.server.Authenticator = DEBUG
Save the file and start CTP. Authentication steps will be logged in the CTP/logs/ctp.log file.
Note that the CTP/log4j.properties file is overwritten in a CTP upgrade.