Implement generic single sign-on with PPM

This section provides information on how to configure PPM to use the generic single sign-on module to integrate with third-party authentication servers.

Single sign-on works as follows:

1. A user logs on to a portal that has been configured to use a third-party authentication application.

2. The user accesses the PPM standard interface through an external Web Server integration that is part of the logged-in domain.

3. The PPM Server receives the user information through the REMOTE_USER environment variable, HTTP header, or HTTP request attribute specified in the sso.conf file.

4. If the user is a valid PPM user, he is granted access to the PPM standard interface and PPM Dashboard.

Requirements for Implementing Generic Single Sign-On

To implement generic single sign-on with PPM, your PPM system be integrated with an external Web server (Sun Java System Web Server, an Apache-based server, or IIS).

Setting Up Generic Single Sign-On with PPM

To implement generic single sign-on:

1. Regarding the third-party authentication application you plan to use:

   1. To configure the third-party application, follow the instructions provided with the application.

   2. Verify that the PPM user is also a valid single sign-on user and can be authenticated.

2. External Web server:

   1. Integrate PPM with the external Web server.

   For information on how to integrate an external Web server, see Integrate an external web server with a PPM Server.

   2. Configure the external Web server to integrate with the third-party authentication application. For information on how to do this, see the documentation provided with the with third-party authentication application.

3. PPM Server configuration:

   1. Verify that the sso.conf file in the <PPM_Home>/integration/sso directory has the following setting.

      Parameter	Description
      LOCATION	Tells PPM server where to find the username information of the authenticated user connecting to PPM. It supports the following values: LOCATION = remote_user: username is stored in the REMOTE_USER CGI environment variable. In this case, the value of the parameter USERNAME is ignored. LOCATION = header: username is stored in the HTTP header defined by the parameter USERNAME. It is the default value if the parameter is not defined. However, we recommend you avoid this setting for security reasons. LOCATION = attribute: username is stored in the HTTP request attribute defined by the parameter USERNAME. This setting is reserved for advanced environments where custom code is running in PPM server to perform authentication.
      USERNAME	Tells the header your single sign-on system uses to store the username of the authenticated user. For example, CA SiteMinder uses HTTP_SM_USER.

   2. Add the following line to the server.conf file.

      com.kintana.core.server.SINGLE_SIGN_ON_PLUGIN=com.kintana.sc.security.auth.GenericSingleSignOn

   3. Run the kUpdateHtml.sh script, which is located in the <PPM_Home>/bin directory.

4. Stop, and then restart the PPM Server

For information on troubleshooting issues you may encounter with single sign-on, see Troubleshooting Your Single Sign-On Implementation.

Troubleshooting Your Single Sign-On Implementation

Determine the header information that the single sign-on server is sending.

1. Check the timestamp as follows:

   1. Open the server.conf file in a text editor, and set the value of the ENABLE_WEB_ACCESS_LOGGING parameter to true.

      Note: For information on how to edit the server.conf file, see PPM Configuration parameters.

   2. Run the kUpdateHtml.sh script.

   3. Restart the PPM Server.

      Note: For details on how to stop and start the PPM Server, see Start and stop the PPM Server on a single-server system.

   4. Log on to PPM.

   5. Check the timestamp on the PPM Server.

   6. Navigate to the <PPM_Home>/server/<PPM Server>/log directory.

   7. Open the <Date>.access.log file and check the timestamp.

2. Open the logging.conf file (located in the <PPM_Home>/conf directory) in a text editor, and add the following text.

   com.kintana.core.logging.PRODUCT_FUNCTION_LOGGING_LEVEL =
   com.kintana.web.filter.debug, DEBUG
   com.kintana.core.logging.PRODUCT_FUNCTION_LOGGING_LEVEL =
   com.kintana.sc.authentication, DEBUG
   com.kintana.core.logging.SYSTEM_THRESHOLD = DEBUG

3. Restart the PPM Server by running the following:

   sh ./kStart.sh -debug

   The information is written to the <PPM_Home>/bin/serverLog_<Debug_Timestamp>.txt file.

4. Enable logging on the single sign-on agent side, and then check the information passed back and forth. Check for any error messages reported.

   Tip: After you check for problems and error messages, you can remove the debugging code you added to the logging.conf file in step 2.

The session timeout property does not work in your generic single sign-on implementation. If you set the server configuration parameter ENABLE_GENERIC_ SSO_TIMEOUT to true, you enable the session timeout property. PPM redirects you to the sign-in page when it times out and forwards you to the Dashboard page after you click Sign-in.

If you set the parameter to false, the session timeout property does not work in your generic SSO implementation.