Setting up HTTPS on OHS for Fusion Apps

Introduction

The purpose of this article is to outline the steps that can be followed to replace the default SSL certificates for OHS with certificates that have been signed by a certification authority (CA). The intended audience is those who have little experience with OHS and SSL and those who want a reference that they can compare their work against.

 

Details

The default certificate that is created for OHS by the installer will work in creating an HTTPS (HTTP over SSL) session between OHS and a browser. However, the first time that A user goes to the OHS server, the following message will be displayed in Internet Explorer:

blog002

 

If the user clicks on the “Continue to this website” link, Internet Explorer will continue normally, but the warning will persist:

blog003

blog004

Firefox will behave similarly:

blog005

Every current browser will display a variation of this. This is because the certificate was created properly but it wasn’t created by a certificate authority that the browser trusts. This is expected behavior that has been built into the browser because of past security attacks on the internet. In this case, the certificate is legitimate because the OHS installer put it there, and one can override the warning and carry on. A business user doing acceptance testing or an end user in production however, will not necessarily know this and assume that something is wrong.   Fortunately, the fix for this is relatively straightforward and for a production deployment it’s typically mandatory to replace this default certificate with a signed certificate. In production, this is usually done with a certificate that is signed by one of the major third party Certificate Authorities such as Verisign. If Internet Explorer, go to Tools > Internet Options, click on the Content tab and then on the Certificates button. The Certificates dialog will open. Click on the Trusted Root Certification Authorities tab and a list like this one will be displayed:

blog006

These are the Root Certificates that are preloaded into the browser and they provide a “chain of trust” that the browser uses to establish whether or not to show the warning page above. A certificate that is signed by a CA with a Root Certificate in this list will be accepted as legitimate. There are two ways to accomplish this:

1. Deploy a certificate signed by one of the CAs in this list on the OHS server, or

2. Import a new Root Certificate on the browser and use it to sign the certificate you deploy on OHS.

One can actually import the OHS default certificate as a trusted Root Certificate and be finished (Firefox actually lets one do this on the fly), but this isn’t a very satisfactory solution because this would need to be done with each and every default certificate that is required. This is done at the browser, so it’s better to do it once for the root certificate and not worry if more OHS instances are added with their own certificates later. If they all have certificates signed by a trusted root in that list, then any certificate signed by that root will be trusted. The instructions that follow are specifically for OHS 11g because that is the only web server currently certified for Fusion Applications. They apply in general to most of the web server technologies out there (differing mainly in how the certificate is managed on the web server). Note also that for FA, there are a minimum of two OHS servers that need to be configured (the one in front of the IDM/IAM components and the one in front of the FA components).

Locating Oracle Wallet Manager (OWM)

OHS servers use a utility called Oracle Wallet Manager to manage certificates on the server. For the OHS instance that will be worked on, one will need to locate the directory that OWM lives in. This should be in the middleware home, in the bin directory under the directory that the OHS binaries are installed in, e.g., if the web middleware home is: /u02/app/oracle/product/fmw/web then OWM will be located in the directory /u02/app/oracle/product/fmw/web/bin:

blog007

So, logged in as the user that owns the OHS processes (important!), start OWM:

blog008

Opening the Wallet “twiddle’ will show as empty because a wallet hasn’t yet been created. So, in the menu, click on Wallet > New:

blog020

This will result in a dialog that asks to create a default wallet directory. Click no to this because the user that runs OHS almost certainly doesn’t have permission to create that directory. Instead, the wallet should be created in the same directory that the default certificate and wallet were created in by the installer. The next dialog will ask for a password for the wallet:

blog010

blog011

The usual rules for creating passwords apply, including the one to make a note of it somewhere because OWM will prompt for it every time the wallet file is opened in the future. A note about wallets: a “wallet” in this case is just a special type of file for storing certificates (see Reference 3 below).Leave the wallet type as Standard and click OK. At the prompt asking to create a new certificate request, click No to see what a new empty wallet looks like:

blog012

blog013

There is a section for Trusted Certificates, and this is where a copy of the Root Certificate that will sign the server’s certificate will need to be added. Just above is an entry called “Certificate:[Empty]” and this is where the signed certificate will need to be added. Note that, to a lesser extent, the idea of a “chain of trust” applies here as well — the server certificate cannot be loaded into the wallet until the Root Certificate that signed it is loaded. This will be revisited shortly.

Creating a Certificate Request and Saving the Wallet

In order to generate a signed certificate, one needs to generate a certificate request. This is a file containing information about the system or the application that will be using the certificate. Click on the “Certificate:[Empty] entry to highlight it, right-click to open the context menu, and click Add Certificate Request:

blog014

The Create Certificate Request dialog will open:

blog015

