Implementing Single Signon

This chapter provides an overview of single signon and discusses how to:

• Implement PeopleSoft-only single signon.

• Implement Oracle Access Manager as the PeopleSoft single signon solution.

• Implement Kerberos as the desktop single signon solution.

Note. Many single signon solutions require that you create a generic user profile with minimal permissions and set up this user as the default or public access user. You find documentation for creating the public access user profile in this PeopleBook. You find documentation for specifying the identity of the public access user in PeopleTools 8.51 PeopleBook: PeopleTools Portal Technologies.

See Also

Working With User Profiles

Creating a Public Access User

Public Users

Understanding Single Signon

This section discusses:

• Single signon options.

• The PS_TOKEN cookie.

Understanding Single Signon Options

Single signon refers to the ability of users to navigate freely within a system of multiple applications after only being authenticated once. There are three different ways to configure single signon, depending on the participating applications that you have installed. The following table displays the single signon options.

Note. You must ensure that before users attempt to use the single signon functionality, a valid user profile is defined for each user in each participating application database. You can accomplish this in a variety of ways, such as automatically generating user profiles based on users' LDAP information, replicating user profiles through Integration Broker at initial sign in, or manually defining user profiles for the authorized users before going live.

Understanding the PS_TOKEN Cookie

When the system authenticates a user, it distributes the PS_TOKEN cookie to the browser. The PS_TOKEN cookie holds user authentication information in the browser that a PeopleSoft system uses to verify user access. Having the token in the browser memory allows the user to navigate freely within the system without having to provide user credentials repeatedly.

The key security features of the PS_TOKEN cookie authentication are:

• The cookie exists in memory; it is not written to disk.

• There is no password stored in the cookie.

• You can set the expiration of the cookie to be a matter of minutes or hours; so if a cookie is intercepted it will only be usable for the duration you specify.

The following table presents the fields that appear in the PeopleSoft authentication token:

signature =  SHA1_Hash ( UserID + Lang + Date 
Time issued + Issuing System + Local Node Pswd )

Note. Single signon does not depend on Lightweight Directory Access Protocol (LDAP) directory authentication. You can implement single signon and not LDAP, you can implement LDAP and not single signon, or you can implement both LDAP and single signon.

Implementing PeopleSoft-Only Single Signon

This section provides an overview of PeopleSoft-only single signon and discusses:

• Working with the Single Signon page.

• Defining nodes for single signon.

• Setting up certificate authorization

• Single signon transaction example.

• PeopleSoft-only single signon configuration considerations.

• PeopleSoft-only single signon configuration examples.

• Securing the PeopleSoft single signon token.

• Using the single signon API.

• Configuring single signoff.

Note. In this configuration, you must create PeopleSoft node definitions for each of the participating applications. You can run any of the participating applications on Oracle WebLogic or IBM WebSphere. You can use passwords or digital certificates for single signon authentication.

Understanding PeopleSoft-Only Single Signon

PeopleSoft applications supports single signon among PeopleSoft applications. Within the context of your PeopleSoft system, single signon means that after a user has been authenticated by one PeopleSoft application server, then that user can access other PeopleSoft application servers without entering an ID or a password. Although the user is actually accessing different applications and databases—recall that each suite of PeopleSoft applications, such as HCM or CRM, resides in its own database—the user navigates seamlessly through the system.

Note. The PeopleSoft-only single signon solution applies only to PeopleSoft applications.

After the first application server/node authenticates a user, the system delivers a web browser cookie containing an authentication token (PS_TOKEN). PeopleSoft uses web browser cookies to store a unique access token for each user after they are authenticated initially. When the user connects to another PeopleSoft application server/node, the second application server uses the token in the browser cookie to re-authenticate users automatically so they don’t have to sign in repeatedly.

Single signon is critical for PeopleSoft portal implementations because the portal integrates content from various data sources and application servers and presents them in a unified interface. When the users sign in through the portal, they always take advantage of single signon. Users need to signon once and be able to navigate freely without encountering numerous signon screens. Because single signon is so integral to the portal, you always need to configure it before deploying a live portal solution.

Note. The browser cookie is an in-memory cookie and is never written to disk. The cookie is also encrypted to prevent snooping and digitally signed to prevent tampering.

Working with the Single Signon Page

Access the Single Signon page (PeopleTools, Security, Security Objects, Single Signon).

Expiration time in minutes	You need to set an expiration time for tokens this system accepts for authentication. Otherwise, once the user is authenticated, the user could be authenticated and signed on to the system with the token for as long as it stays up and running. You can set the authentication interval to be minutes, hours, or days depending on your signon strategy. The value is in minutes. For example, 480 minutes is 8 hours. This is global setting for all users of your PeopleSoft system that get issued the cookie. A short expiration period is more secure, but less convenient because users need to enter their passwords more frequently. The system accepting the token controls the expiration time, not the issuing system. For example, Node HCM_WEST, which has an expiration time of 100 minutes, issues a token to a user. The user attempts to use that token to sign in to Node FIN_EAST, which has an expiration time set to 60 minutes. If a period greater than 60 minutes has transpired, Node FIN_EAST rejects the token. When a node rejects a single signon token, the system prompts the user to enter a user ID and password on the standard signon screen. Note. This expiration time is separate from the timeouts you specify in the Permission Lists and the web server configuration files.
Message Node name	Shows the name of the Message Node. In order to share authentication tokens between nodes, the nodes need to trust each other. By adding a node to this grid, you indicate that a particular node is known to the system and trusted. When a node is trusted, the local node accepts tokens issued by it. By default, no nodes appear in the trusted nodes list. If you want to implement single signon, you need to explicitly configure your system to support it by adding trusted nodes. First, you need to add the local node to the grid as a node must be able to trust its own tokens. When you sign in to the portal, the system authenticates users with a single signon token issued by the local system. The portal won't be able to sign in unless the local node is trusted. Then you add the names of other nodes in the system that should be trusted. Note. You define nodes in Portal, Node Definitions.
Local Node	Indicates whether the node is local or not.

Note. After you update the list of trusted nodes, the system automatically recognizes the new list. Rebooting the application server is not required.

Defining Nodes for Single Signon

Access the Node Definitions page (PeopleTools, Portal, Node Definitions).

The two options related to single signon are:

See Also

Adding and Configuring Nodes

Implementing Nonrepudiation

Setting up Certificate Authentication

This section provides additional details and steps to assist the configuration of certificate authentication used in a single signon implementation.

In the following scenario, you are configuring single signon between these two PeopleSoft systems.

Perform these steps:

1. Set certificate authentication option in master database.

2. Define the portal node and establish trust in content database.

3. Create the private key and install the digital certificate for the local node in master database.

4. Install the digital certificate for the remote node in the content-side database.

Setting Certificate Authentication Option in Master Database

To set certificate authentication option in master database:

1. Sign in to the Portal database.

2. Select PeopleTools, Portal, Node Definitions.

3. Select PSPORTAL from the list of nodes.

4. Verify that it is the local node.

5. Select Certificate from the Authentication Option drop-down list box.

6. Save the page.

7. Click the Return to Search button.

8. Verify that PSHCM exists as a remote node.

Defining Portal Node and Establishing Trust in Content Database

To define the portal node and establish trust in content database:

1. Sign in to the HCM database.

2. Select PeopleTools, Portal, Node Definition.

3. Click the Add a New Value link.

4. Enter PSPORTAL and click the Add button.

5. Select Certificate from the Authentication Option drop-down list box.

6. Save the page.

7. Select PeopleTools, Security, Security Objects, Single Signonand add the PSPORTAL message node to the list of trusted nodes in the Trust Authentication Tokens issued by these Nodes group box.

8. Save the page.

Creating the Private Key and Installing the Digital Certificate for Local Node

To create the private key and install the digital certificate for the local node:

1. Sign in to the Portal database.

2. Select PeopleTools, Security, Security Objects, Digital Certificates.

   Note. Make sure that Root CA with Issuer Alias of PeopleTools is available.

3. Click the Add a new row button (+).

4. Select Local Node as the Type..

5. Enter PSPORTAL in the Alias field.

6. Select PeopleTools as the Issuer Alias.

7. Click the Request link.

8. Fill in the form

   Note. For UNIX application servers, use 512 as the Key Size and PSPORTAL as the common name.

9. Click the OK button.

10. Select all of the text, copy the request, and click the OK button.

11. Request a certificate from your certificate provider.

12. Request the certificate using a base-64-encoded CMC or PKCS #10 file, or submit a renewal request by using a base-64-encoded PKCS #7 file.”

13. When you receive the certificate, download and save it to C:\temp as newcert.cer.

14. Open the certificate with a text editor.

15. Select all of the text and copy the certificate.

16. Sign in to the Portal database.

17. Select PeopleTools, Security, Security Objects, Digital Certificates.

18. Click the Import link for the PSPORTAL alias.

19. Paste the certificate into the text box.

    Note. Make sure that there is no space after END CERTIFICATE, otherwise, you are not allowed to save.

20. Click the OK button.

Installing Digital Certificate for the Remote Node in the Content-Side Database.

To install the digital certificate for the remote node in the content-side database:

1. Sign in to the HCM database.

2. Navigate to PeopleTools, Security, Security Objects, Digital Certificates.

3. Click the Add a new row button (+).

4. Select Remote Node as the Type..

5. Enter PSPORTAL in the Alias field.

6. Select PeopleTools as the Issuer Alias.

7. Click the Import link.

8. Open the certificate that you downloaded to C:\temp\newcert.cer with a text editor.

9. Copy the text and paste the digital certificate into the empty edit box.

10. Click the OK button.

Single Signon Transaction Example

Now that you have a general understanding of why a single signon implementation is useful, and some of the details involved with PeopleSoft-only single signon, this section presents an example of how the PeopleSoft-only single signon scheme works.

In this scenario there are two databases, or nodes: an HCM database and Financials database. Recall that the terms database and node are synonymous. Each database has one application server and one web server. The following steps describe the “back-end” events that occur when a user signs in to the HCM database, completes a transaction, and then clicks a link that targets a page in the Financials database.

Step 1: User Signs In to an HCM Application

The following occurs:

1. The user PTDMO clicks this link: http://hcm.peoplesoft.com/psp/hcmprod/?cmd=login&languageCd=ENG

2. The user enters ID and Password at the sign in page and clicks the Sign In button.

Step 2: Application Server Authenticates User

The following occurs:

1. The web server relays sign in request to the HCM application server.

2. The HCM application server authenticates the user.

Step 3: Application Server Generates Single Signon Token

The following occurs:

1. If the user is authenticated by the application server, then it generates a single signon token.

2. The application server encrypts and encodes the token (base 64).

3. The application server sends the token to the web server, along with a return code indicating that the system authenticated the user.

Step 4: Web Server Creates Cookie in User's Browser

When the web server receives the single signon token from the application server, it creates a cookie and inserts the cookie in the user's browser.

If the browser is configured to show the Security Alert dialog, then the user sees a message similar to the following example. In most cases, you don't configure browsers to show this dialog; this dialog box is just an example of the data that the browser receives.

The cookie that the web server distributes for PeopleSoft single signon is named PS_TOKEN. In this case the domain rt-sun23.peoplesoft.com set the cookie.

Notice that the cookie expires at the end of session. This indicates that the system never writes the cookie to disk, the cookie exists in browser memory for the duration of the session only.

The web server inserts the single signon token within the Data field of the cookie. So that the system can send the binary data across the HTTP protocol, the token data is encrypted and base 64 encoded.

Step 5: User Needs to Access Financial Application

After the user completes a few transactions in the HCM system, suppose they arrive at a page containing a link to the Financial system. The user clicks the link, and because they've already entered their credentials for the HCM system they don't need to sign in again.

The browser sends the PS_TOKEN cookie to the Financials web server.

Step 6: Financials Web Server Receives PS_TOKEN Cookie

The Financials web server does detect that the user hasn't been authenticated by the Financials system yet. However, because the web server received the signon cookie it does not display the sign in page.

To retrieve the page the user requested (by way of the link in the HCM application), the Financials web server attempts to connect to the Financials application server. It passes only the Data field from the PS_TOKEN cookie because the application server needs only the information in the Data portion.

Step 7: Financials Application Server Authenticates PS_TOKEN

Before allowing the user to connect, the Financials application server evaluates the PS_TOKEN Data field in the following flow:

1. Is the forwarding node trusted?

   The application server checks to see that the message node name listed as the Issuing System is a trusted node. The list of trusted nodes for the Financials system resides in the PSTRUSTNODES table. You configure the list using PeopleTools, Security Objects, Single Signon. The Single Signon page enables the administrator of the Financials system to "trust" authentication tokens generated from HCM as well as any other nodes deemed trusted.

2. Has the token expired?

   The application server checks that the authentication token hasn't expired. Using the Issued Date and Time field within the token, the Financials application server makes sure that the token was issued within the interval between the timeout minutes value and the current time. You configure a token's expiration time on the Single Signon page.

   Note. It is important to note that the expiration parameter specified in the Financials system is the relevant value, not the expiration value specified in HCM. This enables the Financials administrator to control the maximum age of an acceptable token. It's also important to consider that all times are in Greenwich Mean Time (GMT), so it doesn't matter what time zones the systems are in.

3. Has the signature been tampered with?

   The application server checks that the signature is valid. The Financials application server takes all the fields in the token and the Node password for the issuing node and generates a hash. The token is valid only if the signature within the token exactly matches the one generated by the Financials application server. Because an exact match is the only acceptable situation, Financials can be sure that HCM generated the token, and that it hasn't been tampered with since it was generated. If a hacker intercepted the token in transit and changed the User ID, Language, and so on, the signatures wouldn't match and as a result the Financials application server would reject the token.

   Note. You should use digital certificate authentication when implementing single signon.

PeopleSoft-Only Single Signon Configuration Considerations

The following topics describe some items you might want to consider as you implement your single signon configuration.

Single Authentication Domain Limitation

Web servers must be assigned to the same authentication domain—the server name in the URLs used to access them must contain the same domain name. A browser sends a cookie back only to the same domain from which it received the cookie.

In PeopleSoft applications, an authentication domain is not the same thing as an internet protocol (IP) address. An authentication domain is a logical URL address that you specify during Pure Internet Architecture setup, and its purpose is to associate different web servers (even at different physical locations) so that they appear to be at the same location to the PeopleSoft applications that use those web servers.

Important! Specifying authentication domains incorrectly for multiple Pure Internet Architecture installations can produce single signon errors.

If you want to keep two PeopleSoft applications from erroneously attempting to employ single signon, make sure that the authentication domain you specify for one application's web server is not a subset of the authentication domain you specify for the other. For example, if your CRM web server has an authentication domain of .crm.mycompany.com, your Financials web server authentication domain must not be .mycompany.com (the parent of the CRM server domain) or .fin.crm.mycompany.com (a child of the CRM server domain). It can, however, be .fin.mycompany.com (or any child of the mycompany.com domain).

If you do want two PeopleSoft applications to employ single signon, you must ensure that each application contains a definition of the other as a trusted node, and you must specify the same authentication domain for both applications' web servers during Pure Internet Architecture setup.

Furthermore, the web server that generates the cookie must have the domain that shares the PS_TOKEN cookie specified in the web profile of the local Pure Internet Architecture web site. For example, in the context of our HCM to Financials example, the web profile for the HCM web server must contain the value of .peoplesoft8.com in the Authentication Domain property.

Note. You must specify the leading dot (.).

The single domain issues occur in the following situations:

• You're using straight Pure Internet Architecture, as in you are deploying applications but not by way of the portal.

• You're using the portal with frame-based templates. All PeopleSoft portal solutions products (Enterprise, Employee, Customer, Supplier portals) are built using frame-based templates.

Frame-based templates aren't proxied automatically. Proxying refers to when the system rewrites the URL to point to a location on the portal servlet, rather than the original location of the URL.

Single Signon Between Machines without DNS Entries

If you're setting up single signon between machines that don't have DNS entries, you need to modify the hosts file on the machine that's running the web browser. For example, let’s say that you are using machine a.peoplesoft.com to signon to the web server a.peoplesoft.com, and then access b.peoplesoft.com using single signon. In this situation, you would need to update the hosts file on a.peoplesoft.com as follows.

# Copyright (c) 1993-1999 Microsoft Corp.
#
# This is a sample HOSTS file used by Microsoft TCP/IP for Windows.
#
# This file contains the mappings of IP addresses to host names. Each
# entry should be kept on an individual line. The IP address should
# be placed in the first column followed by the corresponding host name.
# The IP address and the host name should be separated by at least one
# space.
#
# Additionally, comments (such as these) may be inserted on individual
# lines or following the machine name denoted by a '#' symbol.
#
# For example:
#
#      102.54.94.97     rhino.acme.com          # source server
#       38.25.63.10     x.acme.com              # x client host

127.0.0.1       localhost
216.131.221.88  a.peoplesoft.com
66.122.220.101  b.peoplesoft.com

Domain Names

You need to use a fully qualified domain name when addressing the web server in your browser.

• This is an example of a correctly formatted URL: http://hcm.peoplesoft.com/myapplication/signon.html

• This is an example of a incorrectly formatted URL: http://hcm/myapplication/signon.html

When using the portal, the domain name that you specify in the Portal URI Text edit box on the Content Provider administration pages must match the fully qualified domain name you enter as the authentication domain. For example, you must specify serverX.peoplesoft.com/servlets, not serverX/servlets.

Cross Domain Single Signon

The current PeopleSoft single signon solution deals mainly with systems where there is only one DNS domain. Many sites need to deploy the PeopleSoft Portal in multi-domain environments. For example, you might want to have the portal in one domain such as, www.PSFT_ecenter.com, and the HCM database in another domain, such as www.yourcompany.com.

You can configure your environment to support cross-domain single signon by completing the following configuration tasks.

• Setup a third-party web security product that supports multi-domain single signon and supports LDAP user profiles.

  There are several industry-standard products on the market.

• Configure the portal and content provider web servers to trust the web server for authentication.

  For PeopleSoft applications , this involves creating and enabling the public access user.

• Set up the PeopleSoft applications to download the user profiles from the same LDAP server that the web security product uses.

  This means that the DN that comes from the subject field of the certificate has to be a valid DN for the directory that the LDAP_profilesynch function references. Because of this you need to build a user profile cache map that points to the same directory that generated the subject's DN.

Note. This cross-domain limitation does not apply to the portal if the content from the provider in a different domain is wrapped in an HTML template. However, this limitation does apply for any content in the portal that is wrapped in a frame template. Because the Enterprise, Customer, Supplier, and Employee portals that ship with PeopleTools all include frame templates as defaults, you'll need to perform the extra configuration steps to support cross-domain single signon in multi-domain environments. This limitation also applies to Pure Internet Architecture-to-Pure Internet Architecture (iClient-to-iClient) single signon.

PeopleSoft-Only Single Signon Configuration Examples

The following topics describe examples of single signon configurations and the steps required to implement them.

One Database and Two Web Servers

In this scenario there is one database and two or more web servers. While single signon is configured at the database level (that is, you specify timeout minutes and trusted nodes for the entire database), it’s actually used any time two different PeopleSoft servlets connect to the same database.

To set up single signon with one database and multiple web servers:

1. Select PeopleTools, Portal, Node Definitions and make sure that at least one node is defined as the Default Local Node.

   In the results on the search page, you can determine this by looking for a Y in the Default Local Node column.

2. Select PeopleTools, Security, Security Objects, Single Signon and set the following:

   • Make sure the Default Local Node appears in the list under Trust Authentication Tokens issued by these Nodes.

   • Set the timeout minutes to an appropriate value (the default is 720).

3. Access the web profile for each web server and modify the Authentication Domain property.

   Because single signon is implemented using browser cookies, it must be configured so that the user's browser sends the single signon cookie to each web server machine involved. By default, the browser only sends cookies back to the machine that set the cookie. So if web server a.peoplesoft.com sets a cookie after the user is authenticated, the browser (by default) only sends the cookie to a.peoplesoft.com. By default, the browser would not send the cookie to b.peoplesoft.com. To make the browser send the single signon cookie to all servers at in a domain (peoplesoft.com), access the Web Profile Configuration - General page and set a value of .peoplesoft.com for the Authentication Domain property.

   Note. You need the leading period (.) before the domain. It should appear as “.peoplesoft.com,” not “peoplesoft.com.”
   
   If you use only one web server, you don’t need to modify the Authentication Domain property. A web server is designed to accept the cookies it distributes.

Two Databases and Two Web Servers

To set up single signon with multiple databases and multiple web servers:

