Configuring WS-Security For WSRP Consumption and Production

This chapter provides overviews of determining security requirements and WS-Security, and discusses how to:

Set up WSRP security options.
Configure WS-Security For WSRP Producers.
Configuring WS-Security For WSRP Consumers.

Important! The procedures for configuring WSRP consumption and production must be performed in the order set out in this chapter.

Determining Security Requirements

Before implementing WSRP, it is important that you first determine the level of security you require. If you are consuming remote portlets, the level you select must be the same as the producer. If you are producing portlets, consider whether you need to secure only the transmission channel, or the transmission channel and the messages. You should also consider how security will affect the performance of your servers.

There are three types of token security options for WS-Security (set in the server-config.wsdd file):

None. No security token required.
Authentication Token as Username Token. The Username Token is in clear text format.

Important! If you require a secure channel between the producer and consumer, the .HTTPS protocol must be used.
Authentication Token as Username Token with full security. Username Token is encrypted and messages are digitally signed.

Note. For this option, either HTTP or HTTPS protocol can be used to communicate between the producer and consumer.
Username token with no password and digital signature.

Important! The security option used by the producer must be an exact match to the security option used by the consumer.

Understanding the PeopleSoft WS-Security for WSRP

WSRP involves passing of SOAP messages between the WSRP consumer and producer. To safely utilize WSRP, PeopleSoft provides message-level security between the consumer and the producer by incorporating WS-Security.

WS-Security is an extension to the concept of the SOAP envelope header that enables applications to construct secure SOAP message exchanges. It also provides a means for associating security tokens with messages. The WS-Security support provided by PeopleSoft is limited to the Username Token Profile. With Username Token support, a consumer can supply a UsernameToken as a means of identifying the requestor by username, and optionally using a password to authenticate that identity to the web service provider.

WS-Security provides three main mechanisms:

Single sign-on solution between the WSRP consumer and producer: The consumer passes their identification to the producer as part of the SOAP message so that the producer can verify the identity and produce WSRP content without requiring the user to log in.
Message integrity: Ensures that messages have not been tampered with.
Message confidentiality: Guarantees that messages are protected.

This figure shows how WS-Security inserts and conveys security tokens in SOAP messages:

WS-Security SOAP Message Structure

When the PeopleSoft portal is a WSRP consumer, the user ID and password of the user signed into the portal is placed into a Username Token in the SOAP header, and the WSRP portlet consumes it. It is presented to each portlet during the initial markup request. The security handler performs WS-Security token generation, digital signature generation, and token encryption, before the PeopleSoft system sends the SOAP request message and the WS-Security SOAP header.

Important! The PeopleSoft portal authentication information (both the user ID and password), must be the same as the producer's.

When PeopleSoft is the producing system, the consuming system sends PeopleSoft the SOAP request message and the WS-Security SOAP header. The portal accepts the Username Token in the WS-Security header from the remote portal, assuming that the ID and password are acceptable to PeopleSoft. The receiver security handler decrypts the SOAP header, validates the digital signature, verifies the WS-Security token, and generates a PS_TOKEN cookie, the PeopleSoft authentication token.

This diagram shows PeopleSoft as both WSRP consumer and WSRP producer.

PeopleSoft Portal as WSRP Consumer and Producer

Setting Up WSRP Security Options

This section discusses how to:

Use HTTPS protocol to communicate between producer and consumer.
Install certificates for encryption and signature.
Set up security options for WSRP producers.
Set up security options for WSRP consumers.

Using HTTPS Protocol to Communicate Between Producer and Consumer

If you choose the security option “Authentication token as Username token in clear text format”, it is recommended to use HTTPS to protect the username and password. To use HTTPS protocol both the producer and consumer must first configure and enable SSL for HTTPS on their web servers.

Before the consumer imports the producer \pspc\wsdl\wsrp4j_service.wsdl, the producer must modify the file by setting it to HTTPS mode and changing the port number from the HTTP port number to the HTTPS port.

