Employing LDAP Directory Services

This chapter provides an overview of the PeopleSoft Lightweight Directory Access Protocol (LDAP) solution and discusses how to:

• Configure the LDAP directory.

• Cache the directory schema.

• Create authentication maps.

• Create user profile maps.

• Create role membership rules.

• Delete directory configurations.

• Enable signon PeopleCode for LDAP authentication.

• Use LDAP over SSL (LDAPS).

• Set up SSL on the directory (examples).

Note. This chapter assumes you have a working knowledge of LDAP-enabled directory servers.

Understanding the PeopleSoft LDAP Solution

PeopleSoft delivers three technologies that enable you to:

• Authenticate against an LDAP V3 compliant directory server.

• Reuse your existing user profiles stored within LDAP.

The three technologies are:

• Directory Business Interlink, which exposes the LDAP to PeopleCode.

  The system uses it for all communication with the LDAP server process running on a directory server.

• User Profile Component Interface, which exposes the User Profiles component to PeopleCode.

  The system uses it to programmatically manage a local cache of user profiles.

• Signon PeopleCode, which runs when a user signs on to the system—similar to the login scripting of most network systems.

  Signon PeopleCode uses the Directory Business Interlink and the User Profile Component Interface to verify directory-based credentials and programmatically create a local User Profiles cache.

The combination of these three technologies provides a flexible way to configure PeopleSoft for integration with your directory server. No set schema is required in the directory. Instead, you can configure and extend the Signon PeopleCode to work with any schema implemented in your directory server.

The topics in this chapter describe setting up the LDAP integration technology on your site. The tasks assume that there is already an LDAP V3 compliant directory service installed, and that you are intending to import LDAP group values and apply them to PeopleSoft roles.

Note. When you enable LDAP authentication, the password column on the PSOPRDEFN record is no longer used. Also, LDAP authentication requires an application server — it doesn't work with two-tier signon.

Configuring the LDAP Directory

This section provides an overview of LDAP directory configuration and discusses how to:

• Specify network information for LDAP.

• Specify additional connect DNs.

• Install selected PeopleSoft-specific schema extensions.

• Test the connectivity.

Understanding LDAP Directory Configuration

The Configure Directory component (PSDSSETUP) contains four pages that you use for specifying connection information and testing directory server connections.

To enable your PeopleSoft system to successfully connect to your directory server, you must enter the appropriate connection information. This includes the server name (DNS or IP address) and the listening port number. You also must enter the user distinguished name (User DN) and associated password.

The PeopleSoft application server uses the User DN and password to connect to the LDAP server to retrieve user profile information about the specific user signing in to the system. The User DN must reflect a user with the appropriate LDAP browse rights.

Pages Used to Configure the Directory

Specifying Network Information for LDAP

Access the Configure Directory - Directory Setup page.

Directory ID	Identifies the directory connection that you are creating. The directory ID that you enter can identify a specific LDAP server or a collection of LDAP servers depending on how many servers you add in the Server Name section.
Description	Enter a description of the directory connection.
Directory Product	Select your directory product from the list of options.
Default Connect DN (default connect distinguished name)	Displays the default connect DN associated with the directory ID that you entered or selected on the initial search page. The connect DN is the ID that you can use to connect to the directory server. You can enter an alternative connect DN.
Password	Enter the password associated with the directory-based account that appears in the Default Connect DN field. Note. The password is stored in encrypted form in the database; not even individuals with administration access to the database can view the password.
Server Name	Add LDAP directory servers to a connection list. You can add multiple servers for failover purposes using the plus button. All servers you add must participate in the same directory service.
LDAP Server	Identify a specific LDAP server. You can use the DNS name or you can use IP address dotted notation. For example, either of the following formats is acceptable: ldap12.yourcompany.com or 192.201.185.90.
Port	Enter the port number on which the LDAP server is configured to receive search requests. The standard LDAP port is 389. If you do not specify the correct port, PeopleSoft Directory Interface can't exchange data with your LDAP server.
SSL Port	If you are implementing SSL, enter the SSL port on the LDAP server.

Specifying Additional Connect DNs

Access the Configure Directory - Additional Connect DN’s page.

