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 security options for WS-Security to choose from.

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 to communicate between the producer and consumer

See Using HTTPS Protocol to Communicate Between Producer and Consumer.
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.

Important! To communicate with each other, the security option used by the producer must be an exact match to the security option used by the consumer.

Understanding WS-Security

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 username/password through the use of 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

PeopleSoft Portal as WSRP Consumer

The signed in portal users ID and password 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.

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

This figure shows how the security header is added when the PeopleSoft portal is the WSRP consumer:

Example PeopleSoft Portal as WSRP Consumer

PeopleSoft Portal as WSRP Producer

The portal accepts the Username Token in the WSS header from the foreign portal, assuming that the ID and password are acceptable to PeopleSoft.

This figure shows how the security handler manages the WS-Security header when PeopleSoft portal is the WSRP producer.

Example PeopleSoft Portal as WSRP Producer

PeopleSoft Portal as WSRP Consumer and Producer

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

Example PeopleSoft Portal as WSRP Consumer and Producer

Setting Up WSRP Security Options

This section discusses how to:

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

Using HTTPS Protocol to Communicate Between Producer and Consumer

When the security option “Authentication token as Username token in clear text format” is selected, HTTPS mode is recommended 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.

See Implementing WebLogic SSL Keys and Certificates, Setting Up SSL on WebSphere 5.1.1.

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.

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 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, for example: weblogic_domain\keystore\pskey.

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 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.

Enabling message Signature

Consumer:

Create the signature key and certificate on the consumer and store in the web server predefined keystore, for example: weblogic_domain\keystore\pskey.

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 server is:

%PS_HOME%\webserv\%DOMAIN_NAME%\applications\peoplesoft\PORTAL\WEB-INF\classes

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

:%PS_HOME%\webserv\%DOMAIN_NAME%\applications\peoplesoft\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)

% PSCipher.bat <password>

Note. PSCipher.bat is located under the %PS_HOME%/webserv\%DOMAIN_NAME% directory.
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

Configuring WS-Security For WSRP Producers

The producers %PS_HOME%\webserv\%DOMAIN_NAME%\applications\peoplesoft\pspc\WEB-INF\ directory contains a server-config.wsdd file, which contains the WSRPBaseService definition plus three variations. Each one of the variations is associated with a security option:

None. server-config.wsdd.none.
Authentication Token as Username Token.server-config.wsdd.usernametoken
Authentication Token as Username Token with full security.server-config.wsdd.fullsecurity

PeopleSoft provides two options for modifying the security constraint on the WSRPBaseService. Option one undeploys and redeploys web services dynamically without having to reboot the web server. Use option two if your web server is not up and running..

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

Option One

To modify WSRPBaseService without having to reboot the web server.

Using the Command Prompt, enter the command:

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

Example: redeployWS 2.

This will redeploy WSRPBaseService using UsernameToken in clear text security option.

Option Two

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

Using the Command Prompt, enter the command:

cd %PS_HOME%\webserv\%DOMAIN_NAME%\applications\peoplesoft\pspc\WEB-INF\
Copy <desired server-config.wsdd.option> to replace server-config.wsdd file.
Reboot WSRP Producer Portal web server to allow 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 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.

You must be an administrator to access this page.

Enter information based on your security requirements:

None: Leave all the fields blank.
Authentication Token as Username Token: Select Username Token as the authentication token type and leave the remaining fields blank.
Authentication Token as Username Token with full security: Select Username Token as the authentication token type, and select both the Encrypted and Digitally Signed check boxes.

Note. With this option the Username Token is encrypted and messages are digitally signed.

Note. The WS-Security support will be limited to username/password through the use of the UsernameToken Profile.