Note. The system automatically inserts the hostname and port number using the values entered during installation.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions targetNamespace="urn:oasis:names:tc:wsrp:v1:wsdl"
       xmlns:bind="urn:oasis:names:tc:wsrp:v1:bind"
       xmlns="http://schemas.xmlsoap.org/wsdl/"
       xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
       xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">

 <import namespace="urn:oasis:names:tc:wsrp:v1:bind"
       	  location="wsrp_v1_bindings.wsdl"/>

  	<wsdl:service name="WSRPService">
    		<wsdl:port binding="bind:WSRP_v1_Markup_Binding_SOAP" name="WSRPBaseService">
      		<soap:address location="https://<Producer Hostname>:<SSL port>/pspc/wsrp4j/WSRPBaseService"/>
    		</wsdl:port>
    		<wsdl:port binding="bind:WSRP_v1_ServiceDescription_Binding_SOAP" name="WSRPServiceDescriptionService">
    	<soap:address location="https://<Producer Hostname>:<SSL port>/pspc/wsrp4j/WSRPServiceDescriptionService"/>
    		</wsdl:port>
    		 	</wsdl:service>
       </wsdl:definitions>

Note. Where <Producer Hostname> is the hostname of the Producer web server, <SSL port> is the SSL port number of the Producer web server.

If you are using an SSL accelerator in your PeopleSoft system, and you want to use the HTTPS protocol for WSRP to communicate with PeopleSoft Pure Internet Architecture, you need to use the following properties file:

<PS_HOME>\webserv\peoplesoft\applications\peoplesoft\pspc\WEB-INF\config\services\PIAService.properties.

Note. This is similar to using Web Profile's Default Addressing fields.

See Configuring Web Profiles.

In this properties file, specify the default protocol, host, and port to override the incoming request protocol, host and port. The settings WSRP checks in the PIAService.properties file are:

usePIAConfig = true	Flag to check if settings in the PIAService.properties file should be used or not. If you set usePIAConfig to be true, the incoming request is overriden by values set in PIAService.properties. Otherwise, the system uses the incoming request values for protocol (scheme), host, and port.
portalHost=<your webserver host>	The default host to use instead.
portalPort=<your port>	The default port to use instead.
SSLToPIA=true	If you set SSLToPIA to be true, the system will use HTTPS, otherwise it will use the HTTP scheme.

Installing Certificates For Encryption and Signature

When the security option Authentication token as Username token with full security is selected, both the producer and the consumer must install the certificates that are used to enable the encryption and signature.

This diagram illustrates the process flow for installing certificates and enabling encryption and signature.

Process for installing certificates and enabling encryption and signature

First use the following reference for instructions on how to create and request your encryption and signature certificates.

See Implementing Secure Sockets Layer (SSL) on OAS 10g, Implementing WebLogic SSL Keys and Certificates.

Enabling Encryption

Producer:

The encryption key and certificate are created on the producer and stored in the web server predefined keystore.

Note. Make sure when you create the entry to hold your encryption keys and certificate in your keystore, the entry's alias name must be the security node name of your Producer server.

Send the encryption certificate to the consumer. This can be done using an out-of-band method, such as file copy or email.

Consumer:

Install the encryption certificate on the Consumer server by runningpskeymanager.cmd -import.

Note. Make sure when you import the certificate, the entry's alias name must be the security node name of your Producer server.

Enabling Message Signature

Consumer:

Create the signature key and certificate on the consumer and store in the web server predefined keystore.

Note. Make sure when you create the entry to hold your signature keys and certificate in your keystore, the entry's alias name must be the security node name of your Consumer server.

Send the signature certificate to the producer. This can be done using an out-of-band method, such as file copy or email.

Producer:

Install the signature certificate on the Producer server by running pskeymanager.cmd -import.

Note. Make sure when you import the certificate, the entry's alias name must be the security node name of your Producer server.

Encrypting Keystore Password Using PSCipher

A copy of the wss.properties file, which contains PKI java keystore information, such as keystore file location and password for the keystore can be found on both the Consumer and Producer servers.

The location of the wss.properties file on the Consumer web server is:

...\PORTAL\WEB-INF\classes

The location of the wss.properties file on the Producer web server is:

....\pspc\WEB-INF\classes

The following is the sample wss.properties file:

org.apache.ws.security.crypto.provider=
org.apache.ws.security.components.crypto.Merlin org.apache.ws.security.crypto.merlin.keystore.type=jks org.apache.ws.security.crypto.merlin.keystore.password=UWZzB57U6SE= org.apache.ws.security.crypto.merlin.file=keystore/pskey

