Understanding Single Signon and Pagelets

The Signon Process with the API

The PRTL_SS_CI component interface contains two user-defined methods:

• Authenticate( ).

  Your external authentication program distributes an authentication token that can be retrieved from a cookie in the browser. The Authenticate function determines whether an authentication token is valid.

• GetUserID( ).

  If the token is valid, you use the GetUserID function to retrieve the user ID associated with the authentication token.

Before reading about the development requirements of your API, examine the steps that occur internally when you use the API in conjunction with the delivered PRTL_SS_CI:

1. The user enters the user ID and password into the PeopleSoft portal sign-in page.

2. If the sign-in to the portal application server is successful, the server generates a single signon token. The web server receives the single sign-on token from the application server and issues a cookie to the browser.

3. The user navigates in the portal and encounters a link to the external system. The user clicks the link.

4. The browser passes the PS_TOKEN cookie to the external web server.

5. The external web server checks for the PS_TOKEN cookie before displaying a sign-in page.

6. After the system determines that the user is accessing the application through the PeopleSoft portal, you retrieve the authentication token and send it to the PRTL_SS_CI component interface to verify authentication. For instance, it calls PRTL_SS_CI.Authenticate(Auth. token string).

7. After the system authenticates the token, it can then make calls to the PRTL_SS_CI.Get_UserID() function to return the appropriate user ID.

In general, cookies are not transferable across domains. The only domain that can access the cookie is the domain that created it. Therefore, the web server for the non-PeopleSoft system must be on the same domain as the PeopleSoft system so that the cookies are passed appropriately.

External Application Support for Single Sign-on

Developers of external applications need to alter the sign-on process to conform to the following requirements:

1. Check for the PS_TOKEN cookie. If the cookie doesn't exist, continue with the normal sign-in process. Otherwise, bypass the sign-in page.

2. Retrieve the authentication token from the PS_TOKEN cookie.

3. Connect to the PeopleSoft portal through the PRTL_SS_CI API.

4. Pass the authentication token to the Authenticate() function of the API.

5. If Authenticate() returns True, retrieve the user ID associated with the authentication token using the Get_UserID() function.

Authentication API PeopleCode Example

The following PeopleCode example shows the process of validating your authentication token and retrieving the user ID. This example is designed to provide a general idea of the process involved and to help you incorporate the PRTL_SS_CI API into your sign-in process.

Local ApiObject &THISSESSION;
Local ApiObject &THISCI;
Local string &AUTHTKN;
/* Assigns the Authentication Token to a variable */
		&AUTHTKN = %AuthenticationToken;
/* Open a session and make a connection */
		&THISSESSION = GetSession();
			If &THISSESSION.connect(1, "EXISTING", "", "", 0) <> True Then
				WinMessage(MsgGet(30000, 1, "Session Connect Failed."));
				Exit (1);
			End-If;
/* Retrieves the component interface PRTL_SS_CI */
		&THISCI = &THISSESSION.GetCompIntfc(CompIntfc.PRTL_SS_CI);