The PeopleSoft application server uses the User DN and password specified on this page to connect to the LDAP server to retrieve user profile information about the specific user signing in to the system. The User DN must reflect a user with the appropriate LDAP browse rights.

Note. You will not see any available schema extensions unless you have installed the PeopleSoft Directory Interface.

Installing Selected PeopleSoft-Specific Schema Extensions

Access the Configure Directory - Schema Management page.

Note. Unless you have installed the PeopleSoft Directory Interface product, you might not have any PeopleSoft schema extensions available to you.

Details

When you click a schema extension’s Details button, the system displays the details of that extension. In addition to the object identifier and name, you may also be interested in the Superiors detail, which indicates which extensions are above this one on the hierarchy, if any. Also of interest is the Type detail, which indicates whether the schema extension is a mandatory, optional, or auxiliary extension.

Schema Cache Information

For convenience, you can use the Schema Cache Process link to transfer you to the Schema Cache page so that you can invoke the Schema Cache process. Last Update Date/Time and Last Update User ID enable you to monitor the frequency of updates as well as the last administrator to run the process.

Testing the Connectivity

Access the Configure Directory - Test Connectivity page.

The page displays the results (PASS or FAIL) of the connectivity test. If connectivity fails, modify the connect information on the Directory Setup and Additional Connect DN’s pages.

Caching the Directory Schema

You use the Cache Schema page to specify a directory server and invoke an Application Engine program designed to create a cache in the PeopleSoft database of the directory schema. This enables you to select names of object classes and attribute types when creating security maps.

This section discusses how to create a cache of the directory schema.

Page Used to Cache the Directory Schema

Creating a Cache of the Directory Schema

Access the Cache Schema page.

Directory ID	Select the directory ID to identify the directory that the system should connect to and retrieve schema information from.
Server Name	Search for the Process Scheduler server on which the Cache Schema process should run.
Cache Schema Now	Click this button to cache the LDAP schema data to tables within the PeopleSoft database. Typically, you use this option during initial setup and any time that the schema has changed.
Process Monitor	After invoking the process, you can monitor the progress by clicking this link.

Creating Authentication Maps

Use the Authentication page only if you're implementing directory authentication as opposed to storing authentication information in the PeopleSoft database. You create authentication maps to define mappings to one or more directories that the PeopleSoft system relies on for authenticating users. You can activate multiple authentication maps. Your PeopleSoft LDAP system authenticates users against all active authentication maps.

This section discusses how to define an authentication map.

Page Used to CreateAuthentication Maps

Defining an Authentication Map

Access the Authentication page.

Status

Activate the authentication map by selecting Active. To disable an authentication map, select Inactive.

Directory Information

List of Servers

User Search Information

Creating User Profile Maps

This section provides an overview of user profile options and discusses how to:

• Specify mandatory user properties.

• Specify optional user properties.

Understanding User Profile Options

If you are going to authenticate users with the directory server, a PeopleSoft User Profile is still required. That is, a row is still required in the table in which PeopleSoft user information is stored (PSOPRDEFN). In this context, you cache LDAP user information inside your PeopleSoft system. The properties that you specify on the Mandatory and Optional User Properties pages are the columns in PSOPRDEFN that the system populates with values from your directory server. These values comprise your user profile options.

PeopleSoft applications use this cache of user information, not your directory server. Whenever a transaction requires user information, the application refers to the local PSOPRDEFN table as opposed to querying the directory server. This improves performance.

After a user signs onto the system and the Signon PeopleCode is carried out, PeopleSoft creates a row for that user in the user definition table by retrieving the LDAP information and creating a local cache. Signon PeopleCode maintains this row automatically; there is no need for any manual updates. Any changes made in the directory server are reproduced in the local cache.

Some properties are required when creating a PeopleSoft User Profile; these properties appear on the Mandatory User Properties page. Other properties are optional, and these appear on the Optional User Properties page.

Note. You must supply user properties to Signon PeopleCode only if you intend to authenticate users with your LDAP directory.

Pages Used to Create User Profile Maps

Specifying Mandatory User Properties

Access the Mandatory User Properties page.

