Part 3: SSL Configuration with Oracle HTTP Server (OHS)

Dear readers,

In the first two parts, we illustrated how to configure the core functions for Identity Management (IdM) with Oracle 10gAS Fusion Middleware. In this section, we will explain how to setup the Oracle HTTP Server or OHS for SSL with Oracle 10g Application Server. OHS is Oracle's implementation of the Apache 1.3 webserver which is an integral component of the Oracle Fusion Middleware technology. In addition to playing a pivotal role in the Oracle 10gAS, OHS is a key ingredient in the Oracle Applications EBS technology stack. With SSL, we can secure HTTP communication between the user's web browser and OHS web server. OHS uses the mod_ossl module or plugin to implement SSL within the web server which fully supports SSL 3.0 standards.

We also have a useful SSL configuration tool (SSLConfigTool) that we will see later on in our discussion which automates many of the steps for us to secure the HTTP protocol with OHS. The SSLConfigTool is located under $ORACLE_HOME/bin directory.

How to Configure SSL with OHS


To configure OHS with SSL, we need to modify the httpd.conf configuration file for OHS to tell Apache 1.3 ahem, OHS server
that it will use SSL for security settings. The httpd.conf file is located under the $ORACLE_HOME/Apache/Apache/conf directory.
The following parameters are key to understanding SSL configurations with OHS:

- ServerName the server which will be enabled for SSL
- SSLWallet File directory path location for the server wallet
- SSLEngine setting to either enable or disable SSL
- SSLVerifyClient verification type for client certificates
we have three options here: none which means SSL without certificates
Optional- only user server certificate
Require: use both server and client certificates


Once we have configured OHS for SSL, we can access the OHS server from secure HTTPS protocol
from the host with https://hostname.domain:4443

Oracle OHS uses the port 4443 as the default port for SSL communications


Now, lets take a look at our current OHS httpd.conf configuration file settings


##
## httpd.conf -- Apache HTTP server configuration file
##

#
# Based upon the NCSA server configuration files originally by Rob McCool.
#
# This is the main Apache server configuration file. It contains the
# configuration directives that give the server its instructions.
# See for detailed information about
# the directives.
#
# Do NOT simply read the instructions in here without understanding
# what they do. They're here only as hints or reminders. If you are unsure
# consult the online docs. You have been warned.
#
# After this file is processed, the server will look for and process
# /home/oracle/infra/Apache/Apache/conf/srm.conf and then /home/oracle/infra/Apache/Apache/conf/access.conf
# unless you have overridden these with ResourceConfig and/or
# AccessConfig directives here.
#
# The configuration directives are grouped into three basic sections:
# 1. Directives that control the operation of the Apache server process as a
# whole (the 'global environment').
# 2. Directives that define the parameters of the 'main' or 'default' server,
# which responds to requests that aren't handled by a virtual host.
# These directives also provide default values for the settings
### Section 1: Global Environment
#
# The directives in this section affect the overall operation of Apache,
# such as the number of concurrent requests it can handle or where it
# can find its configuration files.
#

#
# ServerType is either inetd, or standalone. Inetd mode is only supported on
# Unix platforms.
#
ServerType standalone
#
# ServerRoot: The top of the directory tree under which the server's
# configuration, error, and log files are kept.
#
# NOTE! If you intend to place this on an NFS (or otherwise network)
# mounted filesystem then please read the LockFile documentation
# (available at );
# you will save yourself a lot of trouble.
#
# Do NOT add a slash at the end of the directory path.
#
ServerRoot "/home/oracle/infra/Apache/Apache"
#
# The LockFile directive sets the path to the lockfile used when Apache
# is compiled with either USE_FCNTL_SERIALIZED_ACCEPT or
# USE_FLOCK_SERIALIZED_ACCEPT. This directive should normally be left at
# Port: The port to which the standalone server listens. For
# ports < 1024, you will need httpd to be run as root initially.
#
# This port is used when starting without SSL
Port 7777
Listen 7777
#
# If you wish httpd to run as a different user or group, you must run
# httpd as root initially and it will switch.
#
# User/Group: The name (or #number) of the user/group to run httpd as.
# . On SCO (ODT 3) use "User nouser" and "Group nogroup".
# . On HPUX you may not be able to use shared memory as nobody, and the
# suggested workaround is to create a user www and use that user.
# NOTE that some kernels refuse to setgid(Group) or semctl(IPC_SET)
# when the value of (unsigned)Group is above 60000;
# don't use Group nobody on these systems!
#
User oracle
Group oinstall
#
ServerName sandiego.localdomain
#
# DocumentRoot: The directory out of which you will serve your
# documents. By default, all requests are taken from this directory, but
# symbolic links and aliases may be used to point to other locations.
#
DocumentRoot "/home/oracle/infra/Apache/Apache/htdocs"