/* Checks to see if the component interface is NULL */
			If &THISCI = Null Then
				WinMessage("Component Interface PRTL_SS_CI not found. 
				Please ensure Component Interface Security access is granted 
				to this user.");
				Exit (1);
			End-If;
/* Key fields would usually be set before the Get() function is 
called in order to map the component interface to a particular 
set of data. This component interface is not mapped to data.
* Therefore, the component interface is retrieved and then the 
user defined methods are retrieved */
		&THISCI.get();
		PRTL_AUTH = &THISCI.Authenticate(&AUTHTKN);
		PRTL_USER_ID = &THISCI.Get_UserID();

Authentication API Java Example

Here is an example of a similar operation written in Java. This is a file named SingleSignon.java.

package examples.migration.sso;

import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;
import java.util.*;
import psft.pt8.joa.*;
import PeopleSoft.Generated.CompIntfc.*;

public class SingleSignon extends HttpServlet {
  public static ISession oSession;
  String psfttoken;
  public static void ErrorHandler() {
  		//***** Display PeopleSoft Error Messages *****
if (oSession.getErrorPending() || oSession.getWarningPending()) {
  			IPSMessageCollection oPSMessageCollection;
  			IPSMessage oPSMessage;

  			oPSMessageCollection = oSession.getPSMessages();
for (int i = 0; i < oPSMessageCollection.getCount(); i++) {
  				oPSMessage = oPSMessageCollection.item(i);
  				if (oPSMessage != null)
  					System.out.println("(" + oPSMessage.getMessageSetNumber() + ","
 + oPSMessage.getMessageSetNumber() + ") : " + oPSMessage.getText());
  			}
  			//***** Done processing messages in the collection; 
OK to delete *****
  			oPSMessageCollection.deleteAll();
  		}
	}

  public void doGet(HttpServletRequest request,
                    HttpServletResponse response)
      throws ServletException, IOException {
		  try {
    response.setContentType("text/html");
    PrintWriter out = response.getWriter();

    Cookie[] cookies = request.getCookies();
	    if (cookies == null) {
	      out.println("<TR><TH COLSPAN=2>No cookies");
	    } else {
	      Cookie cookie;
	      for(int i=0; i<cookies.length; i++) {
	        cookie = cookies[i];

	        String pstoken = cookie.getName();
            psfttoken = cookie.getValue();
            if (pstoken.equals ("PS_TOKEN"))

               out.println("<TR>\n" +
	                  "  <TD>" + pstoken + "\n" +
	                  "  <TD>" + psfttoken);
	      }

	    }

     String strServerName, strServerPort, strAppServerPath;
		String strUserID, strPassword;
		strServerName = "jfinnon09";
                strServerPort = "9500";
                strUserID = "VP1";
                strPassword = "password";

		//Build Application Server Path
		strAppServerPath = strServerName + ":" + strServerPort;

      //***** Create PeopleSoft Session Object *****
      //       ISession oSession;

		oSession = API.createSession();

		//***** Connect to the App Server *****
		if (!oSession.connect(1, strAppServerPath, strUserID, strPassword,
 null)) {
			out.println("\nUnable for Jason to Connect to 
Application Server.");
			ErrorHandler();
			return;
		}

     //***** Get Component Interface *****
		IPrtlSsCi oPrtlSsCi;
		String ciName;
	 	ciName = "PRTL_SS_CI";
		oPrtlSsCi = (IPrtlSsCi) oSession.getCompIntfc(ciName);
		if (oPrtlSsCi == null) {
			out.println("\nUnable to Get Component Interface " + ciName);
			ErrorHandler();
			return;
		}

		//***** Set the Component Interface Mode *****
				oPrtlSsCi.setInteractiveMode(false);
				oPrtlSsCi.setGetHistoryItems(true);
				oPrtlSsCi.setEditHistoryItems(false);

		//***** Set Component Interface Get/Create Keys *****

				//***** Execute Get *****
				if (!oPrtlSsCi.get()) {
					out.println("\nNo rows exist for the specified keys.
	\nFailed to get the Component Interface.");
					ErrorHandler();
					return;
				}

				//***** BEGIN:  Set/Get Component Interface Properties *****

				//***** Set Level 0 Properties *****
				//out.println("oPrtlSsCi.PrtlToken: " +
 oPrtlSsCi.getPrtlToken());
				//out.println("Checking token: " + psfttoken);

				//oPrtlSsCi.setPrtlToken(<*>);
		                //String psfttoken;
		                //psfttoken = oPrtlSsCi.getPrtlToken();
		                //System.out.println("oPrtlSsCi.PrtlToken: "
 + psfttoken);

				//***** END:  Set Component Interface Properties *****

				//***** Execute Standard and Custom Methods *****
				//***** Execute Authenticate *****
				boolean auth;

		         auth = oPrtlSsCi.authenticate(psfttoken);
		         //out.println("Auth: " + auth);
				//Execute Get_UserID
		                String psftuser;
				psftuser = oPrtlSsCi.getUserid();
                //out.println("Psftuserid: " + psftuser);

                 String title = "Welcome  " + psftuser;

                //****** Get HTML ***********
                 out.println(ServletUtilities.headWithTitle(title));
                 out.println("</BODY></HTML>");

                //***** Disconnect from the App Server *****
		        oSession.disconnect();
		        return;
  }


  catch (Exception e) {
  		e.printStackTrace();
  		System.out.println("An error occurred: ");
  		ErrorHandler();
  	}
	}


  /** Let the same servlet handle both GET and POST. */

  public void doPost(HttpServletRequest request,
                     HttpServletResponse response)
      throws ServletException, IOException {
    doGet(request, response);
  }

}