Authentication Map	Select the authentication map to associate with this user profile mapping. The server and connection information are taken from the authentication map.
Status	Displays the status of the selected user profile map. Note. Only one user profile map should be active at any time.
Directory ID	Displays the directory ID associated with the authentication mapping.
User ID Attribute	Specify the LDAP attribute that's used to populate the OPRID (user ID) field on PSOPRDEFN. Important! If you specify a different value here than the Search Attribute value that you specified on the Authentication page, users won't be able to switch to another application from the Go menu in PeopleSoft Windows clients such as Application Designer. The second application expects to automatically authenticate a user with the value of %SignonUserId, the system variable that contains the user ID that was used to sign in. However, because the value of OPRID is different from the value of %SignonUserId, the authentication fails with an error message. Users can still access any PeopleSoft Windows client by launching it directly and signing in using the same Search Attribute value for the user ID.

ID Type

Default Role

You can enable your application to automatically apply a role for the user. When signing in to the application, the user provides a value for the search attribute you specified in the authentication map. The system uses that attribute value to search for the user's entry in the LDAP directory, then imports the group containing the entry to the PSOPRDEFN table as the user's role.

To enable this automatic role import feature:

1. Define LDAP groups with names that exactly match the roles defined for your application.

2. Clear the Use Default Role check box on this page.

3. Leave the Role Name and Role Attribute fields on this page blank.

Language

Specifying Optional User Properties

Access the Optional User Properties page.

The following are optional user properties that you can select from the User Profile Property search button.

Creating Role Membership Rules

Use the Role Policy page to define the rules that are read by Dynamic Role Rule PeopleCode and populate PeopleSoft roles with members. The rules return the DNs of "people" directory entries, which supply the system with the user IDs specified on the user profile mapping.

This section provides an overview of role membership rules and discusses how to define role membership rules.

Understanding Role Membership Rules

PeopleSoft security roles are comparable to LDAP directory groups. Roles enable you to group user IDs in logical sets that share the same security privileges. PeopleSoft enables you to keep your external directory groups synchronized with the data stored within the PeopleSoft database.

It is important to keep the data within PeopleSoft consistent with any changes made to the structure or content of the external directory server. This is especially crucial when dealing with security data. The Role Membership Rules page enables you to modify a PeopleSoft role based on directory criteria.

Page Used to Create Role Membership Rules

Defining Role Membership Rules

Access the Role Policy page.

Rule Name	Displays the directory search name that you entered on the search page.
Description	Enter a short description of the rule.
User Profile Map	Select the user profile map to associate with the rule.
Directory ID	Displays the directory associated with the user profile map that you select.
Assign to Role	Click this link to automatically start the Dynamic Members page in the Roles component of the Security menu. On that page, select Directory Rule Enabled and specify the server on which to carry out the rule.

Directory Search Parameters

Build Filter

Search Attributes

Note. You can also write PeopleCode to determine group membership using any arbitrary LDAP search criteria.

Deleting Directory Configurations

You can delete the entire directory configuration or just parts of it.

This section discusses how to:

• Delete the directory configuration.

• Work with the workflow address book.

Page Used to Delete Directory Configurations

Deleting the Directory Configuration

Access the Delete Directory page.

Delete Associated Maps	Deletes the authentication and user profile maps from the configuration.
Delete Associated Searches	Deletes any searches related to the directory configuration.
Delete Associated Role Rules	Deletes any role rules that you have specified for a configuration.
Delete Associated Entry Rules	This applies to the PeopleSoft Directory Interface product only.
Delete Directory Configuration	After you have made the appropriate choices, click this button to perform the delete process. If you click this button with nothing selected, the system deletes only the directory ID and leaves all of the other configuration information intact.

Working with the Workflow Address Book

Select PeopleTools, Security, Directory, Workflow Address Book to access the Address Book page.

Use the Address Book page for configuring LDAP address lookups for use with user-initiated notifications in PeopleSoft Workflow. This page contains the controls needed to retrieve the necessary addresses from the directory. This page applies only if you store user information in a directory.

Note. Each of these controls is discussed elsewhere in this chapter.

See Also

Adding Events and Routings

Enabling Signon PeopleCode for LDAP Authentication

