| Oracle® Web Services Manager Deployment Guide 10g (10.1.3.3.0) Part Number E10298-01 |
|
|
View PDF |
| Oracle® Web Services Manager Deployment Guide 10g (10.1.3.3.0) Part Number E10298-01 |
|
|
View PDF |
Oracle Web Services Manager (Oracle WSM) components send requests to and receive responses from other Oracle WSM components. To secure these communications, you can configure Oracle WSM components to use Secure Sockets Layer (SSL), the most widely used transport-level data-communication protocol providing:
Authentication – Communication is established between two trusted parties.
Confidentiality – The data exchange is encrypted.
Message integrity – The data is checked for possible corruption.
This chapter includes the following sections:
Oracle WSM Policy Manager, Oracle WSM Monitor, and Web Services Manager Control are J2EE applications hosted by the OC4J server. Therefore, Oracle WSM supports all of the security methods supported on the Java platform. See Oracle HTTP Server Administrator's Guide for more information on how to integrate the Oracle HTTP Server and the OC4J server.
How you configure your transport security depends on the Oracle WSM package you installed and how the Oracle WSM components are managed. The following sections describe how to configure transport security based on the type of Oracle WSM installation and deployment.
Oracle SOA Suite Installation
If you installed Oracle WSM as part of the Oracle SOA Suite, then your OC4J server is managed by Oracle Process Manager and Notification Server (OPMN). See Oracle Containers for J2EE Security Guide for information about configuring OPMN to enable HTTPS and use SSL.
When you install the Oracle SOA Suite, there are two installation options. Depending on which option you selected, Oracle HTTP Server may or may not enabled, by default:
If you installed Oracle WSM using the Basic installation option, then Oracle HTTP Server is not enabled, by default.
If you installed Oracle WSM using the Advanced installation option, then Oracle HTTP Server is not enabled, by default. See Chapter 10, "Enabling SSL for the Oracle HTTP Server", in the Oracle HTTP Server Administrator's Guide, to enable Oracle HTTP Server.
See Oracle Application Server Installation Guide for Microsoft Windows or Oracle Application Server Installation Guide for Linux x86 for more information about the different Oracle SOA Suite installation options.
Standalone Oracle WSM Installation
If you installed Oracle WSM as part of the standalone package, how the OC4J Server is managed depends on which of the following installation options you selected:
In a Basic standalone installation, the OC4J server is not managed by OPMN.
In an Advanced standalone installation, Oracle WSM is added to an existing installation of the Oracle SOA Suite, and the OC4J Server is managed by OPMN.
See Oracle Web Services Manager Installation Guide for more information about the different standalone installation options.
Summary of Oracle WSM Deployment Types
Table 4-1 summarizes the different Oracle WSM installations and the deployment type. The installation package and the installation option determines the type of Oracle WSM deployment. In "Configuring the Truststore in SSL Connections" the deployment type determines how you configure your secure communications.
For any SSL connection between two components, the component that initiates the SSL connection acts as a client, and the client end of the connection must be configured to use a truststore. A truststore is a keystore file that includes the trusted certificate authorities that a client will implicitly accept during an SSL handshake. For example, if you want to secure a connection from Oracle WSM Gateway to Oracle WSM Policy Manager, then the gateway must be configured to use a truststore. This section describes how to configure the truststore file for clients in the following Oracle WSM deployments:
OPMN-managed deployments
Standalone OC4J deployments
See "Security Configuration Options" to determine which type of deployment you have installed.
OPMN-Managed Deployments
Perform this procedure if your Oracle WSM installation is managed by OPMN.
Modify the ORACLE_HOME/opmn/conf/opmn.xml file.
Add the JSSE truststore properties as system properties for the node with the XPath /opmn/process-manager/ias-component[id="default-group"]/process-type[id="home"]/module-data/category[id=start-parameters"]/data[id="java-options"] as follows:
-Djavax.net.ssl.trustStore=c:/mykeystore.jks
-Djavax.net.ssl.trustStorePassword=changeit
-Djavax.net.ssl.trustStoreType=JKS
Table 4-2 describes the JSSE truststore parameters.
Table 4-2 Description of JSSE Truststore Properties
| Parameter | Description |
|---|---|
|
|
Path to the location of the truststore. |
|
|
Password used to access the truststore. |
|
|
Type of file used for the truststore. Valid values are JKS or PKCS12. |
Standalone OC4J Server Deployments
Perform this procedure if you have installed Oracle WSM as part of the standalone package, with the Basic installation option.
Modify the ORACLE_HOME/owsm/scripts/oc4j.xml file.
Add the JSSE truststore properties as system properties to the ant target "oc4j.start" as follows:
<target name="oc4j.start" description="-->Start OC4J server">
<echo message="Starting stand-alone OC4J server in ${oc4J.j2ee.home}"\>
<java.jar="${oc4j.j2ee.home}\oc4.jar
fork="true"
failonerror='true"
dir="${oc4j.j2ee.home}">
<jvmarg value="-XX:MaxPermSize=128M"\>
<jvmarg value="-Xms512M\>
<jvmarg value="-Xmx512M"\>
<sysproperty key="http.nonproxyHosts" value="${noproxy.hosts}"/>
<sysproperty key="http.proxyHost" value=${proxy.host}"/>
<sysproperty key="http.proxyPort" value=${proxy.port}"/>
<sysproperty key="javax.net.ssl.trustStoreType" value="JKS"/>
<sysproperty key="javax.net.ssl.trustStore" value="c:\mykeystore.jks"/>
<sysproperty key="javax.net.ssl.trustStorePassword" value="changeit"/>
</java>
</target>
Table 4-3 describes the JSSE Truststore parameters.
Table 4-3 Description of JSSE Truststore Parameters
| Parameters | Description |
|---|---|
|
|
Type of file used for the truststore. Valid values are JKS or PKCS12. |
|
|
Path to the location of the truststore. |
|
|
Password used to access the truststore. |
Oracle WSM Gateway, Oracle WSM Policy Manager, and Web Services Manager Control are all J2EE applications on OC4J, and connections to them can be secured using SSL. The procedure below is an overview of how you secure these applications. For more information, see the chapter "SSL Communication with OC4J, in Oracle Containers for J2EE Security Guide.
To secure OC4J using SSL
Create the following file: ORACLE_HOME/j2ee/instance/config/secure-web-site.xml
The variable instance is the name of your Oracle instance.
Add the protocol="http" and secure="true" properties to the <web-site> element.
If connections to the Oracle WSM component pass through an Oracle HTTP Server, then the protocol must be set to Apache JServ Protocol (AJP). Add the protocol="ajp13" and secure="true" properties in the <web-site> element for these components.
Add the <ssl-config> element beneath the <web-site> element and define the keystore location and password, using the keystore and keystore-password attributes.
For example:
<web-site display-name="OC4J Web Site" protocol="http" port="636" secure="true" > <default-web-app application="default" name="defaultWebApp" root="/j2ee" /> <access-log path="../log/default-web-access.log" /> <ssl-config keystore="../keystore" keystore-password="welcome" /> </web-site>
For each Oracle WSM component that you want to enable with SSL, enter the <web app> entry. For example:
<web app application="policymanager"...>
<web app application="gateway" ...>
<web app application="ccore"...>
Note:
You may copy the entry for the desired components from the
OC4J_HOME/j2ee/instance/config/default-web-site.xml fileFor each <web app> entry that you added to the secure-web-site.xml file, remove the <web app> entry for that same component from the default-web-site.xml file.
Restart Oracle Application Server.
Generally, each Oracle WSM component is specified in either the default-web-site.xml file or the secure-web-site.xml file in the <web app> element. That is, the component is either configured to accept requests on a secure protocol or an open protocol. If you wish to accept requests for a component on both protocols, then you must add the shared="true" property to the <web-app> element in both the default-web-site.xml and secure-web-site.xml files.
Figure 4-1 is a basic deployment of Oracle WSM and shows which components communicate with each other. The arrows start where the connection is initiated and end where the connection terminates. For example, one connection is initiated by the Web Service Client to the Oracle WSM Gateway. Table 4-4 describes each of the connections, the type of information being transmitted, and the supported transport protocols. For those connections that can be secured using SSL, Table 4-4 provides a link to the section in this chapter that describes how to configure the secure connection.
Figure 4-1 Oracle WSM Deployment Showing Component Connections
Table 4-4 Description of Connections Between Oracle WSM Components
| Figure Number | Description of the Connection Between Components | Supported Secure Transport Protocols | For Information on How to Configure Secure Connections |
|---|---|---|---|
|
1 |
The Policy Enforcement Points initiate an SSL connection over HTTP with Oracle WSM Policy Manager. The PEPs retrieve policy information and use it to enforce security on Web services. |
SSL over HTTP |
"Securing PEPs to Oracle WSM Policy Manager" |
|
2 |
Web Services Manager Control initiates an SSL connection over HTTP with Oracle WSM Policy Manager. It sends updates to policies and retrieves and displays policy information in its user interface. Web Services Manager Control acts as a client for the SSL connection. |
SSL over HTTP |
"Securing Web Services Manager Control to Oracle WSM Policy Manager" |
|
3 |
Web service clients can open connections to Oracle WSM Gateways over transport protocols such as HTTP, JMS, and MQ Series. Each of these protocols can be secured using SSL. The same connection is used to send the Web service request and to receive the response. |
SSL over HTTP, JMS, or MQSeries |
"Securing a Web Service Client to Oracle WSM Gateway" |
|
4 |
The Oracle WSM Gateway can open connections to a Web service over transport protocols such as HTTP, JMS, and MQ Series. Each of these protocols can be secured using SSL. The same connection is used to send the Web service request and to receive the response. |
SSL over HTTP, JMS, or MQSeries |
"Securing Oracle WSM Gateway to a Web Service" |
|
5 |
When an administrator connects to Web Services Manager Control, the Web browser can initiate an SSL connection over HTTP. |
SSL over HTTP |
"Securing Connections to Web Services Manager Control" |
|
6 |
A Web service can be registered to an Oracle WSM Gateway by looking up a WSDL from a server hosting a WSDL, UDDI, or a WSIL file. Web Services Manager Control acts as a client to the server. This connection can be secured over SSL. |
SSL over HTTP |
"Registering a Service from a Secure WSDL" |
|
7 |
The Policy Enforcement Points can authenticate and authorize users against an LDAP Server. The gateway or agent acts as a client for the LDAPS connection. |
SSL over LDAP |
"Securing PEPs to an LDAP Server" |
|
8 |
When users log in to Web Services Manager Control, they may be authenticated against an LDAP Server. The connection from Web Services Manager Control to the LDAP Server can be secured over SSL. |
SSL over LDAP |
"Securing Web Services Manager Control to an LDAP Server" |
|
9 |
Web Services Manager Control sends data updates to Oracle WSM Database and retrieves data from Oracle WSM Database which it displays in its user interface over JDBC. SSL over JDBC connections to the Oracle WSM Database are not certified. |
No secure transport protocols are supported. |
Not Applicable |
|
10 |
Oracle WSM Policy Manager sends information to and retrieves information from Oracle WSM Database over JDBC. SSL over JDBC connections to the Oracle WSM Database are not certified. |
No secure transport protocols are supported. |
Not Applicable |
|
11 |
Oracle WSM Monitor sends monitoring data to and retrieves data from Oracle WSM Database over JDBC. SSL over JDBC connections to the Oracle WSM Database are not certified. |
No secure transport protocols are supported. |
Not Applicable |
|
12 |
Web Services Manager Control retrieves and displays monitoring charts and reports from Oracle WSM Monitor over RMI. SSL over RMI connections to Oracle WSM Monitor are not certified. |
No secure transport protocols are supported. |
Not Applicable |
|
13 |
Oracle WSM Agents and Oracle WSM Gateways send monitoring data to Oracle WSM Monitor over RMI. SSL over RMI connections to Oracle WSM Monitor are not certified. |
No secure transport protocols are supported. |
Not Applicable |
The following connections to Oracle WSM Policy Manager can be secured over SSL:
Complete the following tasks to secure PEP connections to Oracle WSM Policy Manager:
To SSL enable Oracle WSM Policy Manager, refer to "Securing OC4J Using SSL".
In addition, if connections to Oracle WSM Policy Manager are passed through Oracle HTTP Server, then you must also enable SSL for the /policymanager/* URL in your Oracle HTTP Server configuration. See Oracle HTTP Server Administrator's Guide for information on how to configure your Oracle HTTP Server.
Configure PEPs to use a truststore by following the instructions in "Configuring the Truststore in SSL Connections".
Complete the following tasks to secure Web Services Manager Control connections to Oracle WSM Policy Manager:
To SSL enable Oracle WSM Policy Manager, refer to "Securing OC4J Using SSL".
In addition, if connections to Oracle WSM Policy Manager are passed through Oracle HTTP Server, then you must also enable SSL for the /policymanager/* URL in your Oracle HTTP Server configuration. See Oracle HTTP Server Administrator's Guide for information on how to configure your Oracle HTTP Server.
Configure the Web Services Manager Control by completing the following procedure:
Edit the following properties in the ORACLE_HOME/owsm/config/ccore/ui-config-installer.properties file.
ui.pm.server.httpScheme=https
ui.pm.server.httpPort=SSL_port
SSL_port is the port to which SSL connections are made.
Redeploy the Web Services Manager Control application by executing the following command from the command line:
wsmadmin deploy control
Configure the Web Services Manager Control to use the truststore configuration. See "Configuring the Truststore in SSL Connections" and follow the procedure for your deployment.
Connections to and from Oracle WSM Gateway can be secured using SSL. The following sections describe how to create these secure connections:
The following sections describe how to secure connections between a Web service client and Oracle WSM Gateway using SSL over HTTP, JMS, and MQ Series.
HTTPS
To SSL enable Oracle WSM Gateway, refer to "Securing OC4J Using SSL".
In addition, if connections to Oracle WSM Gateway are passed through Oracle HTTP Server, then you must also enable SSL for the/ gateway/* URL in the HTTP Server configuration. See Oracle HTTP Server Administrator's Guide for information on how to configure your Oracle HTTP Server.
JMS and MQ Series for SSL
Secure the JMS and MQ Series protocols for SSL by following this procedure:
Edit the SSL properties in the ORACLE_HOME/owsm/config/gateway-config-installer.properties file.
Redeploy the Oracle WSM Gateway by executing the following command from the command line:
wsmadmin deploy gateway
Configure Oracle WSM Gateway to use a truststore by following the instructions in"Configuring the Truststore in SSL Connections".
To SSL enable Oracle WSM Gateway, refer to "Securing OC4J Using SSL".
In addition, if connections to Web Services Manager Control are passed through Oracle HTTP Server, then you must also you must enable SSL for the /ccore/* URL in your Oracle HTTP Server configuration. See Oracle HTTP Server Administrator's Guide for information on how to configure your Oracle HTTP Server.
A Web service can be registered to a Oracle WSM Gateway by looking up a WSDL from a server hosting a WSDL, UDDI, or WSIL. Configure Web Services Manager Control to use a truststore by following the instructions in "Configuring the Truststore in SSL Connections".
The following connections to an LDAP Server can be secured over SSL:
Configure PEPs to use a truststore by following the instructions in "Configuring the Truststore in SSL Connections".
See Oracle Web Services Manager Administrator's Guide for information about policy pipelines and the LDAP authentication policy step.
To use SSL to secure the connection to the LDAP Server, you must modify the properties in the ORACLE_HOME/owsm/config/ccore/ui-config-installer.properties file.
Modify the properties listed under the "UI authentication properties" property group in the ui-config-installer.properties file:
ui.authentication.provider=com.cfluent.accessprovider.ldap.BasicLdapAuthProvider
ui.authentication.provider.properties=
ldapHost=ldaphost|\
ldapPort=389|\
ldapDN=o=company,c=us
ldapSSLEnabled=true|\
ldapSSLPort=636|\
roleAttribute=uniqueMember
See "Configuring the Truststore in SSL Connections" for instructions on how to configure the truststore.
Why am I receiving a Host name verifier exception when SSL is enabled?
The server-side SSL certificate's cn should match the host name of the component. For example, if the Policy Manager is running on http://www.company.com, then the server-side SSL certificate's dn should start with cn=www.company.com.
How do I create a new PKCS#12 keystore for testing using openSSL?
The following example shows how to create a new PKCS#12 keystore with a self-signed certificate for the server side of a connection. The same process is used to create the corresponding client.p12 file.
Create a new self-signed certificate, and a new private key to sign the certificate. Specify the time validity for the certificate with the -days option.
openssl req -x509 -newkey rsa:1024 -days 365 -keyout server-privatekey.pem -out server-cert.pem
You will be asked some questions about country, state, locality, and so on. These questions are asked for informational purposes. The exception to this is the Common Name (CN) field. The CN is used to represent the host name of the machine where the certificate resides. The SSL client may attempt to verify the host name with the CN field to see that they match. Make sure to set it to the host name that you have set for all the connection URLs in the various config.xml files (for example, localhost).
Import the self-signed certificate and the associated private key into a PKCS#12 keystore.
openssl pkcs12 -export -in server-cert.pem -inkey server-privatekey.pem -name testalias -out server.p12
Delete any temporary files. Now that you have them stored in a PKCS#12 keystore, you do not need the server-cert.pem and server-privatekey.pem files.
rm -f server-cert.pem server-privatekey.pem
Why am I getting the error message "HTTPS hostname wrong" when I try to connect to the Oracle WSM Policy Manager over SSL?
The CN field of the server certificate does not match the host name to which the client is connecting. You need to ensure that the CN field matches the host name. An example error message (for localhost) is:
java.io.IOException: HTTPS hostname wrong: should be <localhost>
Note that if you are using a load balancer, the CN must match the load balancer host name.
How do I create a new JKS keystore for testing purposes using keytool?
Enter the following command:
keytool -genkey -keystore test.jks -storepass changeit