For our purposes only the Common Name field really matters. The rest of the fields are important, but they don’t have any impact on SSL functionality. The Common Name needs to match the ServerName directive that is specified in the primary configuration file (httpd.conf). In the following example, this is “fatester.local” so the fields, when filled out, look like this:

blog016

When OK is clicked, the wallet will now look like this:

blog017

and one can export the certificate request to a file.   IMPORTANT NOTE: If the Fusion Apps Enterprise Deployment Guide was followed for the installation AND there is only a single instance of OHS, then a slightly different set of steps must be followed for the OHS instance that is in front of FA because of the virtual server names. In this case, one needs what is known as a “wildcard” certificate, i.e., a certificate whose Common Name starts with a wildcard. In the example above, this would correspond to a Common Name of “*.local” in the request. This is both convenient (the certificate could be used with any web host that matches the wildcard pattern) and potentially perilous (if this certificate is compromised, then all of the web tier components that use it are effectively compromised as well). Reference 6 and similar articles available on the web cover the pros, cons and best practices for this approach. For non-production environments, this isn’t as important but for production this will need to be given serious thought. It should also be noted that for production, one can mitigate this fairly simply by locating the web tier behind a load balancer. The location of the default OHS certificate (meaning the location of the wallet that contains the certificate) is (c.f. Reference 2) in the instance directory for the OHS server, which in this example is:

/u01/app/oracle/admin/ohs_inst1/config/OHS/ohs1/keystores/default

Notice that there is a file already there named cwallet.sso — this is for the default wallet created by the installer. In the keystores directory, create a new folder with the same name as the web host (e.g, fatest.local):

cd /u01/app/oracle/admin/ohs_inst1/config/OHS/ohs1/keystores
mkdir fatest.local
cd fatest.local

The certificate request file is created by clicking on the “Certificate:[Requested]” entry and then Operations > Export Certificate Request from the menu:

blog019

In the Export Certificate Request dialog, navigate to the new directory and enter a filename to be created.Typically the convention “.req” is used for the request file extension, but any valid filename can be used:

blog024

The wallet file is now ready to be saved. This must be named ewallet.p12, and there is no opportunity to use another filename — one can only specify what directory to write this file to. So from the menu, select Wallet > Save As, navigate to this directory and click OK:

blog022

blog025

This directory will now contain two files, the wallet file and the certificate request file:

blog026

Aside: If Using a Third Party or Enterprise CA

If a third party CA is usedto sign the certificate request, then at this point one needs to send the request file to the person in the organization who manages the issuance of certificates through that third party. The request is an encoded plain text file, so one can, for example, simply email the request file to that person. Similarly, if the organization has an internal CA one would again send the request file to the appropriate person. In return, one will receive a signed certificate (and a copy of the Root Certificate) and one can skip ahead to the section titled Importing the Certificate to OWM.

Creating a Local CA Using OpenSSL

If the organization doesn’t have a service contract with a CA or an existing internal CA, one can easily be created using the open source tool OpenSSL. This isn’t the only tool available, but it does have the virtue of being a part of the base Oracle Linux 5 installation. One can confirm that it is present simply by typing “which openssl” in a terminal window, and this should show a result like “/usr/bin/openssl” in response. If not, then a copy can be downloaded from the link in Reference 5 below. One needs to choose a location on the filesystem for the CA and its associated files, and in this example the following is used:

/u01/app/oracle/FA_Certificate_Authority

This puts things in the same file structure as the FA install without risking something happening to it if any changes are made to that install. If one decides to use this CA for more than just Fusion Apps, it may even be located on a different server. In any case, the location should be a protected location with access limited to those who need it, especially if the decision is made to use this CA for production. The first step in creating a CA is to create a public-private key pair using the following command: openssl genrsa -out fa_privkey.pem This creates a file named fa_privkey.pem which contains this key pair:

blog027

Next, create the Root Certificate that will be used to sign certificate requests:

openssl req -new -x509 -keyout fa_privkey.pem -out fa_root_cert.pem -days 3650

This uses the key pair in the file “fa_privkey.pem” to create a Root Certificate named fa_root_cert.pem that will expire in 10 years. That expiry date can be adjusted by the “-days” argument. Notice that, here, one will be asked to provide the same fields that were required for the certificate request:

blog028

In this case, the Common Name doesn’t have to correspond to a particular host, so one is free to specify a descriptive name (FARoot). One now has the following in the directory:

blog029

The certificate request can now be signed, so copy the request file to this directory and run the following command:

openssl x509 -req -in fatester.local.req -CA fa_root_cert.pem -CAkey fa_privkey.pem -CAcreateserial -out fatester.local.pem

blog030

Importing the Certificate to OWM

