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

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 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 <b><tt>Server</tt></b> element in the CTP configuration file (<b><tt>config.xml</tt></b>). The Server element is described in the [[CTP-The_RSNA_Clinical_Trial_Processor#Server|top-level CTP article]]. To configure CTP to use OpenAM authentication, The <b><tt>usersClassName</tt></b> attribute of the Server element must be set to <b><tt>org.rsna.server.UsersOpenAMImpl</tt></b>, and the OpenAM child element must be appended to the Server element. The OpenAM child element is shown below:

+

The OpenAM authentication mechanism is configured in the <b><tt>OpenAM</tt></b> child element of the <b><tt>Server</tt></b> element in the CTP configuration file (<b><tt>config.xml</tt></b>). The Server element is described in the [[CTP-The_RSNA_Clinical_Trial_Processor#Server|top-level CTP article]]. To configure CTP to use OpenAM authentication, The <b><tt>usersClassName</tt></b> attribute of the Server element must be set to <b><tt>org.rsna.server.UsersOpenAMImpl</tt></b>, and the <b><tt>OpenAM</tt></b> child element must be appended to the Server element. The <b><tt>OpenAM</tt></b> child element is shown below:

<pre>

<pre>

Line 14:

Line 12:

*<b>openAMURL</b> specifies the full URL of the OpenAM server, including the protocol and the port.

*<b>openAMURL</b> specifies the full URL of the OpenAM server, including the protocol and the port.

−

A brief description of the authentication mechanism may be helpful in testing.

+

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:

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:

Line 22:

Line 20:

The OpenAM server returns a page containing a form allowing the user to enter the username and password.

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 <b><tt>goto</tt></b> 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 in that domain.

+

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 <b><tt>goto</tt></b> 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.

+

: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.

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.

Line 33:

Line 31:

==OpenAMTest==

==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 http://mirc.rsna.org/download/OpenAMTest.jar]. Run the program on any computer that has Java 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:

+

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 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:

Line 39:

Line 37:

−

The default values are ones that were used at the Mallinckrodt Institute of Radiology during ISN testing, so they won’t be useful in your case.

+

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 OpenAM Server field to point to your OpenAM server.

−

# Set the Test Server 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.

+

* 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 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.

+

* 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.

+

* 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:

−

# 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 should be <b><tt>true</tt></b>.

+

<pre>

−

# 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 <b><tt>uid</tt></b> attribute and a <b><tt>role</tt></b> attribute. The latter might be multi-valued, with one value for each role assigned to the user.

* 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 <b><tt>true</tt></b>.

+

* 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 <b><tt>uid</tt></b> attribute and a <b><tt>role</tt></b> 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.

==DEBUG Logging==

==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 <b><tt>CTP.log4j.properties</tt></b> file. Add these two lines to the bottom of the file:

+

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 <b><tt>CTP/log4j.properties</tt></b> file. Add these two lines to the bottom of the file:

<pre>

<pre>

Line 57:

Line 73:

</pre>

</pre>

−

Note that this file is overwritten in a CTP upgrade.

+

Save the file and start CTP. Authentication steps will be logged in the <b><tt>CTP/logs/ctp.log</tt></b> file.

+

+

Note that the <b><tt>CTP/log4j.properties</tt></b> file is overwritten in a CTP upgrade.

Latest revision as of 02:14, 6 March 2014

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:

Error creating thumbnail: Unable to save thumbnail to destination

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:

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: