Using Signon PeopleCode

This section provides overviews of Signon PeopleCode and Signon PeopleCode permissions, and discusses how to:

  • Modify Signon PeopleCode.

  • Enable Signon PeopleCode.

  • Access X.509 certificates.

Signon PeopleCode runs whenever a user signs in to a PeopleSoft application. The main purpose of Signon PeopleCode is to copy user profile data from a directory server to the local database whenever a user signs in. This ensures that the local database has a current copy of the user profile. Because Signon PeopleCode runs at each signon, you are not required to maintain the local copy of the user information.

Signon PeopleCode is not limited to Lightweight Directory Access Protocol (LDAP) integration. You can also use Signon PeopleCode and business interlinks to synchronize a local copy of the user profile with any data source when a user signs in. Because the signon program is written in PeopleCode, you can customize it any way that suits your site requirements.

The basic process flow of Signon PeopleCode is as follows:

  1. A user enters user ID and password on the signon page.

  2. PeopleTools attempts to authenticate a user with the local PeopleSoft password.

  3. Signon PeopleCode runs.

    It verifies the user and password, and then updates the local cache of user profiles stored in the PeopleSoft database.

Signon PeopleCode runs only when a user logs on through Pure Internet Architecture, the portal, or a three-tier Windows workstation.

Note: If you are using LDAP authentication, the PeopleSoft authentication process will fail because the user password is not stored within the PeopleSoft database. Because of this, if you are using LDAP authentication, you set your Signon PeopleCode program to run when PeopleSoft authentication fails.

Signon PeopleCode scripts run with full permissions of the user they’re invoked as. This includes access to the database using Structured Query Language (SQL), access to the file system, business interlinks, component interfaces application messaging, and so on. A developer could conceivably write a Signon PeopleCode program that exposed or corrupted sensitive information. To minimize this risk, you should follow these guidelines:

  • You should limit access to the Signon PeopleCode setup page to trusted administrators only.

    This will prevent people from configuring un-trusted PeopleCode programs to run at sign-on time.

  • If you aren’t implementing external authentication at your site (all your users are authenticated based on an existing user ID and password with the PeopleSoft database), you should not have the “Exec Auth Fail” column selected for any Signon PeopleCode scripts.

  • After a trusted administrator configures the list of functions that should run at sign-on time, you should use Object Security to restrict access to the record objects that contain the programs.

    Only trusted developers should be allowed to modify the PeopleCode on these records.

  • Even for trusted developers, it is a good idea to have a second person review the code before testing and moving to production.

  • No developer or administrator should have access to the Signon PeopleCode setup page, or the records that contain the Signon PeopleCode functions in a production system.

Note: The password that the user types on the signon page is never visible to the Signon PeopleCode developer. It is impossible to write a script that captures a password entered by a user, and store it in a file or database table.

Signon PeopleCode is record PeopleCode, which you view and edit on the record with which the program is associated. PeopleSoft applications deliver a PeopleCode program for directory authentication. It is intended for production use but it can also be used as a sample that shows many of the technologies you can include within a Signon PeopleCode program. You can find the delivered PeopleCode program on the following record: FUNCLIB_LDAP.LDAPAUTH (FieldDefault). You can customize it as needed for testing or production use.

Open the record in PeopleSoft Application Designer, and view the PeopleCode with the PeopleCode Editor. The delivered PeopleCode accommodates as many different directory scenarios as possible; it demonstrates use of the business interlink and component interface technologies. You may want to modify the authentication PeopleCode to improve login performance or to accommodate any special directory authentication needs. The delivered program that ships with PeopleTools has the following general flow:

  1. Searches the directory server for the user profile of the user signing in.

  2. Using the password the user entered at the signon page, the program attempts to bind (or connect) to the directory server.

    If the connect succeeds, then the password is valid.

  3. Retrieves the user profile of the user signing in.

    The program gets the profile from the directory server and creates a local cache copy within the PeopleSoft database. This improves performance by enabling the PeopleSoft applications to access the user profile locally, rather than making a call to the LDAP server every time they need user profile data. If a locally cached copy already exists for the user signing in, the local cache is updated according to the current user in the directory server.

Note: To see what the Signon PeopleCode program does, use the PeopleCode debugger. This enables you to step through the program step-by-step.

The following table presents the key PeopleCode constructs that you use with Signon PeopleCode. Click the function to view more details in the PeopleCode product documentation:

PeopleCode Function

Description

See %PSAuthResult.

Returns the result (boolean) of PeopleSoft authentication.

See SetAuthenticationResult.

Verifies customers who log on to the system even if the PeopleSoft authentication fails.

See %SignonUserId.

User ID value entered by the user on the Signon page. This applies to Pure Internet Architecture and Windows signon.

See %SignOnUserPswd.

User password value the user entered at the Signon page. This value is encrypted. This applies to Pure Internet Architecture and Windows signon.

See %Request.

The HTML request that comes from the browser. In the case of security, this includes any information submitted at the Signon page, such as user ID, password, and any additional fields if you have extended the Signon page. This applies only to Pure Internet Architecture.

Note: Do not use the %SwitchUser variable in Signon PeopleCode.

Access the Signon PeopleCode page (PeopleTools > Security > Security Objects > Signon PeopleCode).

Image: Signon PeopleCode page

This example illustrates the fields and controls on the Signon PeopleCode page.

Signon PeopleCode page

Signon PeopleCode is different from other PeopleCode in that you specify which Signon PeopleCode you want to have on a specific Signon PeopleCode page. Notice that the PeopleSoft Password Controls program, which is written in PeopleCode, is also on this page.

By default, some of the Signon PeopleCode programs are disabled. You enable them on this page. You can also enable them by enabling password controls on the Password Controls page or by enabling directory authentication on the Directory Authentication component. After enabling each option on the appropriate page, the system enables the associated PeopleCode program on the Signon PeopleCode page.

Note: Using PeopleSoft password controls is valid only if you are not using LDAP authentication. When you're using LDAP authentication, the directory server, not PeopleSoft, controls the password.

You can add your own PeopleCode programs, but you must add them to another record, and then add them to this page. You add and remove rows from the grid using the plus and minus buttons.

Field or Control

Definition
Invoke as user signing in/ Invoke as…

When a PeopleCode program runs, it has to have a context of a user. This is how you indicate to the system which user is executing the program. This is important because the user ID provided must have access to all of the objects that your signon program uses. For example, if you are using LDAP, notice that the Signon PeopleCode contains a business interlink and a component interface. If the user ID provided does not have the appropriate authority to business interlinks or component interfaces, the program fails. Whether you use the value of the user signing in or you create a default user ID for all signon attempts depends on your implementation. For example, if your Signon PeopleCode creates local copies of users, you have to configure that program to be “Invoked as” an existing user in the system. In this case, you should create a new user within PeopleSoft that only has authority to access the objects required within your PeopleCode program. You should then enter this user as the “Invoke As” user.
Sequence

Displays the sequence in which the signon programs run. You can change the sequence by changing the numerical value in the edit box. The application server runs all programs in the ascending order in which they appear.
Enabled

To enable a program to run at signon, select this check box. If it is not selected, then the system ignores the program at signon.
Record

Specify the record on which your record PeopleCode exists.
Field Name

Enter the specific field that contains the PeopleCode.
Event

Enter the event that triggers a particular program.
Function Name

Enter the name of the function to be called.
Exec Auth Fail (execute authentication fails)

Select this check box to "execute if PeopleSoft authentication fails." In other words, if PeopleSoft does not successfully authenticate the user based on the password within the PeopleSoft database, you still want the program to run. For example, you want the LDAP authentication program to run after PeopleSoft denies access so that your program can authenticate the user instead. Also, you can leave this option clear to further secure your system. If you aren't using LDAP authentication, leaving this option unchecked prevents any program or script from running if your PeopleSoft authorization fails.

X.509 certificates are used to authenticate a user at the web server level—SSL/TLS with client-side authentication. You can use PeopleCode to access X.509 certificates.

When you use certificate authentication with PeopleSoft, users do not see the PeopleSoft signon page and enter a user ID. Because of this, the X.509 certificate needs to be available in the Signon PeopleCode so you can write PeopleCode that maps the certificate to a PeopleSoft user ID.

The following sample PeopleCode shows how you access X.509 certificates in Signon PeopleCode:

Local string &clientDN;
&clientDN = %Request.GetParameter("com.peoplesoft.tools.ssl_client_dn");

The value of &clientDN might be similar to the following:

E=tom_sawyer@peoplesoft.com, C=US, S=California, L=Pleasanton, O=PeopleSoft, OU=PeopleTools, CN=Tom Sawyer