#
# Each directory to which Apache has access, can be configured with respect
# to which services and features are allowed and/or disabled in that
# directory (and its subdirectories).
#
# First, we configure the "default" to be a very restrictive set of
# permissions.
#

Options FollowSymLinks MultiViews
AllowOverride None




We also need to update settings for the Oracle Process Manager and Notification (OPMN) for our Portal 10gAS instance
by changing settings for the opmn.xml configuration file located under the $PORTAL_HOME/opmn/conf directory. We can either edit this configuration file for Portal directly or more conveniently, to use the Oracle 10gAS Application Server Control for the Portal instance under Process Management tab. Below is our sample opmn.xml config file for Portal:

Of note here for our purposes, is that we need to enable SSL communication for the OHS HTTP Apache 1.3.x web server. By default, SSL is NOT enabled! So we need to find the section in the opmn.xml file that references the HTTP server. Below is the relevant section:

ias-component id="HTTP_Server"
process-type id="HTTP_Server" module-id="OHS"
module-data
category id="start-parameters"
data id="start-mode" value="ssl-disabled"

We need to change this to "ssl-enabled" and resync OHS to allow SSL settings to take affect.


I prefer to use Application Server control because if we edit the opmn.xml file directly, we need to resync it manually which can be a pain. Application Control Server does this automatically for us. Under the main Portal instance page for 10gAS, we navigate to Process Management as shown below



This brings us directly to the editor for the opmn.xml file and we update it to enable the SSL option



We apply the changes.




Now we need to verify that our certificates can be accepted and then apply final configuration changes to the OHS httpd.conf file to ensure SSL communications function correctly. First, we need to navigate to the Oracle Certificate Authority (OCA) user page. We also need to clear out our web browser and remove old certificates since we are using the same server for our testing purposes.




We use our administrator account and password to login via SSO




Once we login, we can view certificates that we created earlier




We choose to get our certificate by choosing the option Get Certificate which will be used for future SSL communications





Details for the certificates are shown below.




Now we need to add the directives to the Portal Instance OHS web server to complete our setup for enabling SSL with Oracle
10g Application Server.







To complete our SSL tasks for OHS, we need to select Advanced Server Properties tab in the HTTP Server administration web page.




Since the httpd.conf configuration file for OHS is what need to modify to complete our SSL setup for Oracle HTTP Server, we click on the link.

We need to add a couple of directives to our Apache (OHS) httpd.conf configuration file to enable SSL.

SSLVerifyClient require


We then click the Apply button and OHS will need to restart the web server to apply our changes for SSL. Be careful editing this file since any typos will cause the OHS web server to fail to restart.





Now hopefully, our Apache web server OHS restarts with the enabled SSL changes.

A good reference for Apache and OHS since OHS really is Oracle's rebranded version of the Apache 1.3 web server is to consult the Apache main site http://apache.org

For reference on the Apache and OHS SSL directives the link
http://httpd.apache.org/docs/2.2/mod/mod_ssl.html has excellent supplemental details.

Part 2: SSL Configuration with Oracle Wallet Manager and SSO

In our last post, we introduced the concepts of SSL for Oracle Fusion Middleware with Oracle 10gAS in terms of concepts with how to manage the certificate authority (CA) with SSL and the Oracle Certificate Authority (OCA) server.

