Oracle WebCenter Services Sample Portlets - Discussions

Date: July, 2009

Securing the Webservices using WS-Security

Note: The portlets are samples released for test, evaluation, and educational purposes.  They are not supported through formal Oracle Support mechanisms.  We are, however, very interested in receiving your feedback on these portlets.  Please post any suggestions, questions, or issues to the Oracle WebCenter Suite Services discussion forum, and we will respond as quickly as possible.

Table of Contents

  1. Introduction
  2. Pre-requisites
    1. Creating a Local Certificate for Testing Purposes
  3. WS-Security Setup
    1. Configuring the discussions server to use WS-Security for all communications
    2. Configuring WS-Security on the portlet provider side

Introduction

This document will help you set up WS-Security on your Oracle WebCenter Discussions 10g installation and also guide you through the required steps for consuming the same on your portlet application.

Pre-requisites

In order to setup WS-Security, you will need to obtain a valid security certificate from a trusted authority. None the less this document will provide you instructions for creating a local certificate which can be leverage for testing purposes only.

If you already have a certificate then you can skip the following step.

Creating a Local Certificate for Testing Purposes

You can create a test certificate using the "keytool" command available as part of your Java installation. The following steps will guide you through creating a signed certificate which you may then use for your testing purposes.

  1. Create a self signed certificate
keytool -genkey -alias <ALIAS> -keypass <KEY_PASSWORD> -keystore <KEY_STORE_FILE> -storepass <STORE_PASS> -dname <NAME> -keyalg RSA
keytool -selfcert -alias <ALIAS> -keystore <KEY_STORE_FILE> -storepass <CLIENT_KEY_PASSWORD> -keypass <KEY_PASSWORD>

e.g.,

keytool -genkey -alias jive -keypass jive_password -keystore client_certs.keystore -storepass clientKeyStorePassword -dname "cn=jive" -keyalg RSA
keytool -selfcert -alias jive -keystore client_certs.keystore -storepass clientKeyStorePassword -keypass jive_password

The above command will create a client_certs.keystore file. This file will be used in the client-side configuration which is discussed later on.

  1. Export the public key from the certificate

keytool -export -alias <ALIAS> -file <CLIENT_CERTS_FILE.TYPE> -keystore <KEY_STORE_FILE> -storepass <CLIENT_KEY_STORE_PASSWORD>

e.g.,

keytool -export -alias jive -file client_public_key.jks -keystore client_certs.keystore -storepass clientKeyStorePassword

  1. Import the public key in to a truststore for use on the discussions server

keytool -import -alias <ALIAS>  -file <CLIENT_CERTS_FILE.TYPE> -keystore <SERVER_CERT_KEYSTORE_FILE> -storepass <SERVER_KEYSTORE_PASS>

e.g.,

keytool -import -alias jive -file client_public_key.jks -keystore server_public_certs.keystore -storepass serverKeyStorePassword

The above command should create a keystore file called server_public_certs.keystore. Move this file to a location accessible via the Jive server. We will use the above file while confguring the security on the discussions server


WS-Security Setup

Configuring the discussions server to use WS-Security for all communications

  1. Access the discussions administration console and navigate to "System Properties". Out here you will need to set / modify the following keys
webservices.soap.custom.crypto.fileName=crypto.properties
webservices.soap.custom.xfire.active=true
webservices.soap.custom.permissionHandler.className=com.jivesoftware.webcenter.webservices.OraclePermissionHandler
webservices.soap.custom.wss4jHandler.className=com.jivesoftware.webcenter.webservices.OracleHandlerProvider
webservices.soap.permissionHandler.className = com.jivesoftware.webcenter.webservices.OraclePermissionHandler

  1. Edit / Create the crypto.properties found at the following location on your server: <owc_discussions_application>/WEB-INF/classes/crypto.properties
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=serverKeyStorePassword
org.apache.ws.security.crypto.merlin.keystore.alias=jive
org.apache.ws.security.crypto.merlin.file=<absolute path of your server certificate file>

Note: In the above configuration, the keystore type / password / alias / location are the same values that you would have entered while importing the public key in to your local key store. If you are using a custom certificate then please ensure that you make the appropriate changes.

If you make any changes to the server's properties, you will need to restart the discussions server.

Configuring WS-Security on the portlet provider side

The war file (contained in the zip) which you imported into your project contains a file - WebContent/WEB-INF/classes/jive-security.properties. We make use of this file in the sample code for setting security based on WSS4J. Open up this file and make the necessary changes to suit your project's requirements.

# The following line tells the code to use security while communicating with Jive
use.ws.security=true
# The location of the client key store that you generated as part of setting up certificates
keystore.location=/scratch/owc/client_certs.keystore
keystore.type=jks
keystore.password=clientKeyStorePassword
cert.key.alias=jive
cert.key.password=jive_password

Note: In the above configuration, the keystore type / password / alias / location are the same values that you would have entered while importing the public key in to your local key store. If you are using a custom certificate then please ensure that you make the appropriate changes.

With the above changes, you have successfully setup WS-Security for the discussion server web services. In the event of any errors, please check your log files for more information.