enabling ssl in oracle e-business suite release 12

8/10/2019 Enabling SSL in Oracle E-Business Suite Release 12

1/35

1/13/2015 Document 1425103.1

https://support.oracle.com/epmos/faces/DocumentDisplay?_adf.ctr l-state=ewbsr79se_191&id=1425103.1

SSL Primer: Enabling SSL in Oracle E-Business Suite Release 12 (Trial Certificate Example)(Doc ID 1425103.1)

In this Document

Abstract

History

Details Introduction

Configuring the EBS Web Tier for Direct HTTPS Communication

1. Set Your Environment

2. Create a Web Tier Wallet

3. Create a Certificate Request

4. Export the Certificate Request

5. Submit the Certificate Request to a Certifying Authority

5. Import your Certificate to the Wallet

6. Copy the Apache Wallet to the OPMN Wallet

7. AutoConfig

Client Configurations

Introduction

Client Browser Configuration

Mozilla Firefox Security Exception

Microsoft Internet Explorer Security Exception

Retrieving the Public Facing SSL Certificates Using the Client Browser

Introduction

Retrieving the Certificates using Mozilla Firefox

Retrieving the Certificates using Internet Explorer

Importing SSL Certificates into the JDK's Trusted Certificate Store

Creating a Database Wallet and Importing Trusted SSL Certificates

Summary

References

APPLIES TO:

Oracle Applications Technology Stack - Version 12.0.6 to 12.1.3 [Release 12.0 to 12.1]

Information in this document applies to any platform.

ABSTRACT

This note is an illustrated companion to the primary Note:376700.1-Enabling SSL in Oracle E-Business Suite Release 1

and covers the implementation of a Verisign Trial Certificate as an example. The daunting length is primarily due to

the depth of explanation and the number of illustrations.
http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-


2/35

1/13/2015 Document 1425103.1

https://support.oracle.com/epmos/faces/DocumentDisplay?_adf.ctr l-state=ewbsr79se_191&id=1425103.1 2

HISTORY

Author: DCOLLIER

Create Date 28-FEB-2012

Update Date06-Nov-2012

Expire Date distant future

DETAILS

Introduction

There are several places within the EBS R12 instance that require changes to properly work with SSL as documented

Note:376700.1-Enabling SSL in Release 12. These several places are configured using different methods and quite

often the steps are done initially by one person and then later need to be revisited by another person years later when

a step is discovered to have been skipped or a certificate needs to be updated. This simplified guide provides an

illustrated walk-through of each step of the process using a trial certificate as an example. The process is similar for

self-signed, internally-signed, and paid-for certificates.

This guide is written as a very detailed and illustrated primer and each step is illustrated in two ways. The orapki

command line interface examples illustrate and accomplish the task in a very direct and curt fashion, whereas the

abundance of screenshots from the Oracle Wallet Manager's graphical user interface should appeal to newer users.The desired result of creating a wallet can be done by either method, but first time users should choose EITHER orap

OR owm and consider the alternate examples as an illustration of a concept.

SSL Offloading versus SSL Running Natively

SSL uses a handshake protocol to negotiate and establish a session between the client machines and the HTTPS

enabled web servers. During the handshake process, digital certificates are used to authenticate identity and

negotiate how to encrypt the information for the remainder of the session. The Oracle EBS web tier is quite

capable of this, but many customers opt to offload the SSL processing to a reverse proxy or load balancer. The SSL

offloader that acts as an SSL terminator decrypts the SSL-encrypted data from the client and then proxies that data

to the EBS tier in an unencrypted state. As the term implies, the overhead of SSL processing is taken completely

off of the EBS web tier so that the EBS web tier is dedicated to EBS specific processing. This improves

performance and security because the SSL offloader tends to run on specialized SSL acceleration hardware

separate from the EBS web tier and can more easily integrate with intrusion detection systems, virus detection

systems, application layer firewalls, etc. Integration of EBS with one of these third party devices is generally a

simple matter of updating six AutoConfig context file parameters and then running AutoConfig after that third party

device is configured.

While the specific configuration of the third-party SSL hardware is supported and documented by the third-party

vendor, the integration with EBS is detailed in the primary Note:376700.1. SSL offloading is mentioned here only

as an important consideration before proceeding to run SSL directly on the EBS web tier which is covered in the

next section as a starting point for the illustration of further EBS configuration details that follow. Note that even if

an SSL Offloader is used as a web entry point, the JDK(s) and database still require an SSL configuration of their

own because they act as SSL clients to that web entry point.

Configuring the EBS Web Tier for Direct HTTPS Communication

1. Set Your Environment
https://support.oracle.com/epmos/faces/DocumentDisplay?parent=DOCUMENT&sourceId=1425103.1&id=376700.1


3/35

1/13/2015 Document 1425103.1


The web tier setup on EBS R12 instances makes use of the utilities within the 10.1.3 ORACLE_HOME. The typical

applmgr environment is based on the environment files from the APPL_TOP which refer to the 10.1.2 ORACLE_HOME,

so therefore an alternate environment file must be sourced before attempting to start. Navigate to the 10.1.3

Configuration Home and source the 10.1.3 environment file. The file will be named after the $CONTEXT_NAME whic

is typically the SID ($TWO_TASK) followed by the hostname.

For example:

> cd $ORA_CONFIG_HOME/10.1.3

> ls -l *.env

-rw-r--r-- 1 appv1211 dba 3202 Dec 31 01:13 V1211_myserver.env