Upon a review of support notes from Oracle Metalink, the following notes will come in useful for our in depth analysis and review of how to manage SSL with Oracle 10gAS:


Note: 351341.1 - How To Setup and Configure SSO/OHS for SSL
Note 351340.1 - How To Create SSL Wallet Using Wallet Manager and Oracle Certificate Authority
Note 351365.1 - How To Set up and Configure SSO and OIDDAS to use SSL


I highly recommend that all Oracle DBAs and analysts read and digest these Metalink support notes before you configure SSL for Oracle 10g Application Server so that problems are avoided and success ensured for your SSL administration tasks. By doing so, you will prevent many headaches and avoid potential gotchas. I usually make a point to read the release notes and Metalink notes before I perform a major task for a new environment as it saves me hours of frustration. Since we are using a demo lab based environment, some of these tasks from Metalink will not apply but the key concepts still are valid. Now lets move on from where we left off last time which is to configure the Oracle Wallet Manager (OWM) environment so that we can setup a new set of wallets for our certificates for use with SSL and Oracle 10g Application Server.

Now that we have setup our Oracle Certificate Authority (OCA) to use trusted certificates for SSL connections, we can proceed to configure new wallets with Oracle Wallet Manager (OWM) for Oracle 10g Application Server. In contrast to the OCA administration pages located under https://server:/oca/admin we need to check on the user OCA pages by navigating to the pages for user certificates under https://server:/oca/user as shown below figure example.





This differs from the OCA administrator site that provides maintenance options for certificate management with the Oracle certificate authority (OCA) in that user certificates can be viewed and managed on the user site.




From the user menu sitre we can trust and view the certificates to be authenticated by Oracle 10g Application server.
We can also import the Certificate Revoke Lists (CRL) that we saw earlier.



Now lets try to see if our previous certificate is accepted when we attempt to connect to SSO and OCA via SSL.
We click on the right tab option for User Certificates



We try the option by using our existing certificate



OK, so we have several things that we can do from this screen. We can examine the certificate in further detail as well as update the CRL (Certificate Revocation list), get the certificate, as well as change authentication options.

If we choose to get our certificate we can update options for managing our certificate. Now, we need to configure our server side certificate options. For this task, we need to use the Oracle Wallet Manager (OWM)

Oracle Wallet Manager (OWM)


So at this point you are probably wondering, what exactly does this Oracle Wallet Manager (OWM) do and why do I need it? Well, the Oracle Wallet Manager (OWM) is an integral component of SSL authentication. As such, it performs the following key tasks for Identity Management with Oracle 10g Application Server for SSL:

- generates public/private key pair
- creates certificate request
- installs certificates
- configures trusted certificates
- creates the wallet which is accessed by the Oracle Wallet Manager (OWM)
- uploads contents of wallet to LDAP directory systems such as Oracle Internet Directory (OID)
- imports and exports wallets

The Oracle Wallet Manager tool (OWM) is located under $ORACLE_HOME/bin directory for the Oracle 10gAS Infrastructure environment. New wallets must use a password based on the following standard of minimum 8 characters with at least one alphabetic and numeric or special character. The OWM users trusted and user based certificates. One caveat is that you need to install a trusted certificate first before using a user certificate issued by the certificate authority (CA). Wallets can be exported and imported as well. We also will need to configure our end user web browser to trust the OCA. This varies based on your browser version and configuration. We will provide an example of this shortly.

We also need to enable the Oracle HTTP (Apache 1.3) server (OHS) to use SSL. This will be discussed in the third installment for SSL and Oracle 10gAS. Finally, we need to use the SSL configuration tool to automate changes for securing HTTP. Furthernmore, we need to add user certificates to the Oracle Internet Directory (OID) via the ldapmodify command or via an ldif file.


Since we are using a single web browser for our lab environment and Mozilla Firefox in this case, we need to clear out old certificates before we configure a new wallet for Oracle 10g Application Server. We also need to enable Mozilla Firefox to accept certificates. Under our browser window we need to EDIT->PREFERENCES which brings up the options for certificates.