One now has a signed certificate. This needs to be copied along with the Root Certificate back to the directory that contains the wallet file. Start OWM again. From the menu, select Wallet > Open:

blog031

This will display the dialog that again about the default directory:

blog032

This time, click Yes. Navigate to the folder where the wallet file is located and click OK. One will now be prompted for the wallet password:

blog033

Before the signed certificate can be imported, one needs to import the Root Certificate. From the menu, select Operations > Import Trusted Certificate:

blog034

Select the second option (Select a file…) and click OK. Select the Root Certificate (fa_root_cert.pem in the example) and click OK. One will now see “FARoot” in the list of trusted certificates (recall that this was what was used for the Common Name of this certificate). Next, click on the “Certificate:[Requested]” entry and from the menu select Operations > Import User Certificate. Choose the second option in the following dialog, click OK, and navigate to the signed certificate (fatester.local.pem in my case) and click OK. This will result in something like the following:

blog038

There is only one thing left to do in this utility before saving the wallet and moving on: In the menu, select Wallet and check the check box beside Auto Login (opmn requires this):

blog039

One can now save the wallet (Wallet > Save from the menu) and exit OWM.

Updating the OHS Configuration with the New Wallet Location

The location of the SSL wallet file for OHS is specified in the configuration that it loads at startup from the <instance_home>/config/OHS/<instance_name> directory (this is specified by the value of the “SSLWallet” directive). OHS can have a number of configuration files in addition to httpd.conf and ssl.conf through Apache’s ability to put multiple configuration files together at runtime via the “include” directive. For this reason, it is safer to look for all occurrences of “SSLWallet” in this directory:

blog040

If one examines admin.conf, it will be clear that it’s referencing a different wallet than the default (“proxy-wallet”), so no action is required. It’s the directive in ssl.conf that needs to change: SSLWallet “${ORACLE_INSTANCE}/config/${COMPONENT_TYPE}/${COMPONENT_NAME}/keystores/default” Before beginning, one should make a backup of ssl.conf, and then open it in an editor. Comment out the above line and add a new one that looks like this:

SSLWallet “/u01/app/oracle/admin/ohs_inst1/config/OHS/ohs1/keystores/fatester.local”

Remember, the wallet file is always called “ewallet.p12” so what is being specified is the directory where that file is located. Finally, stop and start OHS via opmn to load the configuration change.

Importing the Root Certificate to the Browser

Recall that, if the Root Certificate that signed the OHS server’s certificate isn’t in that list of trusted CAs, it will need to be added. For Internet Explorer, that requires the following steps:

1. Copy the Root Certificate file (fa_root_cert.pem for me) to the workstation.

2. Rename the file to fa_root_cert.cer (this is a quick and easy way to associate the file with the Windows certificate import utility)

3. Double-click on the file:

blog041

4. Click on Install Certificate and click Next:

blog042

5. Select “Place all certificates in the following store and click Browse:
blog046

6. Select “trusted Root Certification Authorities and click OK:

blog047

7. Click Next:

blog048

8. Click Finish and then Yes at the Security Warning prompt:

blog044

blog049

9. Click OK to close the remaining open dialog boxes. It is now time to test the new certificate:

blog050

The HTTPS page now loads without the initial warning or the subsequent warning in pink beside the address bar. To do the same thing in Firefox, follow a similar set of steps:

  1. Start Firefox
  2. Select Tools > Options from the main menu
  3. Click on Advanced, then the Encryption tab, then click View Certificates
  4. In Certificate Manager, click on the Authorities tab and then the Import button
  5. In the Downloading Certificate dialog, choose “Trust this CA to identify websites and click OK
  6. Click OK in Certificate Manager and then in Options

Similar steps can be used  to import the Root Certificate into other browsers like Opera, Chrome and Safari.

 

References

  1. A good overview of SSL and HTTPS for the (technical) beginner: http://www.ourshop.com/resources/ssl.html
  2. The section of the OHS product manual that lists the location of the default wallet and the configuration file that tells OHS where it is (ssl.conf): http://docs.oracle.com/cd/E23943_01/web.1111/e10144/getstart.htm#BEHGABIH
  3. The section of the FMW Adminitrator’s Guide that covers keystores, wallets and certificates: http://docs.oracle.com/cd/E23943_01/core.1111/e10105/wallets.htm#CHDGIJDC
  4. The section of the FMW Administrator’s Guide that covers SSL for the web tier: http://docs.oracle.com/cd/E23943_01/core.1111/e10105/sslconfig.htm#CBDEEDCF 
  5. The official home page for OpenSSL: http://www.openssl.org/
  6. A cautionary tale on using wildcard certificates: http://www.sslshopper.com/article-the-risks-in-wildcard-certificates.html

Add Your Comment