LDAP Authentication runs as Signon PeopleCode that must be enabled and configured to be carried out with proper permissions.

To enable Signon PeopleCode:

1. Select PeopleTools, Security, Security Objects, Signon PeopleCode to access the Signon PeopleCode page.

2. Click the Invoke As option that applies to your configuration.

   Do you want to use a default user ID, or do you want the Signon PeopleCode to be invoked by the user ID of the user who happens to be signing on to the system? Either way, the value for the user ID and password must be a valid PeopleSoft User ID and password. For LDAP authentication, you need to use Invoke As, because the user signing in (most likely) won’t exist in the local system, until Signon PeopleCode runs and updates the local cache of user profiles.

   Note. The user ID entered—whether it is Invoke as user signing in or a default user—must be able to access the User Profiles component in a permission list.

3. Locate the row for the LDAP_Authentication function on the Record FUNCLIB_LDAP.

4. Select the Enabled check box (if it is not already selected automatically by the system).

5. Ensure that the Exec Auth Fail check box is selected; if PeopleSoft authorization fails, then Signon PeopleCode is carried out.

   PeopleSoft authorization always fails if you are using LDAP authentication.

6. Click Save at the bottom of the page.

7. Reboot any application servers running against the local database.

Note. If you intend to use the User Profile Map, you also need to enable LDAP_PROFILESYNCH. The same options apply.

Using LDAP Over SSL (LDAPS)

You can use the LDAP Business Interlink to establish a secure LDAP connection between the application server and the LDAP server. The LDAP Business Interlink uses Netscape’s certificate database, cert7.db. You can obtain a cert7.db using the PKCS Utilities distributed by Netscape. Refer to Netscape’s documentation for more information on obtaining and using the PKCS Utilities.

To establish the secure connection between the PeopleSoft Application Server and the LDAP server you will need the following:

• Cert7.db certificate database from Netscape.

• A Server Certificate for the LDAP server.

• The Trusted Root Certificate from the Certificate Authority (CA) that issues the Server Certificate.

To enable LDAP authentication over SSL:

1. Follow the documentation for your directory server to add the Server Certificate to your directory server.

2. Using Netscape’s PKCS Utilities, add the Certificate Authorities Trusted Root Certificate to the cert7.db certificate database.

3. Place the cert7.db file in the %PeopleTools%\bin\server directory of the application server.

4. Select PeopleTools, Security, Directory, Configure Directory, Directory Setup to access the Directory Setup page, and make sure that the SSL Port field reflects the correct LDAPS port for your directory server.

5. Select PeopleTools, Security, Directory, Authentication Map to access the Authentication Map page, and select the Use Secure Sockets Layer check box.

6. In Application Designer, open the following Business Interlinks, select the Settings tab, and change the SSL setting to YES:

   • LDAP_SEARCH

   • LDAP_BIND

Setting Up SSL on the Directory (Examples)

If you require SSL between your LDAP directory server and your PeopleSoft system, the following topics provide sample procedures for doing so.

This section provides an overview of SSL and the directory and discusses how to:

• Set up SSL for Novell NDS.

• Set up SSL for Netscape (iPlanet).

Note. The procedures outlined in this section are provided as samples. They may not necessarily apply to all situations.

Understanding SSL and the Directory

SSL is a protocol developed by Netscape that defines an interface for data encryption between network nodes. To establish an SSL-encrypted connection, the nodes must complete the SSL handshake. The simplified steps of the SSL handshake are as follows:

1. Client sends a request to connect.

2. Server responds to the connect request and sends a signed certificate.

3. Client verifies that the certificate signer is in its acceptable certificate authority (CA) list.

4. Client generates a session key to be used for encryption and sends it to the server encrypted with the server's public key (from the certificate received in step 2).

5. Server uses its private key to decrypt the client generated session key.

Establishing an SSL connection requires two certificates: one containing the public key of the server (server certificate or public key certificate) and another to verify the CA that issued the server certificate (Trusted Root certificate). The server needs to be configured to issue the server certificate when a client requests an SSL connection and the client needs to be configured with the Trusted Root certificate of the CA that issued the server certificate.