Make sure to select the option for "Ask Every Time" otherwise errors may occur for our certificate authentication processing.
We also need to clean out old OCA web administrator certificates from previous tasks. To do this, we need to stop and restart our OCA server. We can use the $ORACLE_HOME/oca/bin/ocactl stop then $ORACLE_HOME/oca/bin/ocactl revokecert and then restart OCA server with the $ORACLE_HOME/oca/bin/ocactl start command as shown in the following example.





Now we are all set and ready to create a new wallet! To start the Oracle Wallet Manager (OWM) we simply open another terminal shell command window and execute the owm from $ORACLE_HOME/bin directory



From the main OWM screen, we can perform many tasks such as creating new wallets, importing or exporting wallets just to name a few tasks. Now let's create a new wallet.



Oracle Wallet Manager (OWM) asks us if we wish to create a new default wallet. We choose Yes and it complains that it cannot create a default wallet in the system directory with message of "Unable to create system default wallet directory."



We continue anyways and ignore the error warning message




Now we need to enter a wallet password and choose authentication option




We have a choice between standard wallet type of PKCS11 wallet type that we discussed earlier. Lets keep with standard wallet type for sake of simplicity.



Our wallet is created successfully and OWM asks us if we would like to create a new certificate request to link to the new wallet. Since we need to do this, we enter the following details for our new certificate request. We choose to keep the default key size to 1024 bits.



We confirm our choices for the new certificate request and click the OK button.

Now we can see that the new certificate request has been successfully created by OWM.



We still need to submit the certificate for acceptance to the OCA via the user pages that we saw earlier.
To view and obtain the details for our new certificate created by OWM we can examine the details under the menu tree for Wallet-> Certificate [Requested] as shown in the figure example below:




What we need to do is to clear entries from the web browser so that old certificates do not appear since we want to login to the OCA as a user and not as an administrator.





Also be sure to delete old certificates to avoid problems since in our test environment we have a single web browser and server used. Now we need to return back to our OWM window that had the certificate details from our newly created certificate request. Open a new browser window in tandem with having OWM open and connect to the Oracle Certificate Authority User page via SSL based on https://host_name.:/oca/user

In our case, we connect to SSL port 6600





Now we need to copy the certificate details from our new certificate request from OWM from BEGIN NEW CERTIFICATE REQUEST until END NEW CERTIFICATE REQUEST

Move back to the User OCA page and click on Request a new certificate on the Server/SubCA Certificates tab





Now we need to choose the option "Request A Certificate"

Paste the new certificate request encrypted details from OWM into the main field as shown below






Enter personal information in the fields and click OK to submit the request to the OCA.



Now we need to generate the server certificate. Click the Submit button. We verify that it is accepted by the OCA



Our certificate request has been accepted and stored in the OID server. Now we can exit OWM and need to approve the new certificate request from the OCA Administration page. We can cancel saving the new wallet as that is not required. Now lets take a look at how to approve the new certificate request.

Since we are doing this on same server and web browser we need to shutdown the OCA server, revoke old admin certificates, remove them from our browser and restart the OCA services.




We now see the new certificate details for review to either approve or reject the requests




Lets go ahead and approve the new certificate request by View Details






When we submit approval the OCA prompts us once more to make sure we wish to approve the new certificate request





Our new certificate request is approved status and shown below




Now we can verify that the newly created certificate request is available with OCA




We can also verify the encoded certificate details given in BASE64 format:




We will continue our setup for SSL with Oracle 10g Application server in the next installment as the final steps require us to modify configuration to the OHS (Oracle HTTP Server aka Apache 1.3).

Part 1: How to Configure SSL for Oracle 10g Application Server: Part I- Certificate Authority (OCA)

As a subset of Identity Management for Oracle 10g Application Server with Fusion Middleware, we will provide a brief two part series on how to manage SSL. In this post, we will discuss how to setup, configure and manage the Secure Socket Layer (SSL) security within Oracle 10g Application Server. The first part will be to configure the Oracle Certificate Authority (OCA) for use with certificates and the second part involves how to setup and manage wallets with the Oracle Wallet Manager for certificates with SSL and Oracle 10g Application Server. We will provide a four part series on SSL since it is an extremely complex subject within Identity Management (IdM) for Oracle Fusion Middleware.