To define the location of the keystore file, the Portal Administrator needs to define the proper keystore file to replace above org.apache.ws.security.crypto.merlin.file property.

To encrypt the keystore password using Java program PSCipher:

Run PSCipher.bat (.sh for UNIX) to encrypt the password.

% PSCipher.bat <password>

For example, PSCipher interop provides output as UWZzB57U6SE=
Write down the output of PSCipher and then update the encrypted password in the wss.properties file for org.apache.ws.security.crypto.merlin.keystore.password

See Encrypting Text With PSCipher.

Configuring WS-Security For PeopleSoft as a WSRP Producer

The ...peoplesoft\pspc\WEB-INF\ directory on the producer web server contains a server-config.wsdd file, which contains the WSRPBaseService definition plus the following variations. Each one of the variations is associated with a security option:

Security Option	server-config.wsdd setting
1. None	server-config.wsdd.none
2. Authentication Token as Username Token	server-config.wsdd.usernametoken
3. Authentication Token as Username Token with full security	server-config.wsdd.fullsecurity
4. Username Token with no password and digital signature.	server-config.wsdd.untnp

PeopleSoft provides two options for modifying the security constraint on the WSRPBaseService. Which option you should use depends on whether your web server is currently running. If your web server is running, you can modify WSRPBaseService without rebooting the server.

Note. The %PS_HOME%\webserv\%DOMAIN_NAME%\ directory contains the redeployWSRP batch file.

Modifying WSRPBaseService Without Rebooting

To modify WSRPBaseService without having to reboot the web server:

Using the Command Prompt, change to the directory containing the redeployWSRP file:

cd %PS_HOME%\webserv\%DOMAIN_NAME%\
Enter the command: redeployWS <option #>

For example:

redeployWSRP 2

This will redeploy WSRPBaseService using UsernameToken in clear text security option. The web service gets undeployed and redeployed dynamically without having to reboot the web server.

Modifying WSRPBaseService and Rebooting

To modify WSRPBaseService if the web server is not up and running:

Using the Command Prompt, change to the ...\peoplesoft\pspc\WEB-INF directory:

For example:

cd %PS_HOME%\webserv\%DOMAIN_NAME%\applications\peoplesoft\pspc\WEB-INF\
Copy <desired server-config.wsdd.option> to replace server-config.wsdd file.
Reboot the WSRP Producer Portal web server to allow the newly installed server-config.wsdd file to deploy web services for the producer.

Defining Nodes With WS-Security

This section discusses how to set up nodes for WS-Security.

Pages Used to Define Nodes With WS-Security

Page Name	Object Name	Navigation	Usage
Portal	IB_NODEURI	PeopleTools, Portal, Node Definitions, Portal	Enter required information for the WS-Security node.
WS Security	IB_NODESECURITY	Click the WS Security tab from the Portal page.	To enable secure access based on WS-Security for remote producers. Note. Secure access is optional. You must be an administrator to access this page.

Page Name

Object Name

Navigation

Usage

Portal

IB_NODEURI

PeopleTools, Portal, Node Definitions, Portal

Enter required information for the WS-Security node.

WS Security

IB_NODESECURITY

Click the WS Security tab from the Portal page.

To enable secure access based on WS-Security for remote producers.

Note. Secure access is optional. You must be an administrator to access this page.

Configuring WS-Security For WSRP Consumers

Access the WS Security page.

Select Authentication Token options based on the options specified in the server-config.wsdd file.

Security Option	Authentication Token Option
None	Leave all options blank.
Authentication Token as Username Token	For Authentication Token Type, select Username Token and leave the remaining check boxes blank.
Authentication Token as Username Token with full security	For Authentication Token Type, select Username Token and select both the Encrypted and Digitally Signed check boxes. Note. With this option the Username Token is encrypted and messages are digitally signed.
Username token with no password and digital signature.	Username Token, no password.

Note. The Use Default User ID check box applies only to WS-Security implemented for the PeopleSoft Integration Broker.

Note. The WS-Security support will be limited to the username and password based on the use of the UsernameToken Profile of the WS-Security specification.