Enabling SSL for BI Publisher Standalone

How to enable SSL (Secure Sockets Layer) for my BI Publisher Server installed with OC4J standalone ?

SSL is a cryptographic protocols that provides a encrypted therefore secured communications over internet. This can be enabled for your BI Publisher Server to secure the communication between the server and the clients.

I’m sure many of you have installed BI Publisher as a part of Oracle BI EE suite or as just a BI Publisher Server standalone following the standard installation with the installer. The standard installation installs an embedded OC4J server and deploy BI Publisher Server on the OC4J server. In this deployment architecture you don’t have any HTTP server. OC4J Server directly interacts with clients http requests and returns response to the clients for the BI Publisher Server.

Today, I will talk about how to enable the SSL for such configuration, which is that BI Publisher Server standalone deployed on OC4J standalone. I will focus only on enabling SSL communication.

Here is a list of the brief steps that you need to perform.

• Create a Keystore
• Create and Update secure-web-site.xml
• Register the secure-web-site.xml in server.xml
• Test

Create a Keystore

A keystore stores certificates, including the certificates of all trusted parties, for use by a program. Through its keystore, an entity such as OC4J (for example) can authenticate other parties, as well as authenticate itself to other parties. In Java, a keystore is a java.security.KeyStore instance that you can create and manipulate using the keytool utility that is provided with the Sun Microsystems JDK. The underlying physical manifestation of this object is a file.

Here are the steps to create the keystore.

1. Change the directory to ORACLE_HOME/j2ee.

2. Create a keystore with an RSA private/public keypair using the keytool command. In this example, we generate a keystore to reside in a file named mykeystore, which has a password of 123456 and is valid for 365 days, using the RSA key pair generation algorithm with the following syntax:

% keytool -genkey -keyalg "RSA" -keystore mykeystore -storepass 123456 \ -validity 21

Note:

The keystore option sets the filename where the keys are stored.

The storepass option sets the password for protecting the keystore.

The validity option sets number of days the certificate is valid.

The keytool prompts you for more information, as follows:

What is your first and last name? [Unknown]: Kan Nishida What is the name of your organizational unit? [Unknown]: Consulting What is the name of your organization? [Unknown]: Oracle What is the name of your City or Locality? [Unknown]: New York What is the name of your State or Province? [Unknown]: NY What is the two-letter country code for this unit? [Unknown]: US Is <CN=Kan Nishida, OU=Consulting, O=Oracle, L=New York, ST=NY, C=US> correct? [no]: yes Enter key password for <mykey> (RETURN if same as keystore password): Always press RETURN for the key password. In the OC4J 10.1.3 implementation, the keystore password must be the same as the key entry password.

The mykeystore file is created in the current directory. The default alias of the key is mykey.

Create and Update secure-web-site.xml file

1. If you do not have a secure-web-site.xml file, copy the default-web-site.xml to ORACLE_HOME/j2ee/home/config/secure-web-site.xml (by convention).
   
2. Open the secure-web-site.xml and add secure="true" to the <web-site> element, as follows:
   
   

   <web-site port="4446" display-name="Default OracleAS Containers for J2EE Web Site" secure="true" > ... </web-site>

   
   
3. Change the <web-site> port setting to some available port. For example, port="4443". (To use the default of 443, you have to be a super user.)
   
4. Add the following under the <web-site> element to define the keystore and password.
   

   <ssl-config keystore="your_keystore" keystore-password="your_password" />

   
   Where your_keystore is the path to the keystore—either absolute, or relative to ORACLE_HOME/j2ee/home/config (where the Web site XML file is located)—and your_password is the keystore password. For example:
   

   <!-- Enable SSL --> <ssl-config keystore="../../keystore" keystore-password="123456"/>

Register secure-web-site.xml file in server.xml

Add the following line in server.xml:

<web-site path="./secure-web-site.xml" />

Save the changes and restart OC4J server to reflect the changes.

Access to BI Publisher Server for Testing

Now all the settings are done. Let’s test. You should be able to use ‘https’ to access to your BI Publisher.

https://hostname:port/xmlpserver where the port number is the one you set in the secure-web-site.xml file. e.g. https://knishida-lap.us.oracle3.com:4446/xmlpserver

Now OC4J listens for SSL requests on one port (in this example 4446) and non-SSL requests on another (the default is 9704). You can disable either SSL requests or non-SSL requests, by commenting out the appropriate *-web-site.xml pointer in the server.xml configuration file:

<web-site path="./secure-web-site.xml" /> - comment this to remove SSL <default-site path="./default-web-site.xml" /> - comment this to remove non-SSL

Conclusion

Well, it’s pretty simple right?. But of course if you want to really secure then you can do more in the configuration. Also if you have a http server involved, which is a typical architecture with Oracle Application Server, then it requires extra steps. You can take a look at OC4J Security Guide 10.1.3 for the detail. Also, if you need to integrate with Oracle BI EE, which is SSL enabled then there will be more steps, though they are documented in the Oracle BI EE Deployment Guide.