Part 1: Concepts for SSL and Oracle Certification Authority (OCA)
Part 2: SSL Configuration with OCA and Oracle Wallet Manager (OWM)
Part 3: OHS (Oracle HTTP Server) Configuration for SSL
Part 4: Additional topics for SSL with OracleAS 10g such as EBS


Concepts for SSL and Oracle 10gAS PKI


The Oracle Public Key Infrastructure (PKI) is the big picture for managing certificates within Oracle Fusion Middleware components. PKI consists of the following items:

- Secure Sockets Layer (SSL)
- Oracle Wallet Manager (OWM), containers and wallets
- the Oracle Internet Directory (OID) and Oracle 10g Application Server Single Sign On (SSO)

We have discussed most of these components already for OID and SSO. However, before we manage to discuss the details for SSL configuration with Oracle 10gAS, we need to first understand how to configure the Oracle Certificate Authority (OCA) and Oracle Wallet Manager (OWM).

Understanding Certificates with Oracle PKI Components for 10gAS


Digital certificates are electronic documents that establish security credentials for transactions within Oracle 10gAS including Oracle 10g Portal, Reports, and Discoverer applications. Each certificate contains the username and digital signature from the issuing certificate authority (CA). We have a few different types of certificates:

- Client based certificates: also known as end-entity certificates which contain personal or user certificates
- Web server certificates contain server side digital signature for secure web communications between servers.
- root authority certificates are self signed certificates which form the base or root of a certificate authority (CA).

What is a certificate authority (CA) ? A certificate authority is a third party such as Verisign that provides the verified credentials for an organization and issues the security certificates used for all SSL connections. This CA performs the authentication of the user's certificate identity so that it is trusted within the 10g Application server environment. Oracle 10gAS provides a utility called the Oracle Certificate Authority (OCA) which administers and manages these certificates. After the certificate is available it needs a storage place for safe keeping and reference during 10gAS processing of transactions. Here is where the Oracle Wallet Manager (OWM) utility comes into play. We have two choices where to store these trusted certificates: in an LDAP directory system or a wallet manager. The Oracle Wallet Manager (OWM) allows us to store these certificates in a repository schema located in the 10gAS Infrastructure database for safe keeping. We can use the PKCS #12 (Personal Information Exchange Syntax) standard if we so wish as part of the certification process. The Oracle Wallet Manager (OWM) allows us to manage the security credentials for clients and servers.

How Does SSL Work?


The SSL process operates in the following series of steps to provide secure communication between the user's client and Oracle 10g Application Server.

1. An end user connects to the 10g Application Server and submits a request on the SSL port via HTTPS protocol.

2. The server verifies the user's identity by signing the certificate and sending it back to the client

3. The client end user will use the server public key to verify that the owner of the certificate is indeed the same user who signed it. If the certificate authority (CA) credentials are unknown, the end user client browser replies that the certificate was issued by an unknown CA.

4. The user manually verifies that the site certificate has been issued by a trusted authority ie) Verisign and generates a encypted token using the server's public key.

5. The certificate is sent back to the server and SSL performs a handshake operation based on the cipher in the public key. If the session keys match, the certificate is accepted and the end user is able to access the Oracle 10g Application server applicatons via SSL.

The Oracle Certificate Authority (OCA) verifies all details of the operations for SSL with the SSO and OID servers during this process. Now that we have provided an introduction to SSL and Oracle PKI security, lets present some hands on examples of how to configure certificates for SSL with the Oracle Certificate Authority (OCA).

Setup and Configuration for Oracle Certificate Authority (OCA)


By default, after installing the Oracle 10gAS infrastructure components for Oracle 10g Application Server, the OCA is not started. As such, we need to start and verify the processes for the OCA.

By default, the OCA configuration files live under the $ORACLE_HOME/oca/conf directory for the 10gAS infrastructure.