> . ./*.env

Check your work. The above "dot space dot slash star dot env" should have executed the single environment file in th

$ORA_CONFIG_HOME/10.1.3 directory and reset several environment variables in the current shell. The

ORACLE_HOME should now be the 10.1.3 ORACLE_HOME and the available Oracle Wallet Manager (owm) executable

should be from that same ORACLE_HOME.

For example:

> echo $ORACLE_HOME

/space/r1211/apps/tech_st/10.1.3

> which owm

/space/r1211/apps/tech_st/10.1.3/bin/owm

2. Create a Web Tier Wallet

The Oracle Wallet Manager (owm) is an X-Windows application, so therefore an X-Windows display is required to use

it. There are numerous X-Windows clients available for the PC, the choice of which is left entirely to the user.

Alternatively, UNIX /Linux machines are often setup with VNC or similar remote desktops if you choose not to run thewallet manager directly from the console. As another alternative, you can use the orapki command line interface

which needs no X-Windows client. Both methods are covered here because the wallet manager offers better

illustration of concepts and the orapki tool offers an elegantly simple and direct means to an end. To some extent the

implementation process can be a mixture of orapki and owm, but it is less confusing to pick one method for the entire

wallet setup.

The orapki method for creating a wallet is simply:

> orapki wallet create -wallet $INST_TOP/certs/Apache -auto_login

Enter wallet password:

The required option of auto_login is enabled and the wallet is created in the EBS preferred directory via the '-wallet'

option. This directory is the default value specified within the AutoConfig parameters s_ssl_keystore and

s_ssl_truststore. Also, in this example, the wallet password of choice for the newly created wallet is quietly specified

at the command prompt, but could have just as easily been specified as "welcome1" using the "-pwd" option such as

pwd welcome1". We'll prompt for passwords from this point forward as this is a more secure practice than leaving

scripts with plain-text passwords lying around.

The equivalent step with the wallet manager is as follows:

2a. Set the UNIX DISPLAY variable as needed. This depends on your choice of X-Windows clients.


4/35

1/13/2015 Document 1425103.1


2b. Navigate to $INST_TOP/certs/Apache. Backup any existing wallets that may be there. If you ran the above orap

example (you did not need to), you already have a new wallet preloaded with some trusted certificates that you could

examine with the wallet manager:

> cd $INST_TOP/certs/Apache

> ls -l

-rw------- 1 appv1211 dba 7940 Aug 12 08:59 cwallet.sso

-rw------- 1 appv1211 dba 7912 Aug 12 08:59 ewallet.p12

2c. Start the wallet manager as a background process:

> owm &

The Oracle Wallet Manager should start and display its beginning pages:


5/35

1/13/2015 Document 1425103.1


2d. On the Oracle Wallet Manager menu, select Wallet and then New. Answer "No" to the question "Your default

wallet directory does not exist. Do you want to create it?"

2e. In the "New Wallet" window that appears, enter the password you would like to use for the new wallet. The

orapki example used "welcome1", but any password can be used. Choose the wallet type of Standard, then click OK.

This will create the initial wallet and then ask about creating a certificate request.


6/35

1/13/2015 Document 1425103.1


2f. Conveniently, the wallet manager asks if you would like to create a certificate request at this time. You can say

"Yes" at this point and skip to step three. If you select "No", you can still create a certificate request via the menu

navigation of "Operations"/"Add Certificate Request". We'll pause here to emphasize the importance of saving the

wallet and highlight the workaround for a problem that occurs when saving the wallet for the first time.

At this point, you have created a wallet. You can choose Wallet/Save and select the $INST_TOP/certs/Apache

directory as the place to save. The next important step is to check the "Auto Login" box and then save the wallet

again. The reason for this double-step workaround is that if this is the first time you are creating a wallet and did no

create a default wallet directory, then attempting to save the wallet with "Auto Login" checked will result in the error

"Saving SSO wallet failed in: (blank)". Saving the wallet without "Auto Login" checked gives the opportunity to specify

directory to save to, but "Auto Login" is a requirement.


7/35

1/13/2015 Document 1425103.1


Saving the wallet without "Auto Login" checked creates the file "ewallet.p12":

> ls -l


Saving the wallet with "Auto Login" checked (after successfully saving it once without the check) creates the additiona

and necessary file "cwallet.sso":

> ls -l


-rw------- 1 appv1211 dba 7945 Aug 12 09:49 cwallet.sso

The AutoLogin feature allows the wallet to be read by the OS user that owns the wallet (typically applmgr) without

requiring an explicit password entry. This is required for EBS. You will continue to need the wallet password for all o

the upcoming steps that require modifications to the wallet.

3. Create a Certificate Request

With orapki, you can simply add a Certificate Request to the wallet created above using the following example which

we'll also/instead do via owm.

orapki wallet add \

-wallet . \

-dn "CN=mymachine.us.oracle.com,OU=ATG Specialty,O=Support,L=Denver,ST=Colorado,C=US"

-keysize 2048 \

-pwd welcome1

The dn directive specifies the Distinguished Name where:

CN = Common Name which can be a server (including domain) or an individual. I'vhidden my actual server name in this example.

OU = Organizational Unit

O = Organization

L = Locality or City

ST = State or Province (full name, do not abbreviate)

C = Country Code

The keysize parameter specifies the bit-length of the RSA private key (more on this later) and as before the -pwd

directive specifies the wallet password.

The equivalent step with the wallet manager is as follows and assumes the wallet manager is running and still has thwallet open from the previous step.

Select "Operations", then "Add Certificate Request". This brings up a form similar to the parameter list described

above for orapki.


8/35

1/13/2015 Document 1425103.1


Choose a keysize greater than 2048bits

The form for creating the certificate request shows a default keysize of 1024 bits, but you should choose 2048 or

higher. Starting January 1, 2014, the industry is requiring the use of 2048-bit key length on SSL certificates. This is

in compliance with US National Institute of Standards and Technology (NIST) Special Publication 800-131A. Per

NIST, the use of 1024-bit RSA keys is no longer applicable and 2048-bit keys should be implemented. According to

NIST, 2048-bit keys should be applicable until 2030. In October 2012, Microsoft is planning to release a new

service update that blocks RSA keys under 1024-bits on all of its Operating Systems. For more information, see:

Microsoft Security Advisory is available here http://technet.microsoft.com/en-us/security/advisory/2661254 .

Additionally, most certificate authorities are now rejecting Certificate Signing Requests for 1024 bit certificates.

Notice in the above picture that prior to completing the Create Certificate Request form the wallet shows a status of"Certifcate: [Empty]". As soon as you press [OK] on that form, the status will change to "Certificate: [Requested]" as

seen below to indicate that the wallet now has a valid CSR:
http://technet.microsoft.com/en-us/security/advisory/2661254


9/35

1/13/2015 Document 1425103.1


4. Export the Certificate Request

Once the Certificate Request has been created you will need to export it so you can submit the request to a Certifying

Authority. Via orapki, you can enter the following command being sure to substitute the parameter values with the

parameter values used to create the Certificate Request.

orapki wallet export \

-wallet . \

-dn "CN=mymachine.us.oracle.com,OU=ATG Specialty,O=Support,L=Denver,ST=Colorado,C=US" \

-request server.csr \

-pwd welcome1

Remember with this syntax that "-wallet ." refers to the wallet in the present working directory and that the

"server.csr" is the name of the file that will hold the contents of the certificate signing request and is somewhat

arbitrary. If orapki was successful it will say nothing, but the "server.csr" file will be created.

The equivalent step with the wallet manager is as follows.

Click the mouse cursor to highlight where it says "Certificate: [Requested]", then from the menu choose "Operations"

and then "Export Certificate Request". A dialog box will pop up requesting where to save the file and what to name it

The name is somewhat arbitrary, but it is common practice to name it after the server and with a ".csr" extension as

seen below. Note that the top line in this form is used for navigating to a path, whereas the bottom line is for

specifying the filename.


10/35

1/13/2015 Document 1425103.1


If you successfully exported the certificate, you will quietly notice the "Certificate request export successful" at the

bottom of the wallet manager screen. More importantly, the file as you named it will be in the directory you specified

SAVE THE WALLET

At this point you can exit the wallet manager, but do not forget to save the wallet. There is no reasonable way to

take an exported certificate signing request and force it back into a wallet. In the steps that follow you will submit

the exported certificate signing request file to a signing authority and that signing authority will reply with a user


11/35

1/13/2015 Document 1425103.1


certificate to import. You will NOT be able to import this user certificate unless the wallet is in a state of

"Certificate: [Requested]" with the identical certificate request that you submitted to the signing authority. If you

create a new certificate signing request, even with identical field parameters, it will not be the same as any

previously created CSR and therefore will not match the user certificate and owm will refuse to import it.

If this is the second time you are saving the wallet, then this should go very smoothly via the Wallet/Save menu

selection described in step 2. If you attempt to exit owm without saving, you are given just one, final chance. Click

[Yes]. Clicking [X] will close the wallet without saving just as surely as clicking [No].

5. Submit the Certificate Request to a Certifying Authority

The number of certificate authorities available to sign your certificate request are too numerous to mention. The pric

ranges from free to very expensive, depending on the sophistication of the certificate and other factors. Each

certificate vendor makes their own case on their website for why their certificate is the best. In this example, I've

chosen the familiar Verisign trial certificate because it is both free (for a short period) and common.

As a quick note, if you have just an internal test instance, you could use orapki to add a self-signed certificate. Self-

signing enables good SSL encryption, but offers essentially nothing to confirm the identity of the server. A certificate

purchased from a vendor is analogous to a state issued ID card, such as a driver's license. A self-signed certificate is

analogous to an ID card you made yourself that may be trusted by your friends, but not likely by anyone else. I onlymention this here as a side note for those that prefer to quickly create a certificate for free without involving a third

party. If you run the below command, the wallet will immediately have a certificate in ready status and you can skip

the step on submitting the CSR and importing the third party supplied certificates.

To add a self-signed cert run the following command, but change the DN list to your server's values. Skip this if you

are continuing with the steps to obtain a certificate from a vendor.

> orapki wallet add \

-wallet $INST_TOP/certs/Apache \

-dn "CN=myserver.us.oracle.com,OU=ATG Specialty,O=Support,L=Denver,ST=Colorado,C=US" \-keysize 2048 \

-self_signed \

-validity 365 \

-pwd welcome1

This self-signed example uses the same parameters explained previously, but also adds that the certificate is to be

valid for one year (-validity 365). This gives much more time than the typical 14 or 30 day trial certificate period.

If you are NOT going with a self-signed certificate, then submit your certificate to a signing authority. I've opted not

put screenshots for this section because the websites update their pages often and therefore screenshots become sta

almost immediately. For the remainder of this guide, I'm using the Verisign Trial Certificate (aka Norton, aka


12/35

1/13/2015 Document 1425103.1


Symantec) which is readily visible from their home page. The process for these typical websites starts with giving

contact information and then a form where you can either upload the CSR as a file or paste it directly into a given

field. When pasting, be sure to paste the entire contents of the file, including the Begin/End (for example):

-----BEGIN NEW CERTIFICATE REQUEST-----

MIICwzCCAasCAQAwfjELMAkGA1UEBhMCVVMxETAPBgNVBAgTCENvbG9yYWRvMQ8wDQYDVQQHEwZE

ZW52ZXMub3JhY2xlLmNvbTCCASIwDQYJKoZIIxEDAOBgNVBAoTB1N1cHBvcnQxFjAUBgNVBAsTDU

GGRjb2xsMTIxeGUudXMub3JhY2xlLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEB

ALunGNjzWoXteHJK6Xnddp2BHtjZxrvaRdj3L1YB9nokyCHJQykpqbOWehz/Ft1jzi7HkBat6BjO

34lBl33msse/gWMQ8bb0+tQgFEfBKJ5GxhKR/Fh5G6sezAWaKteesexANEkqh91nfQrbF7fDrgY+ylLiUUVBH349 This is just an example to show what a CSR looks PGA6PMqsxzjNc

AZB4kJHuYiqC like, in general. This one is not entirely real. EBggt9dj+18n1

KYEKuAqSUZ4NMJG0CrZwCcyeLwtD6S9apwicHU0CAwEAAaAAMA0GCSqGSIb3DQEBBAUAA4IBAQAk

TKZYvVzWSH7AMXzo/WcWuDUx6bxuln1ujGtEwYBD33DfNDBos0kjJZ17c3aZ/fnHhfJAusZ6aiQu

6CKECCcgLaksidnM5sviGsEwdWHmxX8A+15/QqvDTinv8j/q/kpLTxODnZxEaYi8IrWKPsMC3z/j

EB93DJLN3sa5KcF9Qf5sBwkSecvWIjqPIrbAFDz2L5Djsr+DxrjIXhYAJ8YKn0fu5lYUQNebqxey

OkOSdYrj4KHz8V64OGf2dseTjqLGCXOTuuXcdSJRKuHbvBYDcoW1V/3Ug2flGroqxASzkZgCA1I1

U8dA1gGl97CbFdVv6O9n//gkMvGvPi/Osv6/

-----END NEW CERTIFICATE REQUEST-----

After submitting the certificate request, your certificate vendor should respond with an SSL certificate via e-mail fairly

quickly. Trial certificates generally come almost immediately, but production certificates generally take longer. Whileself-signed certificates enable data encryption, they do nothing to assure users of the legitimacy of a given website. I

contrast, production certificates (and trial certificates to a lesser extent) generally include a vetting process where the

certificate authority must verify the identification and other aspects of the website owner and certificate requestor.

The e-mail from the certificate authority should also explain that almost every certificate commonly issued today is an

EV (extended validation) certificate which requires both an intermediate and a root certificate to accompany your new

created server certificate. In the case of the Verisign Trial Certificate, there is a special "Test Root CA Certificate" an

a "Trial SSL Intermediate Certificate" that is different from the production certificates. For the server certificate (aka

"user certificate") to be imported, you must first import these lower certificates into the wallet as "trusted certificates"

This is illustrated below with an orapki example and a graphical owm example.

5. Import your Certificate to the Wallet

Given the typical example of the Verisign Trial certificate, there are a total of three certificates that need to be

imported into the wallet. The root and intermediate certificates will be imported into the wallet as trusted certificates

and the server certificate will be imported into the wallet as a user certificate. These certificates are downloaded

according to the instructions in the certificate vendor e-mail. Generally, the e-mail provides the server certificate in t

text of the e-mail and then provides links to the vendor website where the trial and intermediate certificates can eithe

be downloaded as a file or copy/pasted off the web pages. Therefore, the filenames for these certificates are entirel

arbitrary, but should be named sensibly.

I used the following:

TrialRoot.cerTrialIntermediate.cer

server.cer

To illustrate a point, here is an attempt to import the server certificate without the root and intermediate:



-user_cert \

-cert server.cer \


13/35

1/13/2015 Document 1425103.1


-pwd welcome1

orapki replies with:

Could not install user cert at server.cer.

Please add all trusted certificates before adding the user certificate

The following sequence does work (orapki replies with no message when all is well):



-trusted_cert \

-cert TrialRoot.cer \

-pwd welcome1



-trusted_cert \

-cert TrialIntermediate.cer \

-pwd welcome1



-user_cert \

-cert server.cer \

-pwd welcome1

You can verify the successful import of the certificates into the wallet by using the following. Note the lack of

"Requested Certificates", the presence of the "User Certificate", and the additional "Trusted Certificates" (example

reformatted for clarity):

> orapki wallet display -wallet $INST_TOP/certs/Apache

Requested Certificates:

--

User Certificates:

Subject: CN=myserver.us.oracle.com,

OU=Terms of use at www.verisign.com/cps/testca(c)05 ,

OU=ATG Specialty,

O=Support,

L=Denver,

ST=Colorado, C=US

Trusted Certificates:

Subject: CN=VeriSign Trial Secure Server Root CA - G2,

OU=For Test Purposes Only. No assurances.,

O=VeriSign\, Inc.,

C=US

Subject: CN=VeriSign Trial Secure Server CA - G2,

OU=Terms of use at https://www.verisign.com/cps/testca (c)09,

OU=For Test Purposes Only. No assurances.,

O=VeriSign\, Inc.,

C=US
http://www.verisign.com/cps/testca(c)05https://www.verisign.com/cps/testca


14/35

1/13/2015 Document 1425103.1


The equivalent step with the wallet manager is as follows:

Start owm and open the wallet as before and select "Operations", "Import User Certificate". If "Import User

Certificate" is grayed out, that indicates that there is no certificate signing request as indicated by "Certificate[Requested]". If you are following these steps in order, this option should be available.


15/35

1/13/2015 Document 1425103.1


You will be given the option of either pasting the certificate or selecting a file that contains the certificate. If you wish

to select a file that contains the certificate, note that the wallet manager dialog will look on the server where owm is

running (not your local PC) so therefore you must take the extra step of copying/ftping your certificate to the server.

The "Import Certificate" selection box can be tricky. If you know the complete path and name of the certificate file,

you can enter this on the bottom line under "Enter file name". If you need to browse for the file, you must use the to

two lines and the Folders/Files selection boxes.

Similar to the orapki example, you can import the trusted certificates first, but the wallet manager is more forgiving

than orapki. After selecting the server certificate for import as a user certificate, the following error is seen:

If you click [Yes], you can neatly import the first trusted certificate (TrialIntermediate.cer in this example) using the

similar file selection dialog as above. The server certificate is an EV (extended validation) certificate, so immediately

you will see the prompt again to import "CA certificate now", but notice in the background that the first CA certificate

(TrialIntermediate.cer in this example) was imported:


16/35

1/13/2015 Document 1425103.1


At this point, click [Yes] once again and import the remaining certificate (TrialRoot.cer in this example). This results

"Certificate: [Ready]" and both of the CA certificates listed in the trusted certificates section.

As before, be certain to save the wallet with Auto Login enabled.


17/35

1/13/2015 Document 1425103.1


6. Copy the Apache Wallet to the OPMN Wallet

As applmgr:

> cp $INST_TOP/certs/Apache/*wallet* $INST_TOP/certs/opmn

7. AutoConfig

As a quick test, we'll implement SSL via AutoConfig and then continue with the rest of the setup afterwards for reason

that will be made clear later. While the Oracle Applications Manager (OAM) context editor is the recommended metho

for updating the EBS configuration, the vast majority of customers simply edit the AutoConfig context file directly. It i

always a good practice to make a backup copy of the context file before editing because the XML syntax can be tricky

and a single, misplaced character can make the file entirely meaningless to the AutoConfig engine.

In this example, I'm taking the original web entry URL of http://myserver.us.oracle.com:8010 and changing it to

https://myserver.us.oracle.com:4443. The changes are documented in Note:376700.1 with the following matrix anddetailed below:

Variable Non-SSL Value SSL Value

s_url_protocol http https

s_local_url_protocol http https

s_webentryurlprotocol http https

s_active_webport same as s_webport same as s_webssl_port

s_webssl_port not applicable default is 4443

s_https_listen_parameter not applicable same as s_webssl_port
http://dcoll121.us.oracle.com:8010/


18/35

1/13/2015 Document 1425103.1


s_help_web_agent url constructed with http protocol ands_webport

url constructed with https protocol ands_webssl_port

s_login_page url constructed with http protocol and

s_webport

url constructed with https protocol and

s_webssl_port

s_external_url url constructed with http protocol and

s_webport

url constructed with https protocol and

s_webssl_port

The original and edited context file ($CONTEXT_FILE) parameters, in detail, were:

ORIGINAL: http

CHANGED: https

ORIGINAL: http

CHANGED: https

ORIGINAL: http

CHANGED: https

ORIGINAL: 8010CHANGED: 4443

ORIGINAL: 4443

CHANGED: 4443

ORIGINAL: 4443

CHANGED: 4443

ORIGINAL:

CHANGED:

ORIGINAL: http://myserver.us.oracle.com:8010/OA_HTML/AppsLogin

CHANGED: https://myserver.us.oracle.com:4443/OA_HTML/AppsLogin

ORIGINAL: http://myserver.us.oracle.com:8010

CHANGED: https://myserver.us.oracle.com:4443

There are other noteworthy context entries that are NOT changed because the defaults are generally assumed. Thes

assumed values are why the web tier wallet was created in the directory that it was:

/space/r1211/inst/apps/V1211_myserver/certs

/space/r1211/inst/apps/V1211_myserver/certs/Apache/cwallet.sso


19/35

1/13/2015 Document 1425103.1


The following is used when the reverse proxy is SSL, but the underlying web tier is HTTP. The example for this

document was without a reverse proxy and with the web tier as SSL so therefore the sslterminator must remain as '#

#

After these changes, stop the web tier services, run AutoConfig, and then start the web tier services once again.

For example:

> cd $ADMIN_SCRIPTS_HOME

> adstpall.sh apps/apps

> adautocfg.sh

> adstrtal.sh apps/apps

Client Configurations

Introduction

At this point, it will seem that the SSL setup is complete because most functionality will work. This is a common

mistake that returns to haunt the instance later. I'm referring to this section as "client configurations" and start with

the configuration of the client browser. The client browser is the most obvious case of a client connecting to the web

entry URL. The less obvious client connections come from within the EBS instance.

It is very common for the various bits of functionality within EBS to make URL calls to the web entry URL. For examp

the java based Workflow mailer on the concurrent manager tier may use the JDK (Java Development Kit) on the

concurrent manager tier to make the HTTPS URL call to retrieve framework content for workflow e-mails via the web

entry URL. With iRecruitment, URL calls may be generated from the web tier JDK and also from the database via the

OWA_UTIL package. Therefore, it is just as necessary to populate the trusted certificate store of the JDKs and the

database as it is to populate the trusted certificate store of the client browser. The JDK and database client

configuration dissertation follows the client browser configuration dissertation.

On a related point, if you implement SSL with a paid-for certificate, the client browser is likely to already have the roo

and intermediate certificates that work with the server certificate just installed and therefore the initial connection fro

the browser will simply work whereas client connections from the JDK or the database will not. The trial certificate is

a good example of what happens when a nonstandard certificate is used and illustrates this point further.

Client Browser Configuration

On initial connection with the HTTPS web entry URL presenting a trial certificate, most browsers will immediately wan

to reject the connection because the connection is not trusted. As browser versions vary, the appearance of these

screens will differ, but a recent Mozilla Firefox example and Internet Explorer example appears as the following.

For example, a typical screen from Mozilla Firefox:


20/35

1/13/2015 Document 1425103.1


Similarly, the equivalent Microsoft Internet Explorer example is:


21/35

1/13/2015 Document 1425103.1


Mozilla Firefox Security Exception

With the Mozilla Firefox example, you can simply click on "Confirm Security Exception" and choose to permanently sto

the exception.

Before accepting the exception, this is a good time to introduce the rather excellent certificate viewer available via the

View button which will be used later:


22/35

1/13/2015 Document 1425103.1



23/35

1/13/2015 Document 1425103.1


From the General tab, you can see that this is indeed the certificate that was just installed. From the Details tab, you

can see the certificate chain is comprised of the "Verisign Trial Secure Server Root CA - G2", the "Verisign Trial Secur

Server CA - G2", and the named server certificate. There is also the Export button which can be used to create three

files from each of the three certificates that are very similar to the three files that were installed earlier into the web

tier wallet. This is very useful later because these files can be imported into the JDK and database trusted certificate

stores.

Microsoft Internet Explorer Security Exception

With Internet Explorer, the concept is the same, but the navigation differs. In this case you DO want to "Continue to

this website (not recommended)" since that is the only way to proceed to the login page. The URL line will be painte

red and there will continue to be a warning as shown below. You can click on where it says "Certificate Error" to view

the certificates similar to the earlier illustration:


24/35

1/13/2015 Document 1425103.1


With the Internet Explorer certificate viewer, you can also see the chain of certificates and here (above screenshot) it

is highlighted that the problem certificate is the root trial certificate. Other certificates for other vendors may vary, bu

the trial certificate from Verisign is a special one that is not included in most browser certificate stores. If you click o

the offending certificate, you can view it and click the button to install the certificate via the certificate import wizard

and following the defaults. The next time you visit the EBS login page for this instance (after restarting the browser),

you will no longer see a certificate error because the certificates presented are now trusted.

It was important to illustrate the concept of importing trusted certificates twice because it illustrates the client

concepts in the next section where we'll be importing these same certificates into the JDK and the Database wallet.

Retrieving the Public Facing SSL Certificates Using the Client Browser

Introduction

As described earlier in this document, there were three files returned from the certificate authority that were importe

into the web tier's wallet:

TrialRoot.cer

TrialIntermediate.cer

server.cer

If you still have these files (the actual filenames are arbitrary) then you can skip this step, but as alluded to earlier it is

quite common to need these files for the JDK and the database wallet and not have them. This is especially common

the SSL is being handled by an SSL offloader such as a hardware load balancer controlled by a division of a large

corporation different from the division that handles the EBS instance.

If you do not have these files, they are easily retrieved. When a browser (or any SSL client) connects to an SSL URL,


25/35

1/13/2015 Document 1425103.1


the following general sequence of steps occur:

1. The browser requests that the web server identify itself.

2. The server sends the browser a copy of its SSL Certificate.

3. The browser checks whether it trusts the SSL Certificate. If so, it sends a message to the server. (If not, the SSconnection fails.)

4. The server sends back a digitally signed acknowledgement to start an SSL encrypted session.

5. Encrypted data is shared between the browser and the server

Step 2 is the reason you can use the browser to recover the three original files (more or less files if you are usingsome other certificate). Step 3 is the reason the certificates had to be accepted in the browser's trusted certificate

store and why the JDK and database wallet will also need the certificates.

Retrieving the Certificates using Mozilla Firefox

Just after invoking the URL to connect to the SSL enabled EBS instance, the Mozilla Firefox browser will indicate the

acceptance of the SSL certificate presented by adding a padlock icon to the URL in the address bar (location bar).

Clicking the mouse on that padlock will display the window with the button for [More Information...]. The screen

following that display the rather excellent certificate viewer illustrated earlier. From this certificate viewer, you can

save each one of the three certificates by using the [Export] button.

Highlight each one of the three certificates, one by one, and export them as X509 PEM certificate format. Once again

the file names are arbitrary, but choose names that are meaningful.


26/35

1/13/2015 Document 1425103.1


Retrieving the Certificates using Internet Explorer


27/35

1/13/2015 Document 1425103.1


Just after invoking the URL to connect to the SSL enabled EBS instance, the Internet Explorer browser will indicate the

acceptance of the SSL certificate presented by adding a padlock icon to the URL in the address bar (location bar).

Clicking the mouse on that padlock will display the window with the hyperlink to "View Certificates" which will thenbring up the Internet Explorer version of the certificate viewer. This is substantially more cumbersome than the Mozi

Firefox certificate viewer.


28/35

1/13/2015 Document 1425103.1


Clicking on the [Copy to File] button will start the Certificate Export Wizard. Use this to save the server certificate in

X509 Base-64 format.

To retrieve the Intermediate and Root certificates, navigate back to the main certificate viewer window and click the

"Certificate Path" tab. If you highlight the server certificate, the [View Certificate] button will gray out and this is why

the previous step was used to retrieve it. If you highlight the remaining Intermediate or Root Certificate, the [View

Certificate] button will be enabled. Clicking on the [View Certificate] button will open a new instance of the certificate

viewer that is specific to the certificate you highlighted. As before, click the Details tab, click the [Copy to File] buttonand navigate through the Certificate Export Wizard to export the certificate.


29/35

1/13/2015 Document 1425103.1



30/35

1/13/2015 Document 1425103.1


Repeat these steps for each certificate.

Importing SSL Certificates into the JDK's Trusted Certificate Store

At this step, based on the initial section where the certificate files were created or the previous section where the

certificate files were recreated, you will have three certificate files representing the server certificate, the intermediat

certificate, and the root certificate. This is the typical certificate chain provided by the Verisign Trial certificate which

used as the example in this document. Self-signed and internally signed certificates will have more or less certificates

in the chain. Nevertheless, all certificates should be imported into the JDK. Regardless of the number of certificates,

the concept of importing the certificates into the JDK is the same.

Continuing with the example of the Verisign Trial Certificate, there are/were three certificates which were FTP'd to th

appstier (application tier) server:

TrialRoot.cer


server.cer

Within EBS, the JDK is often called upon to act as an SSL client, similar to the way the browser acts as an SSL client

when connecting to the EBS instance. The reason for this is that it is very common for java based product functionali

to make URL calls to the same web entry point the client browser connected to. For the JDK to successfully make thi

SSL connection, it is similar to the client browser in that it must have a store of trusted certificates. The JDK is

different from the browser in that it will not interactively act with the user to accept certificates. These certificates

must be loaded into the JDK's trusted certificate store before the SSL connection is attempted. If the certificates are


31/35

1/13/2015 Document 1425103.1


not in place, the SSL connection will fail and that failure will not be readily apparent on the user interface.

The default certificate store for the JDK on each EBS applications tier is $AF_JRE_TOP/lib/security/cacerts and the

default password for cacerts is "changeit". The key and certificate management utility for managing public/private ke

pairs and certificates is the keytool command ($AF_JRE_TOP/bin/keytool). To import each of the three certificates in

this example, the keytool command is run three times:

For example:

keytool -import -alias TrialRoot \-file /home/applmgr/mycerts/TrialRoot.cer \

-trustcacerts -v -keystore $AF_JRE_TOP/lib/security/cacerts

keytool -import -alias TrialIntermediate \

-file /home/applmgr/mycerts/TrialIntermediate.cer \


keytool -import -alias Servername \

-file /home/applmgr/mycerts/server.cer \


Piece by piece, the keytool command string we're using means: keytool - The certificate management utility for Java

($AF_JRE_TOP/bin/keytool).

import - Import the specified certificate into the specified keystore

($AF_JRE_TOP/lib/security/cacerts for EBS).

alias - In the case of EBS, this name is arbitrary, but must be differen

from any other alias entry in the keystore.

file - the name of the certificate file (X509 Base64 PEM format) to

import

trustcacerts - import the certificate file as a trusted certificate such as fro

a certificate authority

v - verbose show the user detailed output

keystore - the name of the keystore in which to import the trusted

certificate

The following example is for the TrialRoot certificate, but be sure to repeat this for all certificates in the chain

(TrialRoot.cer, TrialIntermediate.cer, Server.cer in this example). Additionally, you should repeat this process for eac

web tier JDK and each concurrent manager node JDK (in case the concurrent manager node is not on the same

appstier as the web node):

> ls -l

total 12

-rw-r--r-- 1 appv1211 dba 2009 Sep 23 06:40 server.cer

-rw-r--r-- 1 appv1211 dba 1964 Sep 23 06:41 TrialIntermediate.cer-rw-r--r-- 1 appv1211 dba 1566 Sep 23 06:39 TrialRoot.cer

> which keytool

/space/r1211/apps/tech_st/10.1.3/appsutil/jdk/jre/bin/keytool

> ls -l $AF_JRE_TOP/lib/security/cacerts

-rw-r--r-- 1 appv1211 dba 64251 Jun 5 2011

/space/r1211/apps/tech_st/10.1.3/appsutil/jdk/jre/lib/security/cacerts

> keytool -import -alias TrialRoot \

-file /home/applmgr/mycerts/TrialRoot.cer \



32/35

1/13/2015 Document 1425103.1


Enter keystore password: changeit

Owner: CN=VeriSign Trial Secure Server Root CA - G2, OU="For Test Purposes Only. No

assurances.", O="VeriSign, Inc.", C=US

Issuer: CN=VeriSign Trial Secure Server Root CA - G2, OU="For Test Purposes Only. No

assurances.", O="VeriSign, Inc.", C=US

Serial number: 168164a428ca12dfab12f19fb1b93554

Valid from: Tue Mar 31 18:00:00 MDT 2009 until: Sat Mar 31 17:59:59 MDT 2029

Certificate fingerprints:

MD5: E0:19:F5:FC:C0:9A:13:0E:38:B7:BF:0D:02:40:D3:C2

SHA1: 51:51:B8:63:8A:4C:1F:15:54:56:ED:37:C9:10:35:CA:D3:01:B9:36

Signature algorithm name: SHA1withRSA

Version: 3

Extensions:...

Trust this certificate? [no]: yes

Certificate was added to keystore

> ls -l $AF_JRE_TOP/lib/security/cacerts

-rw-r--r-- 1 appv1211 dba 65400 Oct 5 12:26

/space/r1211/apps/tech_st/10.1.3/appsutil/jdk/jre/lib/security/cacerts

Enter keystore password:changeit - unless you did change it

If you are prompted to "Enter keystore password", the default password for an Oracle installed JDK is "changeit".

If that password does not work, it is reasonably simple to delete/move the existing keystore and create a new

keystore with a password of your choosing.

> mv $AF_JRE_TOP/lib/security/cacerts $AF_JRE_TOP/lib/security/cacerts.old

Then, when you run either of the above keytool commands to import a certificate for the first time, a new cacerts

will be created and you will be prompted for a password of your choice instead of being asked for just the current

password:

Enter keystore password: whatever

Re-enter new password: whatever

Repeat the import for all certificates in the certificate chain and for each JDK.

The best way to be certain that the JDK has all of the certificates necessary to complete the SSL negotiation with your

web entry URL is to simply separate what that URL presents into separate SSL certificates as described above

(Retrieving the Public Facing SSL Certificates Using the Client Browser) and then import each one into the JDK. It is

rarely or never a problem to have too many certificates, but always a problem to have too few. Furthermore, in a

typical EBS installation it is common to have more than one appstier (applications tier). Each appstier will have its ow

JDK and each JDK should have a complete set of trusted certificates.

You can review what is already in the keystore with the following command.

> keytool -list -trustcacerts -v -keystore $AF_JRE_TOP/lib/security/cacerts


33/35

1/13/2015 Document 1425103.1


You can optionally add a grep to look for specific SHA1 certificate fingerprints, such as the VeriSign Trial Secure Serve

Root CA imported above, to confirm they are in the keystore:

> keytool -list -trustcacerts -v -keystore $AF_JRE_TOP/lib/security/cacerts -v | grep "SHA1:" |

grep -E '51:51:B8:63:8A:4C:1F:15:54'

Enter keystore password: changeit

SHA1: 51:51:B8:63:8A:4C:1F:15:54:56:ED:37:C9:10:35:CA:D3:01:B9:36

For further information on the keytool utility, see:

http://docs.oracle.com/javase/6/docs/technotes/tools/solaris/keytool.html

Creating a Database Wallet and Importing Trusted SSL Certificates

For reasons similar to the above JDK explanation, the database is often called upon to act as an SSL client similar to

the way the browser acts as an SSL client when connecting to the EBS instance. The most common method is to hav

the product code make use of the OWA_UTIL package and make a URL call from PL/SQL. If this URL starts with http

then the database will have to negotiate the SSL connection just like any SSL client browser and will therefore need a

set of trusted certificates in a private store. For the database, the private store of trusted certificates is the database

wallet. By default, this wallet does not exist at all so therefore there is no pre-existing set of common certificates

available by default. Instead, a database wallet must be created and then loaded with the specific certificates that ar

to be trusted. Similar to the case with the JDK, the complete chain of certificates presented by the URL being called

should be imported into the database wallet and these are the very same certificates that can be obtained using the

method described above under the heading "Retrieving the Public Facing SSL Certificates Using the Client Browser".

For EBS, the expected location for the database wallet is described by the profile option "Database Wallet Directory"

(FND_DB_WALLET_DIR) which is enabled only at the site level. This singular location is typically the database tier's

$ORACLE_HOME/appsutil/wallet directory.

For example, from sqlplus:

select fnd_profile.value('FND_DB_WALLET_DIR') from dual

FND_PROFILE.VALUE('FND_DB_WALLET_DIR')

-----------------------------------------------

/space/r1211/db/tech_st/11.1.0/appsutil/wallet

Continuing with the example of the Verisign Trial Certificate, there are/were three certificates which were FTP'd to th

dbtier (database tier) server which are needed in the common case where the database makes a URL call to the EBS

web entry point:

TrialRoot.cer


server.cer

1. Login to the database as the Oracle user and source the appropriate EBS environment. This is typically the only en

file in the database ORACLE_HOME directory and sets the $ORACLE_HOME and the PATH to the database wallet


34/35

1/13/2015 Document 1425103.1


manager (owm).

For example:

>orav1211:dc12a:/space/r1211/db/tech_st/11.1.0> ls *.env

V1211_dc12a.env

>orav1211:dc12a:/space/r1211/db/tech_st/11.1.0> . ./V1211_dc12a.env

> which owm/space/r1211/db/tech_st/11.1.0/bin/owm

> which orapki

/space/r1211/db/tech_st/11.1.0/bin/orapki

2. Confirm the value for the profile option "Database Wallet Directory" as above. If the wallet directory does not exis

create it.

> mkdir $ORACLE_HOME/appsutil/wallet

3. If you do not already have a wallet, the fastest way to complete this task is via the orapki utility illustrated in great

detail earlier.

Create your new wallet:

orapki wallet create \

-wallet $ORACLE_HOME/appsutil/wallet \

-auto_login

-pwd welcome1

Import the certificates into the new wallet as trusted:

orapki wallet add \


-trusted_cert \

-cert TrialRoot.cer \

-pwd welcome1

orapki wallet add \


-trusted_cert \

-cert TrialIntermediate.cer \

-pwd welcome1

orapki wallet add \


-trusted_cert \

-cert server.cer \

-pwd welcome1

There are two quick ways to now test the wallet, borrowed from Note:416619.1. The first is the very direct method

with manually entered parameters based on the values for this instance:


35/35

1/13/2015 Document 1425103.1

The parameter list for utl_http.request is:

URL: Web Entry URL, typically the value for the profile option "Applications Framework Agent"

Additionally, I've added a resume template file as something interesting to retrieve.

Proxy: Proxy profile options you may or may not have or need a forward proxy

Wallet Path: "Database Wallet Directory" profile option value

allet Password: This is the wallet password, such as the one chosen when the wallet was created.

For example:

select utl_http.request

(

'https://serverxxx.us.oracle.com:4443/OA_HTML/IRCRESUMEUK1.xsl',

null,

'file:/space/r1211/db/tech_st/11.1.0/appsutil/wallet',

'welcome1'

)

from dual

Another example is to automatically retrieve the value for the profile options, including the proxies. The URL is taken

directly as the site level value for "Applications Framework Agent", the proxy is a computed value based on the values

of the profile options "Applications Server-Side Proxy Host And Domain", "Applications Proxy Port", and "Applications

Proxy Bypass Domains" which identify the forward proxy that is likely the same as the one defined in the client browse

located on the same network. The wallet path is computed based upon the "Database Wallet Directory" described

earlier. The wallet password is computed here using an internal procedure. Within EBS, the wallet password is set

using the script $FND_TOP/patch/115/sql/txkSetWalletPass.sql. If you find that the hardcoded utl_http call works, bu

the version from EBS code does not, txkSetWalletPass.sql is likely the answer. The script is short and self-explanator

select UTL_HTTP.REQUEST

( url => fnd_profile.value('APPS_FRAMEWORK_AGENT')||'/OA_HTML/IRCRESUMEUK1.xsl',

proxy => hr_util_web.proxyForURL(fnd_profile.value('APPS_FRAMEWORK_AGENT')),

wallet_path=>'file:'||fnd_profile.value('FND_DB_WALLET_DIR'),

wallet_password=>fnd_preference.eget('#INTERNAL','WF_WEBSERVICES','EWALLETPWD','WFWS_PWD')

)

from dual

SUMMARY

This paper covered the implementation of SSL using a single EBS web tier using the Verisign Trial Certificate as an

example. This is version 1.0 of this paper. In upcoming releases, the author intends to cover topics such as expired

certificate renewal/replacement and common SSL setup tests. Customer comments and suggestions are certainly

welcome.

enabling ssl in oracle e-business suite release 12

Documents