Professional Documents
Culture Documents
Table of Contents
INTRODUCTION: What is Covered in this Document? ........................................................................................... 3
CHAPTER 1: SSL Overview ....................................................................................................................................... 4
What is SSL? .................................................................................................................................................................. 4
What is an SSL Certificate? .......................................................................................................................................... 4
SSL on WebLogic........................................................................................................................................................... 7
CHAPTER 2: Planning Steps (For First Time Install of SSL) ................................................................................. 8
Validate whether SSL should be Installed on WebLogic Server or Proxy/Load Balancer ..................................... 8
Determine what Type of Certificate to Install and which Certificate Authority to Use .......................................... 9
Does SSL Need Installed on Other PeopleSoft Components? .................................................................................. 10
CHAPTER 3: Steps to Install/Renew SSL Certificate on WebLogic .................................................................... 11
PART #1: Preparation Steps....................................................................................................................................... 11
PART #2: Create Certificate Request (CSR) ............................................................................................................ 13
PART #3: Import Signed Certificate into WebLogic Keystore ............................................................................... 15
PART #4: Configure WebLogic to use the New Certificate ..................................................................................... 19
PART #5: Validate the SSL Installation .................................................................................................................... 22
PART #6: Verify that PeopleSoft Database Contains the Root/Intermediate CA for your Server Cert ............ 24
APPENDIX A: SSL Terminology.............................................................................................................................. 25
APPENDIX B: Troubleshooting Tips ...................................................................................................................... 27
Failure Importing Certificate using pskeymanager import ............................................................................... 27
Failure Accessing PeopleSoft Application after Configuring SSL........................................................................... 28
APPENDIX C: Where to Find more Information .................................................................................................... 29
WHAT IS SSL?
SSL allows for encrypted communication between the browser and web server, thus providing a more secure
environment. When SSL is installed on the web server, the browser communicates with the web server using
https protocol (instead of http). In a nutshell, this is what occurs:
Browser sends request to web server for secure page (this is done by specifying https in browser url
instead of http)
Web server sends back its public key
The browser validates the certificate was issued by a trusted certificate authority (eg Verisign) and uses
the public key to encrypt all future requests to the web server.
SSL uses two keys
1. A private key: Installed on the web server
2. A public key known to everyone (eg browsers)
You need to install the SSL Certificate on your web server in order for the browser to communicate with the
web server using https.
The SSL certificate is signed by a Certificate Authority (CA) such as Verisign. This allows for the browser to
verify the identity of the site before sending private information. Note that you can use your own certificate
software which allows you to sign your own certificates.
Copyright 2012 Oracle, Inc. All rights reserved.
The SSL certificate has a root certificate associated with it, and also sometimes has an intermediate
certificate associated with it. The root and intermediate certificate are part of the public key and they identify
the certificate authority (eg Verisign) who signed your certificate.
The root and intermediate certificates, for well known Certificate Authorities such as Entrust and Versign, are
included in most web browsers. If you use your own certificate signing software, then users would be required
to install the root certificate, for your company, into their browser keystore.
You can easily view the SSL certificate for any secure site as follows:
a.
b.
c.
d.
In the above example, the certificate is issued to www.oracle.com and was signed by GeoTrust.
e. By clicking on the Certification Path tab, you can see the entire certificate chain including root
certificate, intermediate certificate(s) (if there is one) and the server certificate. For example, the
certificate tab for above certificate shows the following:
In this example, we see that there is a root certificate called GeoTrust Global CA and an
intermediate certificate called GeoTrust SSL CA, and the actual server certificate issued to
www.oracle.com
SSL ON WEBLOGIC
When you create a WebLogic domain in a PeopleSoft environment, by default, it configures both an http and
https port. The https port is configured to use a demo certificate. If you choose to use SSL on the WebLogic
server, you will need to replace the demo certificate with a valid SSL certificate (as described in Chapter 3:
Steps to Install/Renew a Certificate on WebLogic)
The My Oracle Support SSL Information Center contains links to many Knowledge Documents pertaining to
installing, configuring and troubleshooting SSL on WebLogic:
Doc# 1549157.2: Information Center: SSL on PeopleSoft Web Servers for PeopleTools 8.5x
In this example, there are no load balancers or proxy servers installed in front of the WebLogic server. So if
you are installing SSL, you will need to install the SSL certificate on the web server (as per instructions in
Chapter 3)
In this example, SSL is terminated at the load balancer. So you have encryption between the browser and load
balancer (which is typically the highest area of vulnerability). But there is no encryption from the load balancer
to web server (which is usually behind a firewall). This is the most common SSL configuration in environments
where there is a load balancer or proxy installed in front of the WebLogic server.
If you use this configuration, then there is no need to install a certificate on your Web server.
In this example, SSL is installed on both the load balancer and the web server. So the information is encrypted
all the way from the users browser to the web server. This configuration is typically used only by companies
who have a strict security requirement that https be used everywhere.
If you use this configuration, you will need to install SSL on the load balancer and the web server. But note that
you could use the same certificate for both the Load Balancer and the WebLogic Server(s). See Document
1087154.1 on how to copy an SSL certificate from an external device (such as load balancer) to WebLogic.
REN Server: If using this component, you are required to use https if you are accessing the PeopleSoft
application using https. See Document 1177643.1: Master Note for How to Configure SSL on REN Server
Report Server: If configuring SSL, refer to Document 617697.1: How to Configure HTTPS for Report
Distribution?
Integration Gateway: Refer to Document 1488269.1:How to enable PeopleTools 8.4x-8.5x Application Server to
use https Integration Gateway
Portal/Content Configuration: If you are using Enterprise Portal with other PeopleSoft applications, refer to
Document 784325.1:Content Provider Pagelet Shows "Unable To Get Document" Error On Portal Home Page
Using SSL
Note that the primary purpose of this document is to provide details on installing SSL on your WebLogic server, therefore
there is no in-depth coverage of other components. But we do want to make note of this since you may need to review
other components when preparing to install SSL on your web server.
If you have further questions and the information below does not help, then please open a Service Request for the
component you need help with (eg REN Server, Report Server, Integration Gateway, Portal)
10
11
certificate when you are ready (and go back to the old certificate in the event there are issues with the
renewed certificate). Below are details on each approach:
If using a new alias name: Decide what alias name you will use for the renewed certificate. We
recommend you tack the year to the alias name, for the renewed certificate. So for example, if your
current alias is called PSOFTSVR, then call the new certificate PSOFTSVR2013. (dont put any
spaces in the name).
Note that there is no harm in leaving the old certificate in the keystore, even after you install the
renewed certificate. But if you want to delete it at a later date, you are welcome to do so using
pskeymanager delete command. But be sure to back up pskey file before doing this!
If using the same alias name:
a. Backup up the pskey file (as per step #2 above)
b. Delete the existing alias:
i. cd <PS_CFG>/webserv/<DOMAIN_NAME>/piabin
ii. pskeymanager delete (use ./pskeymanager.sh delete for Unix/Linux)
iii. Respond to prompts to delete the alias
iv. If you make this change directly in the production server, then you will need to
temporarily restore the old pskey file in the event that you need to restart the web server
before you have imported the renewed certificate into the keystore. This is necessary
because the webserver reloads the contents of pskey each time it is restarted.
12
13
6. Back up the pskey keystore file: Note that when you create the certificate request, a unique entry (called private
key) is stored in the pskey keystore file. It is very important to NOT lose this entry, as the signed certificate must
match up to the private key/certificate request that was submitted to the Certificate Authority. If you accidently
overwrite the private key entry, it cannot be recovered and you have to start over. So this step is very important and
we strongly encourage you to backup the keystore file. The file is located in:
<PS_CFG>/webserv/<DOMAIN_NAME>/piaconfig/keystore/pskey
So perhaps you could make a copy called pskey-after-CSR-request
7. Submit the request to your Certificate Authority (CA): Send the request to your CA. Note that you can use an
external CA (eg Verisign, Entrust, Thawte, GoDaddy) or if your company has its own certificate signing tool, you can
sign your own certificate. After the certificate has been signed, you can move on to Part#3 (Import Signed Certificate
into WebLogic keystore)
14
Note: If you see a message like this (below) indicating there isnt enough info to verify the certificate, then you
will not be able to extract out the chain, as the root/intermediate(s) arent installed on your desktop. If this
happens, then assume that the Certificate Authority provided you the proper root and intermediate(s) and
move on to step #3
c.
Next, go to the tab titled Certification Path. You will see the root certificate, intermediate certificate(s) (if
there are any) and the server certificate.
In the example below, the certificate has a root (VeriSign), an intermediate (VeriSign Class3 International
Server CA G3) and the actual server certificate (issued to *.oracle.com)
15
d. Now we are going to extract the root and intermediate certificate. Well start by extracting the root certificate
(which is the very top certificate). Do this as follows:
i.
Double-Click on the top certificate (Verisign) in this example
ii.
This will launch another window showing the root certificate. Example:
iii.
iv.
v.
Click Next
When prompted for format choose Base-64 encoded
16
vi.
vii.
viii.
ix.
x.
Click Next
When prompted for file name, enter root.cer (or whatever you wish to call the file)
Click Finish then Ok
At this point, the root certificate is in a file called root.cer
If you have intermediate certificate(s) repeat step d., but this time double-click on the second certificate
which is the intermediate certificate and extract it to file intermediate.cer. (if there are two intermediate
certificates then youll need to repeat yet again to extract the other intermediate certificate).
At the end of this step, you should know how many root and intermediate certificates the server certificate is using
and each certificate should be in a separate file
3. Create a Chain file which will contain the server certificate, root certificate and intermediate certificate(s) (if
there are any) into a single file
Using a text editor (eg Notepad or WordPad), create a single file that contains all of the certificates. The file should
contain the server certificate followed by intermediate certificate (if there is one) followed by root certificate. It is
very important to list the certificates in the right order.
If you have a server certificate, one intermediate certificate and a root certificate, the file will look something like this:
-------BEGIN CERTIFICATE--------dfsfsdfdf
sfsdfwehdfhdf <---------server certificate
dgdfgfgfdg
--------END CERTIFICATE-----------------BEGIN CERTIFICATE--------hghjgfjgj
sfsdfwejjhdfhdf <---------intermediate
dgdfgiuiyuiuiyufgfdg
--------END CERTIFICATE-----------------BEGIN CERTIFICATE--------dfsfsmbvmvbmdfdf
sfsdetetrtyrfwehdfhdf <---------root CA
dgdfgnbnbvnvbfgfdg
--------END CERTIFICATE-----------
If you have a server certificate and a root certificate, the file will look something like this:
-------BEGIN CERTIFICATE--------dfsfsdfdf
sfsdfwehdfhdf <---------server certificate
dgdfgfgfdg
--------END CERTIFICATE-----------------BEGIN CERTIFICATE--------dfsfsmbvmvbmdfdf
sfsdetetrtyrfwehdfhdf <---------root CA
dgdfgnbnbvnvbfgfdg
--------END CERTIFICATE-----------
Make certain there are no extra carriage returns at beginning or end of the file! If there are, the import will fail!
4. Run pskeymanager import to Import the Root Certificate and any Intermediate Certificate(s):
a. Go to a command line prompt on the web server.
b. cd <PS_CFG>/webserv/<DOMAIN_NAME>/piabin
c. Run command pskeymanager import (for Unix/Linux use ./pskeymanager.sh import)
d. When prompted for an Alias, enter anything, such as RootCA
e. When prompted for the name of the certificate file, enter the name of the root certificate file (that you created
in step#2 above)
f. If asked if you want to trust this file, respond yes
Copyright 2012 Oracle, Inc. All rights reserved.
17
g. If you have an intermediate certificate, repeat above steps (youll need to use a different alias name such as
IntermediateCA. If you have multiple intermediate certificates, then youll need to repeat the import for
each of the intermediate certificates
Note: The above step is typically not necessary. But we have found some situations where it is necessary to have the
root/intermediate certificates imported into the keystore as separate entries. So we suggest you complete the above
step just in case it is needed in your environment. It definitely does no harm to import these entries (even if they arent
needed)
5. Use pskeymanager import to import the Certificate Chain:
a. Go to a command line prompt on the web server
b. cd <PS_CFG>/webserv/<DOMAIN_NAME>/piabin
c. Run command pskeymanager import (for Unix/Linux, use ./pskeymanager.sh import)
d. When prompted for an Alias enter the same alias you specified when you created the CSR (in Part#1)
e. When prompted for the name of the certificate file, enter the name of the file created in step #3 above
f. When prompted for the key password, enter the password you specified when you created the CSR (in
Part#2)
g. If asked if you want to trust this file (eg "...is not trusted. Install reply anyway?"), respond yes.
h. If the install is successful, you will receive message Certificate reply was installed in keystore
If you receive any errors, then please refer to Appendix B of this document (see section Failure Importing
Certificate using pskeymanager import)
6. Validate keystore entry: This step is optional, but if you wish to view the new certificate entry in the WebLogic
keystore, you can do so using this command:
pskeymanager list verbose alias peoplesoft (replace peoplesoft with your alias name)
The above command will show detailed information for the certificate that you imported. The beginning of the output
will look something like this:
Alias name: peoplesoft
Creation date: May 20, 2013
Entry type: PrivateKeyEntry
Certificate chain length: 2
Certificate[1]:
Owner: CN=peoplesoft.oracle.com, OU=Oracle Support, O=Oracle, L=Pleasanton, ST=California, C=US
Issuer: CN=PeopleTools TEST root CA, DC=peoplesoft, DC=com, OU=PeopleTools Development, O=PeopleSoft Inc,
L=Pleasanton, ST=CA, C=US
Serial number: 364c9410000000001f6d
Valid from: Mon May 20 09:54:10 PDT 2013 until: Tue May 20 10:04:10 PDT 2014
18
f.
In the bottom portion of the page, you will need to do the following:
i. Validate that the Custom Identity Keystore field and Custom Trust Keystore field are set to the correct
value (these values should NOT need to be changed, unless you chose to import certificate to a keystore
other than the standard pskey keystore delivered with PeopleSoft
ii. Enter the Keystore Passphrase in the Identity and Trust sections. Note that this is the keystore
password. In other words, it is the password you enter when using pskeymanager. Note that youll need to
enter the password in four fields:
19
20
21
2. If you get a browser pop-up warning and/or you get any sort of error such as cannot display the webpage then
please refer to Appendix B of this document (see section Failure Accessing PeopleSoft Application after Configuring
SSL). Note: if you are testing on a different environment than where you will ultimately be using the SSL certificate,
then it is ok if you get a browser pop-up warning as the certificate may not match to the host name in the browser url
3. If you are able to successfully access the PeopleSoft application, then this is a good indication that the certificate was
successfully installed. But you may still want to view the certificate just to validate that the application is using the
newly installed certificate. This can be done as follows:
a. Click padlock icon next to browser url (these instructions are for IE browser)
b. Then click view certificate hyperlink and you will be able to see the certificate details
c. You should then be able to verify certificate from these details. For example, the example below, this shows us
that WebLogic is using a certificate issued to driver-pc.us.oracle.com that is valid until 5/20/2014
22
4. At this point, your certificate is fully installed and configured. It you have installed the certificate in a test environment,
then when you are ready to go-live with the new certificate, do the following:
a. Copy pskey file from your test system back to production (so you will overwrite the old production pskey
file)
b. Then repeat Part#4 (Configure WebLogic to use the New Certificate) and Part #5 (Validate the SSL
Installation).
23
24
CA (Certificate Authority): This is the organization that issues (ie "Signs") your certificate.
Common CA's are VeriSign, Entrust, GoDaddy, Thawte. Note that you can also purchase a
certificate signing tool and sign your own certificates, therefore you are your own Certificate
Authority.
Chain Certificate: This term is sometimes used to refer to the entire SSL certificate which is
comprised of the following:
-Root Certificate
-Intermediate Certificate(s) (not all certificates contain an intermediate certificate)
-Server Certificate
Cipher Suite: a type of algorithm used to encrypt information. Refer to document 660309.1 if
you wish to change the cipher suites that your WebLogic server is using.
CN (Common Name) this is who the certificate is issued to. It needs to match to the hostname
that is used in the browser url when accessing the PeopleSoft application. So if you access the
PeopleSoft application using: https://peoplesoft.mycompany.com/ps/signon.html, then the
certificates common name is "peoplesoft.mycompany.com".
CSR (Certificate Signing Request): A CSR is a file sent to a certificate authority in order to apply
for a certificate. The CSR file includes information such as common name, organization, etc.
(you create the CSR using pskeymanager tool). The certificate is created from the CSR.
Demo Cert: This is a certificate that is delivered with the web server. It does not have a certificate
authority associated with it. You can use the certificate but browser will issue a warning stating
that it is not a trusted certificate. If you are unable to access the PeopleSoft environment using
the demo certificate, refer to document 1499938.1
Hash Algorithm: The algorithm used to secure the certificate. The most common is SHA. But
recently a new algorithm was released, called SHA2 (see doc 1225455.1 for more details)
Intermediate CA: This is an extra public key (in addition to the Root CA) to add an extra layer of
security. Most, but not all Certificate Authorities (CA's), issue an intermediate certificate. Some
CA's issue multiple intermediate certificates
One-way SSL: This is when a certificate is installed ONLY on the server (WebLogic). With oneway SSL, the server passes its certificate and CA chain to the browser. The browser trusts the CA
that issued the server certificate. 99% of our customers use One-Way SSL, however a few use
Two-Way SSL (see description of "Two-Way" SSL below)
Private Key: this is a unique entry placed in the keystore when a CSR is created. (it is then
signed using the public key from the Certificate Authority). The SSL private key is used to decrypt
the data passed over the SSL connection
Protocols: This refers to the encryption protocol. There are different protocols including SSLv2,
SSLv3, TLS1.0, TLS1.1 and TLS 1.2. The most common protocols are "TLS1.0" and "SSLv3".
25
SSLv2 is an older protocol and usually not used anymore. TLS 1.1 and 1.2 are newer protocols
and are supported starting with PeopleTools 8.53. If you wish to change the protocols your web
server is using, refer to document 664126.1
pskeymanager.cmd/sh: This is an Oracle "Wrapper Script" to the java keytool. Note that it is not
necessary to use pskeymanager and you can use keytool instead. However, you may find
pskeymanager more user friendly as it builds the arguments for the keytool command after
prompting you for necessary information. Also, pskeymanager is configured to use the pskey
file to store keystore information, which is a PeopleSoft standard.
Root Certificate (aka "Root CA" or "Trusted CA"): This is a public version of the certificate
containing only the public key. The Root certificate is the top most portion of the certificate chain.
It is provided by the Certificate Authority.
SAN (Subject Alternative Name): This is a type of certificate that allows you to assign multiple
host names to a single certificate. A SAN Certificate is also sometimes referred to as a "MultiDomain" certificate or "Unified Communications Certificates (UCC)". These certificates are
currently not supported in PeopleSoft.
Signature Algorithm (aka Signing Algorithm): This is the algorithm used to sign the certificate.
DSA and RSA are different types of signing algorithms. We support RSA.
SSL Handshake: This term is often used to refer to the communication between client (eg
browser) and server (eg WebLogic) at initial communication when the client and server exchange
information and server authenticates itself to the client.
Two-way SSL: this is when a certificate is installed on both the client (browser) and the server
(WebLogic). BOTH sides (ie browser and WebLogic server) pass certificates to each other to
establish communication. So both sides know the identity of each other from their respective
certificates It is extremely rare to see PeopleSoft customers use two-way SSL. Typically, oneway SSL is used.
Wildcard Certificate: A wild-card certificate allows you to secure multiple domains with the same
certificate. For example, you could use the same certificate for the following websites, by issuing
your certificate to *.mycompany.com
https://peoplesoft.mycompany.com
https://support.mycompany.com
https://sales.mycompany.com
Wildcard certificates were previously not supported with WebLogic, but they are supported starting
with WebLogic 10.3.6. Even though they aren't supported with older WebLogic versions, they
usually work fine in a PeopleSoft environment.
26
Verify there are no extra carriage returns at beginning or end of the chain file that you are importing.
Verify that the chain certificate contains files in the correct order:
o The server certificate should be at top of file
o The intermediate certificate should be next (if there is one)
o The root certificate should be at end of file
Verify that the signed certificate that you are importing, was created for the certificate request that you
sent to your Certificate Authority.
If the above information doesnt help, refer to the Troubleshoot tab of the SSL Information Center:
Doc# 1549157.2: Information Center: SSL on PeopleSoft Web Servers for PeopleTools 8.5x
There is a section in the Troubleshoot tab called Issues using pskeymanager script and it contains a list of
common errors, when using pskeymanager, and how to correct the problem.
27
If the above information doesnt help, refer to the Troubleshoot tab of the SSL Information Center:
Doc# 1549157.2: Information Center: SSL on PeopleSoft Web Servers for PeopleTools 8.5x
There is a section in the Troubleshoot tab titled Issues Starting and/or Accessing WebLogic After
Configuring SSL and it contains a list of all known problems that may result in problems accessing the
PeopleSoft application after configuring SSL.
28
29