We need to startup the OCA by using the ocactl utility located under $ORACLE_HOME/oca/bin. Once we start the OCA processes by executing the ocactl start command, we are ready to configure the certificates for Oracle 10gAS.




To get help on using the ocactl commands, we have the following example:





The oca.xml file contains the main settings for the configuration of the OCA for Oracle 10g Application server as shown in the following example.



You can edit the file with any XML editor utility.
Since OCA relies on wallets to store the various PKI credentials and password storage area for passwords. The OCA requires the certificate authority (CA) signing wallet as well as the CA SSL wallet. The CA signing wallet is created by the Oracle 10gAS installer or can be imported from another CA to setup a custom CA structure. The new wallet along with the signed key and certificate are signed by the new CA. The SSL certificate authority wallet is created by the 10gAS installer when you install 10g Application Server components for the Infrastructure. It contains the SSL certificate and private key for the SSL server that hosts the OCA. This SSL wallet can also be imported from another certificate authority (CA) or managed by the Oracle Wallet Manager (OWM) utility.

To access the OCA interface from within Oracle 10g Application Server, we can navigate to the 10gAS home page for OCA based on https://server:/oca/admin as shown in the following example.



We can also check the details from the main 10gAS application server infrastructure page for OCA operations.



Now lets return to the main OCA interface that we discussed earlier. The first step for configuration after we have started the OCA processes with 10g Application Server is to setup the enrollment process for certificates.




The fields with asterisks are required by OCA. Here we use ocawebadmin as our user with ABC
for the organization. We also have options below to setup the certificate information.




We can set the time period for the certificate from 6months to 5 years. We also have an option to set the certificate key size to either high grade or medium grade based on our security and encryption policy standards. We finalize our setup and click the submit button which will process our new certificate details as shown below.



Now that we have our OCA certificate for administration tasks, we need to import it into our web browser! To do so, we choose the option below to install in browser.



Once we have successfully added the new certificate to our browser, we save the backup copy and return to our main OCA administration page to verify all certificates and their status. Since this was a test certificate that we used previously, OCA rejected our new certificate request. So we will need to revoke all certificates by using the ocactl revokecert command. In the next post, we will cover these tasks in more detail to complete our coverage for SSL with Oracle 10g Application Server. In a nutshell the reason why this failed was because the certificate also needs to exist in the Oracle Wallet Manager (OWM). If the certificate cannot be found by OWM, it will be rejected by the OCA. So we will need to clear out all certificate requests and recreate a new wallet and certificate for SSL to be used by the Oracle 10g Application Server. We conclude this introduction to SSL configuration with a summary display of the main OCA administration page for certificate management.

The first general pages provides us with options to manage and configure certificates and certificate requests.



When we first access the general tab, the certificate will popup to ask us if we trust it or not as confirmation.
We have many options here to configure and publish the certificate with SSL. We can enable or disable SSL and/or SSO authentication for our certificates as well as configure directory settings for the LDAP OID server. We also have a Notification tab to setup our SMTP server for emailing alerts and messages to the OCA administrator.



If we need to change policy settings for managing our certificates, we navigate to the Policy tab for the OCA Administration web console.




We can set policy rules for certificates based on requests, revocations or renewals. Under the Certificate Management tasks menu, we can also update our Certificate Revocation List (CRL).




We have menu options to enter the number of days to keep the certificate revocation list valid in days (CRL Validity)
as well as the Signature Algorithm choice between SHA1 with RSA or MD5 with RSA.




On a final note for our introduction to SSL with Oracle 10gAS, there is an option to customize the certification practice statement issued by the OCA within Oracle 10g Application Server applications. By editing the ocaadmin_cs_practicestmt.html file located under $ORACLE_HOME/j2ee/oca/applications/oca/helpsets/oca_practice_stmt, IT security administrators can have a department message issued by Corporate IT security as part of the messaging system.

We will conclude our discussion of SSL for Oracle 10gAS in our next post by explaining the setup and configuration of the Oracle Wallet Manager (OWM) with the Oracle Certificate Authority (OCA) for SSL.