1. Select PeopleTools, Portal, Node Definitions.

   For each node that you want to involve in the single signon configuration and check the following:

   • Make sure that at least one node definition is defined as the Default Local Node for each database.

     In the results on the search page, you can determine this by looking for a Y in the Default Local Node column.

   • Make sure that each database contains a node definition for the other nodes in the single signon configuration.

   • Make sure that the Authentication Option is set correctly.

     For example, if you are using password authentication make sure that the node password for node ‘X’ is the same in each node definition for node ‘X’ in each database.

     If you use digital certificate authentication, make sure the certificates are properly installed in the PeopleSoft Keystore before setting the node’s Authentication Option to Certificate.

2. Select PeopleTools, Security, Security Objects, Single Signon and set the following:

   • Make sure the Default Local Node appears in the list under Trust Authentication Tokens issued by these Nodes.

   • Set the timeout minutes to an appropriate value (the default is 720).

3. Access the web profile on your web server and modify the Authentication Domain property.

   Because single signon is implemented using browser cookies, it must be configured so that the user's browser sends the single signon cookie to each web server machine involved. By default, the browser only sends cookies back to the machine that set the cookie. So if web server a.peoplesoft.com sets a cookie after the user is authenticated, the browser (by default) only sends the cookie to a.peoplesoft.com. By default, the browser would not send the cookie to b.peoplesoft.com. To make the browser send the single signon cookie to all servers at in a domain (peoplesoft.com), modify the authentication domain as follows.

See Working with SSL/TLS and Digital Certificates, Employing LDAP Directory Services.

Single Signon with Third Party Authentication

This section presents a simple example of how to implement single signon when you have implemented a third-party authentication system at the web server level. This applies to both portal and intranet web servers.

This discussion assumes that you have enabled public user access in the web profile for the appropriate site.

See Creating a Public Access User.

Note. While this example does not cover authentication, it assumes that you have set up your third-party authentication correctly. Third-party authentication is out of the scope for PeopleSoft support and documentation.

For PeopleSoft application single signon, the PeopleSoft system needs to know the user ID to be used for the web session. If implementing this configuration, you are required to address the following steps:

1. Authenticate the web user.

2. Determine which PeopleSoft user ID to use for this web user.

3. Send the user ID to the PeopleSoft application server.

4. Write Signon PeopleCode to retrieve the user ID from the location, as indicated in step 3.

5. Reauthenticate the user ID during Signon PeopleCode.

6. Indicate to the PeopleSoft application server to use the user ID for all subsequent service requests.

The following examples address steps 3, 4, and 6.

The following HTML applies to step 3 above. You can change the JavaScript function to set the cookie name and value that you want. Also, change the location to point to the PeopleSoft page to which you want to redirect users, for example:

<html>
<head>
<title>PeopleSoft 8 Single Signon Example</title>
</head>

<!--
PeopleSoft 8 Single Signon Example

In this example, security is non-existent.  In a production
system, the UserId could come from your site's single signon
tool.  Other information could also be included.  For this
example, only the UserId is saved into cookie.  This cookie then
gets sent to the PIA Web Servlet which passes it on to the
PeopleSoft Application Server.  A piece of Signon PeopleCode is
needed to extract the UserId from the cookie and call
SetAuthorizationResult to "sign on" the user.

- Change the domain value of the cookie to your domain.
- Change the location ref to the target URL within your PeopleSoft site.
//-->

<body>
<script language=JavaScript>
var cookie = "ThirdPartyUserId=PS; Domain=.peoplesoft.com; path=/; MaxAge=1";
document.cookie = cookie;
location="https://hcm.oraclepeoplesoft.com/psp/hcmprod/EMPLOYEE/HCM/c/ROLE_⇒
EMPLOYEE.TIME_OFF.GBL?FolderPath=PORTAL_ROOT_OBJECT.EE_SELF_SERVE.EE_TIMEOFF_⇒
GBL&IsFolder=false&IgnoreParamTempl=FolderPath%2cIsFolder"</script>
</body>

</html>

The following Signon PeopleCode example applies to steps 4 and 6 above. The Signon PeopleCode needs to retrieve &UserID from where the third-party portal put it in the HTTP Request. For example,

Function SSO_EXAMPLE()
   
/*This is step 4*/
   &TPUserId = %Request.GetCookieValue("ThirdPartyUserId");
   /*This is step 6*/
   If &TPUserId <> "" Then
      SetAuthenticationResult( True, &TPUserId, "", False);
   End-If
End-Function;