The nature of those configurations depends on both the protocol being used and the client and server platforms. In most cases you replace HTTP with LDAP. SSL is a lower level protocol than the application protocol, such as HTTP or LDAP. SSL works the same regardless of the application protocol.

Note. Establishing SSL connections with LDAP (LDAPS) is not related to web server certificates or certificates used with PeopleSoft integration.

Setting Up SSL for Novell NDS

This section discusses how to configure the LDAP business interlink to establish SSL encrypted LDAP connections. The LDAP business interlink uses a certificate database that resides on the file system of the PeopleSoft Application Server. The certificate database is a file called cert7.db and needs to reside in the file system of the application server. The cert7.db certificate database needs to contain the Trusted Root certificate of the CA that issued the Server Certificate of the LDAP server.

Setting Up the Certificate

To obtain a cert7.db, you must download Netscape Navigator 4.7, install it, and launch Netscape Navigator. Create a user profile with the name of PeopleSoft, and verify that the following directory structure exists: Netscape\Users\PeopleSoft.

To import the certificate:

1. In the PeopleSoft directory, find cert7.db.

2. With Netscape Navigator open, click the Security button at the top.

   The Security Information page appears.

3. Select Certificates and Signers.

   The system displays the valid certificates in the database.

4. Delete all of the certificates, click OK, and close Netscape Navigator.

5. Import the CA’s certificate into the cert7.db certificate database.

You are ready to configure the LDAP business interlink for SSL. There are two relevant settings on all transactions of the business interlink:

• SSL setting.

• SSL_DB location setting.

As with all business interlink inputs, these can be set using either Application Designer or PeopleCode.

To make the settings using Application Designer:

1. Open an existing instance of the LDAP business interlink, or create a new instance.

2. Select the Settings tab.

3. Set the SSL parameter to YES.

4. Set the SSL_DB parameter to the name of your certificate database (cert7.db by default).

5. Save the business interlink.

To make the settings using PeopleCode, drag the business interlink definition into the PeopleCode editor. The following code is created:

/* ===>
   This is a dynamically generated PeopleCode template to be used only as a helper
to the application developer.
You need to replace all references to '<*>' OR default values with  references to
PeopleCode variables and/or a Rec.Fields.*/

/* ===> Declare and instantiate: */
Local Interlink &LDAP_SEARCH_1;
Local BIDocs &inDoc;
Local BIDocs &outDoc;
Local boolean &RSLT;
Local number  &EXECRSLT;
&LDAP_SEARCH_1 =  GetInterlink(INTERLINK.LDAP_SEARCH);

/* ===> You can use the following assignments to set the configuration parameters.
*/

&LDAP_SEARCH_1.SSL = "NO";
&LDAP_SEARCH_1.SSL_DB = "cert7.db";
&LDAP_SEARCH_1.URL = "file://psio_dir.dll";
&LDAP_SEARCH_1.BIDocValidating = "Off";
…..

Note. This example uses the Search transaction, but the same principle applies to any transaction.

You must change the .SSL and .SSL_DB settings to indicate that SSL should be used, and specify the name of your certificate database file. For example:

&LDAP_SEARCH_1.SSL = "YES";
&LDAP_SEARCH_1.SSL_DB = "cert7.db";

Configuring Your LDAP Server for SSL

This section describes how to configure NDS eDirectory V8.5 for LDAPS using the Organizational CA built into NDS’s PKI services.

To configure NDS eDirectory V8.5 for LDAPS:

1. Export the Self Signed Trusted Root Certificate from the CA.

   1. Start Console1 and navigate to the Organizational CA object in the Security container:

   2. Open the Properties dialog, go to the Certificates tab, and choose Self Signed Certificate from the menu.

   3. Click the Export button.

   4. In the Export a Certificate dialog box, choose binary DER format, designate a file name and location, and click Export.

   5. Rename this file using an .X509 file format.

2. Create a Server Certificate to be used by LDAP.

   1. In Console1, navigate to the container that holds the Server Object for the LDAP Server:

   2. Right-click the container entry (such as Config), and select NewObject. Scroll down and find NDSPKI:Key Material in the list, and click OK.

   3. In the Create Server Certificate dialog box, make sure that the server name is the name of the directory server running the LDAP service.

      Also, give the new certificate a meaningful name, select the Standard creation method, and click Next:

   4. Review the information in the next dialog box, and click Finish.

      You should now have a certificate that contains the public key for the server running the LDAP service stored in your directory as an object:

3. Indicate to the LDAP service which port to use for SSL connections and to issue the certificate when a client requests a connection on that port.

   1. Find the object representing your LDAP Server; it's in the same container where you just created the certificate, and it's named LDAP Server-hostname-NDS.

   2. Open the properties dialog box on the LDAP Server object, and select the SSL Configuration tab.

   3. Enter the port number that you want to use for LDAPS, and in the SSL Certificate field, click the browse button to select the certificate that you just created.

      Do not check Enable and Require Mutual Authentication unless you have configured this option (which is outside the scope of this discussion).

      Note. Under your Novell Install Directory there should be a file called X509.REG. The path should be similar to install_directory\CERTSERV\MISC\X509.REG. Take this file and move it to the machine on which you've installed Netscape. From the machine that uses Netscape, run the X509.REG file by double-clicking it. This updates your registry so that Netscape can import the certificate.

4. Import the certificate.

   1. Launch Netscape, select File, Open, and enter the file location of the .X509 certificate that you exported from NDS.

   2. Netscape will take you through the certificate import process.

      Complete the steps in the wizard.

   3. To confirm proper installation, click the security tab (the lock), open the security administrator for Netscape, and click the Certificates Signers link, which takes you to all valid certificates in the database.

      You should now see the certificate that you imported.

5. Move the cert7.db to the appserv folder.

   The system should now be running LDAPS with NDS.

   Note. You are responsible for receiving certificates from a CA, such as Entrust.Net or Verisign.

Note. If you try to test this with the business interlink tester, the error code 89 is often reported. This does not mean that LDAPS is not working. To test, you can run a trace on the directory to see the SSL handshake occurring. You can also turn off port 389 and see if authentication still works. If it does, then this indicates that SSL is working.

Setting Up SSL for Netscape (iPlanet)

To set up SSL on Netscape:

1. Make sure that your directory is defined in the PeopleTools, Security, Directory component.

2. Modify the Signon PeopleCode page:

   1. Select PeopleTools, Security, Security Objects, Signon PeopleCode to access the Signon PeopleCode page.

   2. Select the Invoke as radio button.

   3. Enter the user ID and password of a user who has permission to run the Signon PeopleCode.

      The password will not be visible once the page is saved.

   4. Select the Enabled box to enable the Signon PeopleCode.

   5. Enter the Signon PeopleCode location as shown in the default values.

   6. Select the Exec Auth Fail box, because Signon PeopleCode is triggered when authentication fails against the PeopleSoft authentication.

   7. Save the page.

      Note. Make sure that the user ID entered above has permission to run the Component Interface USER_PROFILE.

3. Modify the LDAP_BIND and LDAP_SEARCH business interlink definitions:

   1. Open Application Designer.

   2. Open the LDAP_BIND definition.

   3. Select the Input tab.

   4. Enter the server name and port for the LDAP server.

      The other parameters are not required for this procedure.

   5. Select the Settings tab.

   6. Select YES from the SSL drop-down list box.

   7. In the SSL_DB edit box, enter the location of the certificate database; for example, c:\peoplesoft\certificates.

      Note. This field should contain just the directory location, not the database filename.

   8. Click Set Default to save the default settings.

   9. Save and close the definition.

4. Consider the following items:

   1. The application server binds as a client to the LDAP server as part of the authentication, so it is only necessary to have access to the Root Certificates.

      The LDAP administrator at your site should have already installed a server (Node) Certificate on the LDAP Server.

   2. The cert7.db file can be transferred to the application server in binary mode and installed in the same directory as PSAPPSERV.CFG and PSTUXCFG of the application server domain.

   3. Using a copy of the LDAP server’s cert7.db is not a security risk, as the Node Certificates are encrypted strings based on the host name and other site-specific parameters.

      The application server accesses the Root Certificates, which are generally available at no charge from the CA.

5. Reboot the application server domain.