After you write the program, you need to enable the program using the Signon PeopleCode page. (PeopleTools, Security, Security Objects, Signon PeopleCode.

Securing the PeopleSoft-Only Single Signon Token

PeopleSoft single signon functionality also applies at the web server level. For example, let's say that you have two web servers: server X and server Y. Assume that web server X is an SSL/TLS site, and assume that web server Y is not. In these situations, many organizations want server Y to trust the authentication token, PS_TOKEN, issued by server X. This requires that the PS_TOKEN be set to be secure.

If the PS_TOKEN is not marked as secure, then when a user signs in through server Y, the browser sends PS_TOKEN to server Y over the unencrypted, non-SSL/TLS link. This is typical behavior for browsers when dealing with non-secure cookies. Potentially, in this situation a hacker could identify this token from the clear network and use it to signon to the SSL/TLS-secure server X.

Another important use of this feature relates specifically to the PeopleSoft Enterprise Portal. When the portal proxies content with an HTML template, it should forward PS_TOKEN cookies that are marked secure only over SSL/TLS connections.

To resolve this potential security issue, select the Secure Cookie with SSL check box on the Web Profile Configuration - Security page. You use this property to control the secure attribute of the single signon cookie. If you enable the property, and the scheme of the current request is HTTPS (an SSL/TLS server), the system sets the secure attribute of the single signon cookie (PS_TOKEN) to true. This prevents the single signon token from travelling over an insecure network.

Note. If you enable this property, you are effectively disabling single signon to any non-SSL/TLS servers.

If, at your site, you want users to sign in to an HTTPS server, and then want to do single signon with HTTP servers, set this property to false, which allows single signon between HTTPS and HTTP servers.

Note. If you can tolerate the security risk, and want single signon between secure and non-secure links, you can set this flag to false. However, before doing this make sure you are aware of all the security implications, such as the security of the HTTPS server may be compromised.

Using the Single Signon API

PeopleSoft provides a component interface named PRTL_SS_CI that enables external applications to seamlessly integrate a single signon solution with the PeopleSoft portal applications. This ensures that users who have already signed in to the portal don't have to sign in again for every system you reference in your portal.

To take advantage of the Single Signon API, you need to create a custom API, which includes building the dynamic link libraries, classes, and registry settings necessary to enable an external application to communicate with PeopleSoft software.

Note. Due to constraints imposed by the PeopleCode SwitchUser built-in function, PRTL_SS_CI does not work properly when called from PeopleCode. Only external applications, such as Java, Visual Basic, and C/C++ programs, can access PRTL_SS_CI.

The files of your custom API need to reside on the client machine; that is, the web server for ASP, and the machine running the Java program for Java. The registry file may also need to be executed to update the registry with the new libraries.

Understanding 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 if 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 we describe the development requirements of your API, PeopleSoft recommends that you take a moment to examine the steps that occur internally when you use the API in conjunction with the delivered PRTL_SS_CI.

Developing your External Application to Support Single Signon

Developers of the external applications need to alter the signon process to conform to the following requirements.

1. Check for the PS_TOKEN cookie.

   If the cookie doesn’t exist, continue with your normal signon process. Otherwise, bypass the sign in page.

2. Retrieve the authentication token from the PS_TOKEN cookie.

3. Make a connection to the PeopleSoft system through the PRTL_SS_CI API.

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

5. If the function returns True, you then the Get_UserID() function retrieves the user ID associated with the authentication token.

Note. The component interface is not mapped to data because the key field for the data would be the authentication token. This token is dynamically assigned when the user signs in to the portal, and it is not stored anywhere in the system as data. Therefore, there are no key fields and the token is passed directly to the user defined functions.

Configuring PeopleSoft-Only Single Signoff

In addition to single signon, the PeopleSoft system also signs the user off of content providers when the user signs off. However, there are some exceptions to the sign-off functionality.

The portal only signs out content providers that meet the following criteria:

• Content providers are accessed only through HTML templates.

• Content providers are all PeopleSoft 8.x applications.

This means that for content providers accessed through frame templates, single sign off is not automatically enabled when you configure single signon. This section describes the steps you need to complete to configure single sign-off for content providers being accessed through frame templates, which includes all of the PeopleSoft Portal solutions (Employee, Customer, and so on).

The following procedure covers inserting an HTML image tag <img> containing a logout command into a set of files on the web server. When the user signs off, the browser attempts to download the images using an "HTTP get," which causes the system to send the logout command to each specified content provider.

This procedure is not appropriate for content that is never accessed using a frame, as in it is accessed from the content source using an iScript and a business interlink, such as Lotus Notes integration.

To configure single sign-off for frame content:

1. On your web server, locate and open signin.html.

2. Open signon.html, select Save As, and enter the name signout.html.

3. Open signout.html, expire.html, and exception.html.

4. Add the following image tags to these files.

   You need to add one image tag to each of these files for each content provider that requires single signoff.

   Add the tags just before the closing body tag, as shown:

   <! add tags here>
   </body>

   If you have three content providers that require single signoff, such as HCM, FIN, and HTML Access, you need to add three image tags to each file.

   For example:

   <IMG src="http://hcm.peoplesoft.com/servlets/psp/ps/hrdb/?cmd=logout"
   height=0 width=0 border=0>
   <IMG src="http://fin.peoplesoft.com/servlets/psp/ps/hrdb/?cmd=logout"
   height=0 width=0 border=0>
   <IMG src="http://htmlaccess.peoplesoft.com/html_access/system/init_asp/
   logout.asp?cmd=dummy"
   height=0 width=0 border=0>

   The previous code is an example. To determine the exact URL you need to add for your implementation, right-click the logout link of each content provider. You can usually view the logout link when accessing the application outside of the portal. Examine the properties of this link, and add the specified URL to the image tag.

   Note. The string "cmd=dummy" is required in the image tag for HTML Access to make sure that the browser doesn't attempt to cache the image, which would prevent it from issuing the logout command.

5. Select PeopleTools, Web Profile, Web Profile Configuration, Look and Feel on your web server.

   In the Signon/Logout Pages group box, change the value of the Logout Page field to signout.html.

Implementing Oracle Access Manager as the PeopleSoft Single Signon Solution

PeopleSoft applications support Oracle Access Manager as the single signon solution.

To implement Oracle Access Manager as the PeopleSoft single signon solution:

1. Install and configure Oracle Access Manager.

   See Oracle Access Manager Installation Guide

2. In the PeopleSoft application, create OAMPSFT as a new user profile and associate a low security role such as PeopleSoft User.

   See Creating a New User Profile.

3. In the user profile, access the ID page and select NONE as the ID type.

   See Defining User Profile Types.

4. Save the user profile.

5. Access the web profile and enter OAMPSFTas the public access user ID.

   See Configuring Web Profiles.

6. Using PeopleSoft Application Designer, open the FUNCLIB_LDAP record.

7. Right-click the LDAPAUTH field and select View PeopleCode.

8. Find the getWWWAuthConfig() function and replace the value that is assigned to the &defaultUserId with OAMPSFT.

9. Save the record definition.

10. Access the Signon PeopleCode page (PeopleTools, Security, Security Objects, Signon PeopleCode) and enable the OAMSSO_AUTHENTICATION function—the Signon PeopleCode for Oracle Access Manager single signon.

11. Save the page.

12. WebLogic users must disable basic authentication.

    Access <PIA_HOME>\webserv\peoplesoft\config> and modify the config.xml file by adding this tag: <enforce-valid-basic-auth-credentials>false</enforce-valid-basic-auth-credentials>

    For Example:

    <security-configuration xmlns:xacml="http://www.bea.com/ns/weblogic/90/security⇒
    /xacml">
        <name>peoplesoft</name>
        <realm>myrealm</realm>
    	
    .......
    
        <credential-encrypted>{3DES}dOa1fqoTbX1GUq7RQPhDNDgkWkIZhzWVlEXkmSMbt9Uuf1Ff⇒
    VZIrJC</credential-encrypted>
        ​<enforce-valid-basic-auth-credentials>false</enforce-valid-basic-auth-⇒
    credentials>
    ​
      </security-configuration>

13. Stop and restart the application server, web server, and HTTP server.

Implementing Kerberos as the Desktop Single Signon Solution

This section presents an overview of a Kerberos-PeopleSoft integration, presents considerations for securing Kerberos tokens across the enterprise, and then discusses how to:

• Configure the directory server to act as the Key Distribution Center (KDC).

• Set up Kerberos authentication on the web server.

• Set up Kerberos authentication on the application server.

• Write Signon PeopleCode for Kerberos authentication.

• Configure the PeopleSoft application for Kerberos authentication.

• Modify Signon PeopleCode to include Kerberos authentication.

Understanding Kerberos-PeopleSoft Integration

Kerberos is a network protocol that uses secret key cryptography to provide authentication between clients and servers. The Kerberos authentication protocol enables mutual authentication between clients and servers before secure network connections are established. Kerberos establishes trust between a client and server by using a third party intermediary called the Key Distribution Center (KDC). The KDC stores a secret key (password) for every client and server on the network. Clients and servers authenticate each other by exchanging tickets, which represent the clients' network credentials. When a client wants to access a server, the client first authenticates against the KDC and requests a client-to-server ticket for that server. The client then presents that ticket to the server, which validates the credentials and then processes the client’s request.

In Kerberos-PeopleSoft single signon integrations, the Kerberos server handles HTTP requests. While Kerberos was not specifically designed to operate over HTTP, tokens can nonetheless be wrapped within HTTP headers according to the Simple Protected Negotiate (SPNEGO) protocol. In a Kerberos-PeopleSoft implementation, you must configure the web server to:

1. Accept the HTTP-wrapped Kerberos tokens that are sent by the client.

2. Forward the user credentials on to the application server for signon.

Note. The Kerberos protocol assumes that transactions between clients and servers take place on an open network where most clients and many servers are not physically secure, and packets traveling along the network can be monitored and modified freely. In such a situation, Kerberos authentication prevents hackers, who can appear to be either a client or a server, from accessing , viewing , and manipulating communications between legitimate clients and servers.

When implementing Kerberos desktop single signon, you configure your directory server to act as the KDC. All clients and servers must authenticate against the KDC before they can communicate securely with each other. Clients authenticate when a user signs in using network credentials from a laptop or desktop machine. Servers, on the other hand, generally authenticate as a different user than the one running the server process. Because of this, you must create a server user account in your directory.

A user's credentials must pass to the server machine; you do this by using a keytab file. The keytab file stores the name and encrypted password of the server user account. The use of the keytab file enables a server to automatically authenticate against the KDC without prompting for the password or storing it as plaintext. You also must map the server user’s credentials to a Service Principal Name (SPN) that matches the website that the server hosts. For example, if a browser requests a client-to-server ticket for www.example.com, it asks the KDC for a ticket to a service principal named HTTP/www.example.com@example.com. You must create the mapping between this SPN and the server user.

Note. Kerberos authentication supports any LDAP V3 compliant directory server. Set up for Microsoft Active Directory is included in an appendix in this PeopleBook.

See Enabling Kerberos Authentication in a Microsoft Active Directory Environment.

The PeopleSoft Web Server KerberosSSOFilter Servlet

The PeopleSoft web server requests authentication from the client and then forwards the client credentials to the application server. This process is encapsulated in the KerberosSSOFilter servlet filter, which you attach to the PeopleSoft portal servlet. Servlet filters are intermediaries between the portal servlet and the client. Filters can:

• Pass messages through unchanged.

• Modify message contents.

• Stop messages entirely.

The following diagram illustrates the request and response flow between the client, the KerberosSSOFilter, and the portal servlet:

KerberosSSOFilter authentication process flow

This table describes the requests and responses between the client, the KerberosSSOFilter and the web server.

The filter first checks to see if the client request (1) has a valid session id. If it does, then the client is already authenticated and no further action is required (5). If not, the filter checks the request’s headers for a Kerberos token. This token is then validated using the server’s credentials. If the token is valid, the authenticated username is added to the request in a special header, KRB_USER (3). The application server can then retrieve the username from this header, once it receives the request.

If the token is invalid, the token header is removed, making it appear to the servlet (and eventually the application server) as if no ticket exchange occurred (6). If no Kerberos token is present, then the filter must request authentication (2). Before doing so, it checks if the request is a POST. POST requests are always passed through to the Servlet (7), because the client browser will not resend POST parameters along with the authentication information. In addition, POST is used during regular web-based sign in, and performing single signon simultaneously with this is redundant and not a good practice. For the sake of correctness and simplicity, POST requests never trigger authentication requests or single signon.

After the filter makes the authentication request, the browser must determine how to proceed. If it can find appropriate credentials (a client-to-server ticket) then it will repeat the request (1) with the appropriate token in the header. Note that a browser may not respond to an authorization request if it cannot acquire credentials. The user will then not be able to view the site. Setting up the browser to avoid this is discussed in Browser Configuration. The filter is transparent to servlet responses. That is, responses from the servlet (4) pass through unchanged. Thus, responses from the application server are also unaffected by the filter. In other words, once Kerberos authentication completes and the user is issued a valid session ID, client/server messages will continue as if the filter was not present (the path going through 1, 5 and 4).

This table describes a typical single signon transaction in which Kerberos provides valid credentials during the authentication process:

This table describes a typical single signon transaction in which Kerberos provides invalid credentials during the authentication process:

PeopleSoft Public Access and Signon PeopleCode for Kerberos Authentication

Although the web server performs Kerberos authentication, the application server is responsible for signon. The web server determines the network or directory username, but the application server must then map that name to a PeopleSoft user ID and sign the user in. To achieve single signon, the application server must perform these functions any time a user requests a PeopleSoft page, for example by clicking a link or by selecting a browser Favorite or Bookmark. You enable the application server to map the directory username to the PeopleSoft user ID by setting up public access, and then by adding a Kerberos authentication Signon PeopleCode function.

When a user who is not signed in requests a page, the application temporarily signs in as the public access user. You configure Single Signon settings that instruct the application server to run the KRB_AUTHENTICATION PeopleCode function in the FUNCLIB_LDAP record. This function checks for the request headers that the KerberosSSOFilter generates, and then performs the mapping and sign in operations.

The PeopleCode function that performs the user mapping depends on your specific implementation, but if you import your PeopleSoft users through LDAP from the same directory server that you use for Kerberos authentication, then the mapping is straightforward. For example, Kerberos authentication might return a username in this format: johnsmith@EXAMPLE.COM, while in your PeopleSoft application, the user ID is simply, johnsmith. In this case, the mapping operation merely strips @EXAMPLE.COM from the Kerberos username string.

Note. If the application server finds no authentication headers, then you should retrieve the PeopleSoft Sign In page so that a user is unaware of a failed attempt at authentication.

Browser Configuration

Internet Explorer default settings typically work with Kerberos single signon. However, if the browser settings are not the default, you might need to change the browser settings. In addition, Internet Explorer only uses Kerberos authentication for sites in the Local intranet zone. If your PeopleSoft applications are not within this zone, you must add them.

See Enabling Kerberos Authentication in the Browser.

Considerations for Securing Kerberos Tokens Across the Enterprise

The previous sections discuss a web server-only implementation of Kerberos authentication. While this set up is a robust single signon solution, some elements remain less than optimally secure. In a web server-only implementation, the application server trusts any username that the web server places into the KRB_USER header. If the Kerberos token is accessed and manipulated between the web server and the application server, a hacker can very possibly sign in to PeopleSoft applications as any user. The web server-only configuration places an inordinate amount of trust on the PeopleSoft web server, yet ignores the connection between the web and application servers.

To make Kerberos authentication more secure, you can:

• Configure the application server to re-validate the Kerberos token.

• Configure the KerberosSSOFilter to request Kerberos tokens over a secure network connection only.

• Bypass KerberosSSOFilter authentication and forward the Kerberos token directly to the application server.

By using these methods, you make it almost impossible to trick the application server with a username and prevent network traffic sniffing. You also decrease the load on the web server.

Understanding Kerberos Authentication on the Application Server

In a typical configuration, the web server forwards the Kerberos token that it receives from the client to the application server, but the application server ignores it. To make the token more secure, set up the application server to run a Java program that accesses and validates the Kerberos token. The program should check the keytab for the username (the same way that the KerberosSSOFilter does), compare the username from the keytab to the value in the KRB_USER header, and then only if they match continue the sign in process.

Understanding Kerberos Authentication on an Encrypted Network

Kerberos single signon should be done through an encrypted channel by using SSL/TLS. Encrypting the channel substantially increases security. Using a secure channel requires no changes to the Kerberos single signon configuration, only that PeopleSoft pages are accessed through HTTPS rather than HTTP. To help enforce this policy, configure the KerberosSSOFilter to request Kerberos tokens over a secure connection only. When you implement this configuration, the filter passes any request that comes over an non-secure connection directly to the web server.

Note. Requiring this setting is not always appropriate. If the web server uses a proxy to connect securely to the client, then the connection between the proxy and the web server might not be secure, although the connection to the client is. In this case, the KerberosSSOFilter will not recognize that the connection is actually secure and will not request authentication.

Forwarding Kerberos Tokens Directly to the Application Server

Another possible configuration is to have the KerberosSSOFilter perform no authentication, but to forward tokens directly to the application server. The filter still must request the token, but does not validate it or add a KRB_USER header before passing the message on. The application server is responsible for both validation and sign in. Although this configuration only requires one validation step, rather than two, it also prevents the KerberosSSOFilter from appending a mutual authentication token.

Typically, a mutual authentication token is returned as part of the response to a successful authentication attempt. In theory, the browser can use the token to verify the identity of the website—making the authentication mutual. In practice, however, neither Mozilla Firefox nor Microsoft Internet Explorer does this. Removing authentication from the filter simply decreases the load on the web server.

Configuring the Directory Server to Act as the Key Distribution Center KDC

To configure your directory server to act as the KDC:

1. Create an appropriate server user account in the directory.

2. Generate the keytab file. The keytab file stores the name and encrypted password of the server user account.

3. Map the server user credentials to a Service Principal Name (SPN) matching the website that the server hosts.

   When a browser requests a client-to-server ticket for www.example.com, the browser asks the KDC for a ticket to a service principal named HTTP/www.example.com@example.com.

See Also

Enabling Kerberos Authentication in a Microsoft Active Directory Environment

Setting up Kerberos Authentication on the Web Server

To set up Kerberos authentication on the web server:

• Configure the web server JVM for Kerberos authentication.

• Attach the KerberosSSOFilter to the PeopleSoft portal servlet.

Configure the Web Server JVM for Kerberos Authentication

To configure the web server JVM for Kerberos authentication:

1. Place the keytab file in a folder, such as C:\krb\, on the server.

   The actual location is not important as long as it is accessible by the server.

   Important! Use caution when you transfer the keytab; any party that gains access to it can pose as the server.

2. In the same folder, create two configuration files:

   • krb5.conf

     The krb5.conf file defines the domain to use for authentication and the domain controller to use as the KDC. For example, if you use the example.com domain with a domain controller at 192.168.1.1, then the krb5.conf file should contain:

     [libdefaults] default_realm = EXAMPLE.COM [realms] EXAMPLE.COM = { kdc = 192.168.1.1 }

   • krbLogin.conf.

     The krbLogin.conf file defines how the server authenticates against the KDC. For example, if you use a server that hosts www.example.com with keytab krb5.keytab in C:\krb\, then the krbLogin.conf file should contain: krbServer { com.sun.security.auth.module.Krb5LoginModule required storeKey=true useKeyTab=true keyTab="C:/krb/krb5.keytab" isInitiator=false principal="HTTP/www.example.com"; };

     Note. Use forward slashes in the keytab path.

3. Configure the web server to use these files for Kerberos authentication, by adding JVM arguments.

   1. Edit the setEnv.cmd file in the <PS_HOME>\webserv\peoplesoft\bin\ directory.

   2. Find the line that begins with SET JAVA_OPTIONS_WIN= and append the line with this text:

      -Djava.security.auth.login.config="C:\krb\krbLogin.conf
      -Djava.security.krb5.conf="C:\krb\krb5.conf"

4. Save the file.

Attaching the KerberosSSOFilter to the PeopleSoft Portal Servlet

To attach the KerberosSSOFilter to the PeopleSoft portal servlet:

1. These Java class files should be present in the <PS_HOME>\webserv\peoplesoft\applications\peoplesoft\PORTAL.war\WEB INF\classes\com\peoplesoft\pt\desktopsso\kerberos directory.

   • KerberosSSOFilter.class

   • KerberosSSOFilter$1.class

   • KerberosSSOFilter$KerberosAuthWrapper.class

   • KerberosSSOFilter$KerberosHideWrapper.class

   Note. In addition to the compiled Java classes, all PeopleSoft applications include the Java source code for the Kerberos single signon. You can find the source code files in the <PS_HOME>\sdk\desktopsso\src\com\peoplesoft\pt\desktopsso\kerberos directory.

2. Open the web.xml file in the <PS_HOME>\webserv\peoplesoft\applications\peoplesoft\PORTAL.war\WEB INF\ directory.

3. Find the section that begins and ends with <display-name> ... </display-name> and below that section insert the following xml. This table describes the purpose of the xml.

   XML	Description
   <filter> <filter-name>KerberosSSO</filter-⇒ name> <filter-class>com.peoplesoft.pt.des⇒ ⇒ ktopsso.kerberos.Kerberos SSOFilter</filter-class>	Begin the filter definition. Identify the filter as KerberosSSO. Identify the location of the KerberosSSO Java class files (Java servlet) that the web server calls.
   <init-param> <param-name>checkSecureConnection<⇒ ⇒ /param-name> <param-value>true</param-value> </init-param>	Require a secure (HTTPS) connection for the authentication request. If the parameter value is true, use HTTPS connections only. If the parameter value is false, non-HTTPS connections are allowed.
   <init-param> <param-name>validateToken</param-⇒ name> <param-value>true</param-value> </init-param>	Check for a valid Kerberos token. If parameter value is true, then the web server calls the KerberosSSOValidator Java class to validate the Kerberos token. If the parameter value is false, then bypass the web server and forward the Kerberos token to the application server for validation. Important! If set to false, you must set up the application server to call the KerberosSSOValidator Java class. See Configuring the Application Server JVM to Validate the Kerberos Token.
   <init-param> <param-name>verbose</param-name> <param-value>true</param-value> </init-param> </filter>	Turn on verbose tracing of the Java class so that you can debug it if there is an issue. If the parameter value is true then the web server writes extensive comments to the Java console as the KerberosSSOValidator runs. If the parameter value is false then the web server does not create a debug file in the Java console as the KerberosSSOValidator runs. Note. The program doesn't create and store a physical log file on the web server. End the filter definition.
   <filter-mapping> <filter-name>KerberosSSO</filter-⇒ ⇒ name> <url-pattern>/*</url-pattern> </filter-mapping>	Map specific URLs to specific filters. Specify the Kerberos filter. Specify the URLs by their pattern; /* indicates that all URLs should be directed to the filter.

4. Save the file.

Setting up Kerberos Authentication on the Application Server

Setting up Kerberos authentication on the application server requires that you configure the application server JVM to validate the Kerberos token:

Configuring the Application Server JVM to Validate the Kerberos Token

To configure the application server JVM to validate the Kerberos token:

1. These Java class files should be in the <PS_HOME>\class\com\peoplesoft\pt\desktopsso\kerberos directory.

   • KerberosSSOValidator.class

   • KerberosSSOValidator$1.class

   Note. In addition to the compiled Java classes, all PeopleSoft applications include the Java source code for the KerberosSSOValidator. You can find the source files in the <PS_HOME>\sdk\desktopsso\src\com\peoplesoft\pt\desktopsso\kerberos directory.

2. Open the application server configuration file: psappsrv.cfg

3. Find the line that begins with JavaVM Options=and append the line with this text:

   -Djava.security.auth.login.config=C:\krb\krbLogin.conf
   -Djava.security.krb5.conf=C:\krb\krb5.conf.
   

4. Save the file.

Writing Signon PeopleCode for Kerberos Authentication

The Signon PeopleCode function that you create for Kerberos authentication can vary based on where you want authentication to occur. This section discusses Signon PeopleCode that implements Kerberos authentication:

• At both the web and application servers.

• At the application server only

Implementing Kerberos Authentication at Both the Web and Application Servers

To implement Kerberos authentication at both the web and application servers only:

1. In PeopleSoft Application Designer, open the FUNCLIB_LDAP record definition. Right-click the LDAPAUTH field and select View PeopleCode.

2. Find the Function getWWWAuthConfig() PeopleCode function.

3. Change the &defaultUserId to “PUBUSER”.

4. In the same field and event, add a KRB_AUTHENTICATION function.

   This table describes the elements that make up a sample Kerberos authentication Signon PeopleCode program:

   Code	Description
   Function KRB_AUTHENTICATION() If %PSAuthResult = True And &authMethod <> "WWW" And &authMethod <> "OAMSSO" And &authMethod <> "OSSO" And &authMethod <> "SSO" And &authMethod <> "LDAP" Then	Declare the function. Check that the user is authorized and that the application is using no other authentication method.
   getWWWAuthConfig(); If %SignonUserId = &defaultUserId Then Local string &princName = %Request.Get⇒ Header("KRB_USER"); Local string &krbToken = %Request.Get⇒ Header("Authorization"); Local string &userName = &princName; Local number &foundDelim = Find("@",⇒ &userName);	Trust web server authentication. Verify that the public user is the current user and then, Retrieve the Authentication header from the KRB_USER and set it as the Kerberos token. Set the user name to be the principal name. Find the numeric location of the @ sign in the name.
   If (&foundDelim > 0) Then &userName = Substring(&userName, 1,⇒ &foundDelim - 1); End-If;	If there is something in front of the @ symbol in the name, then Strip the text that precedes the @ symbol and set it as the user name..
   If Len(&userName) > 0 Then &krbToken = Substring(&krbToken,⇒ 11, Len(&krbToken) + 1); &validator = GetJavaClass⇒ ("com.peoplesoft.pt.desktopsso.kerberos. KerberosSSOValidator").getInstance(); Local string &validUserName =⇒ &validator.validate(&krbToken);	If there is a user name, then Extract the user name from the Kerberos token. Call the Kerberos validation program and validate the Kerberos token.
   If &validUserName <> "NULL" And &princName = &validUserName Then SetAuthenticationResult⇒ (True, Upper(&userName), "", False); &authMethod = "KRB"; End-If; End-If; End-If; End-If; End-Function;	If the user name contains a value, then Compare the principal name to the name in the Kerberos token, and if the values are the same, Authenticate the user and sign in. Specify to the system that Kerberos authentication was performed so that other Signon PeopleCode functions can perform similar checks to the one at the beginning of function. Close the if statements. Close the function.

5. Save the record definition.

Implementing Kerberos Authentication at the Application Server Only

To implement Kerberos authentication at the application server only:

Note. In the web.xml file on the web server, make sure that you have set the validateToken parameter to false so that the web server forwards the Kerberos token directly to the application server.

1. In PeopleSoft Application Designer, open the FUNCLIB_LDAP record definition. Right-click the LDAPAUTH field and select View PeopleCode.

2. Find the Function getWWWAuthConfig()PeopleCode function.

3. Change the &defaultUserId to “PUBUSER”.

4. In the same field and event, add a KRB_AUTHENTICATION function.

   This table describes the elements that make up a sample Kerberos authentication Signon PeopleCode program:

   Code	Description
   Function KRB_AUTHENTICATION() If %PSAuthResult = True And &authMethod <> "WWW" And &authMethod <> "OAMSSO" And &authMethod <> "OSSO" And &authMethod <> "SSO" And &authMethod <> "LDAP" Then	Declare the function. Check that the user is authorized and that the application is using no other authentication method.
   getWWWAuthConfig(); If %SignonUserId = &defaultUserId Then Local string &krbToken = %Request.Get⇒ Header("Authorization");	Trust web server authentication. Verify that the public user is the current user and then, Retrieve the Authentication header from the Kerberos token.
   If Len(&krbToken) > 12 Then &krbToken = Substring(&krbToken,⇒ 11, Len(&krbToken) + 1); &validator = GetJavaClass⇒ ("com.peoplesoft.pt.desktopsso.kerberos. KerberosSSOValidator").getInstance(); Local string &userName =⇒ &validator.validate(&krbToken);	Extract the user name from the Kerberos token. Call the Kerberos validation program and validate the Kerberos token.
   If &userName <> "NULL" Then Local number &foundDelim = Find⇒ ("@", &userName); If (&foundDelim > 0) Then &userName = Substring(&user⇒ Name, 1, &foundDelim - 1); End-If; SetAuthenticationResult(True,⇒ Upper(&userName), "", False); &authMethod = "KRB"; End-If; End-If; End-If; End-If; End-Function;	If the user name contains a value, then Find the @ symbol and strip the text that precedes the @ symbol and set it as the user name. Authenticate the user and sign in. Specify to the system that Kerberos authentication was performed so that other Signon PeopleCode functions can perform similar checks to the one at the beginning of function. Close the if statements. Close the function.

5. Save the record definition.

Configuring a PeopleSoft Application to Use Kerberos Authentication

To configure the PeopleSoft application to use Kerberos authentication:

• Enable public access.

• Enable Kerberos authentication Signon PeopleCode.

Enabling Public Access

To enable public access:

1. Select PeopleTools, Web Profile, Web Profile Configuration and open the profile to which you are adding Kerberos authentication.

2. On the Security tab, select the Allow Public Access check box and then enter the user ID and password of the public access PeopleSoft application user. This user should have minimal permissions.

   In this example, you see that public access is enabled as the user ID, PUBUSER.

   Note. You are not limited to PUBUSER as the user ID, however, the user ID on this page must be the same user ID that you entered in the getWWWAuthConfig()function in the Signon PeopleCode.

3. Save the web profile.

Enabling Kerberos Authentication Signon PeopleCode

To enable Kerberos authentication Signon PeopleCode:

1. Select PeopleTools, Security, Security Objects, Signon PeopleCode.

2. Insert a new row and enter these values:

   Field	Value or State
   Enabled	Selected
   Record	FUNCLIB_LDAP
   Field Name	LDAPAUTH
   Event Name	FieldDefault
   Function Name	KRB_AUTHENTICATION
   Exec Auth Fail	Selected
   Sequence	Enter a value that does not conflict with the flow of other Signon PeopleCode functions.

3. Save the page.

   In this example, you see that the Kerberos authentication Signon PeopleCode, the KRB_AUTHE NTICATION function, is enabled:

See Also

Creating a New User Profile

Creating a Public Access User

Public Users