5 Deploying Oracle WSM Gateways

This chapter discusses how to deployOracle WSM Gateways, and includes the following sections:

• Oracle WSM Incoming and Outgoing Transport Protocols

• Registering Oracle Web Services Manager Gateways

• Configuring Incoming Transport Protocols

• Configuring the Incoming JMS Transport Protocol

• Configuring the Incoming MQ Transport Protocol

Oracle WSM Incoming and Outgoing Transport Protocols

The Oracle WSM Gateway receives message requests over an incoming protocol, and sends these requests over the outgoing protocol to the appropriate Web service. The incoming and outgoing protocols are independent of each other and configured separately. Within a single environment, you can mix or match the incoming and outgoing transport protocols.

For example, a client request can be made over HTTPS, and the Web service invocation can be made using Java Message Service (JMS). In this case, the Oracle WSM Gateway takes the incoming request and translates it to the outgoing transport protocol.

This chapter focuses on incoming transport protocols. See Oracle Web Services Manager Administrator's Guide for more information about outgoing transport protocols.

Before configuring the gateway to receive the incoming transport protocol, you need to register and deploy the Oracle Web Services Manager Gateway. The following section describes how to register and deploy a gateway.

Registering Oracle Web Services Manager Gateways

Before installing a Policy Enforcement Point (PEP), you need to register the PEP as a new component in the Oracle WSM Policy Manager. The registration process assigns an Oracle WSM component ID. The component ID defines the boundaries and responsibilities of the PEP. In the case of gateways, it contains information that teaches the gateway about your Oracle WSM environment.

Prerequisites and General Information about Registering Oracle WSM Gateways

Use Oracle Web Services Manager Control to register your Oracle WSM Gateway. Only users who are members of the group assigned to the Oracle WSM Domain Administrator role can add or edit registration details for Oracle WSM PEPs: Oracle WSM Gateways, Oracle WSM Client or Server Agents.

Contact your Oracle WSM system administrator about obtaining the privileges required to access or update specific Oracle WSM components.

Refer to the Oracle Web Services Manager Administrator's Guide for more information about the Oracle WSM roles and permissions required to perform specific operations from the Web Services Manager Control.

Before you register your gateway, ensure that you have successfully completed the installation process for all server-side components.

To register a gateway

1. In the navigation pane of Web Services Manager Control, select Policy Management, then select the Manage Policies option.

   If any gateways or agents have been previously registered, the Web Services Manager Control displays a list of these registered components.

2. Click Add New Component.

   The Web Services Manager Control displays the Add New Component page.

3. Specify the following gateway properties:

   • Select Gateway from the list of Component Types.

   • Enter a meaningful name for the Component that describes its location or function. This is very important. Prior to registering new components, you may want to establish a convention for naming your components, so that you can easily identify them.

   • There is only one choice for Container Type – Oracle Web Services Manager.

   • In the Component URL field, specify the URL at which the gateway will be running. The syntax for specifying the URL is:

     http://hostname:port/gateway

     or

     https://hostname:port/gateway

     where hostname and port refer, respectively, to the host and port from which the gateway may be accessed.

     Note:

     If you plan to load balance the gateway, then the host and port should refer to the externally visible host and port of the load balancer.

   • Enter the Component Groups to which you want to grant Modify or View permissions to the gateway.

     • Groups mapped to the Oracle WSM Component Administrator role may view and edit component details, and add, edit, or delete managed services and routing associated with the component. However, they cannot add, delete, or remove Oracle WSM components, or change any registration details of the components.

     • Groups mapped to the Oracle WSM Component Support role may only view component information and associated services. They are not allowed to add, edit, or change details of the component, or any of its associated services.

     See Oracle Web Services Manager Administrator's Guide for more information on roles and groups.

4. Click Register.

   Oracle WSM adds the component to the Oracle WSM system registry, assigns a unique ID to it, then displays the component ID.

5. Click OK.

   Oracle WSM displays the List of Components, including the newly added gateway and its component ID. Make a note of the component ID.

6. Edit the properties in the ORACLE_HOME/owsm/config/gateway /gateway-config-installer.properties file to configure incoming transport protocols.

7. Deploy the gateway using the wsmadmin command:

   wsmadmin deploy gateway

   See "deploy" , for more information about the deploy command. If you make any other changes to the gateway, you must redeploy the component using the wsmadmin deploy command.

Configuring Gateway Component IDs

When you create and register an Oracle WSM Policy Enforcement Point (PEP), it is assigned a Component ID. Component IDs are unique identifiers that associate the PEP with a set of policies.

The component IDs start with the number C0003001. This number is incremented by 1 for each subsequent component that is created and registered. After a PEP is created, the component ID must be specified in the appropriate property file. (For gateways, this file is gateway-config-installer.properties. For agents, this file is agent.properties.) To make it easier to use Oracle WSM, by default, the Oracle WSM Gateway comes preconfigured in the gateway-config-installer.properties file with the component ID C0003001. This configuration assumes that the first component you create is an Oracle WSM Gateway.

There are two situations where this default configuration causes conflicts:

• The first PEP you create is an agent, not a gateway. In this case, the component ID C0003001 is assigned to the agent. If you subsequently create a gateway, it will be registered with the next component ID, in this example, C0003002. However, the component ID parameter in the gateway-config-installer.properties file is incorrectly assigned the number C0003001.

• If you have more than one Oracle WSM Gateway in your Oracle Web Services Manager environment and each gateway is assigned a different component ID, for example, C0003001 and C0003002. The component ID in the gateway-config-installer.properties file will be correct for the first gateway, but it will be incorrect for the second gateway.

In both of these situations, you must edit the properties file with the correct component ID.

To edit the component ID for an Oracle WSM Gateway

1. Open the following file in a text editor: ORACLE_HOME/owsm/config/gateway/gateway-config-installer.properties

2. Edit the value for the component ID in the parameter gateway.component.id=

3. Redeploy the gateway using the wsmadmin deploy gateway operation.

   See "deploy" for more information on this command. See Table 6-0, "Installing Oracle WSM Agents" for more information on editing the component ID for Oracle WSM Agents.

Configuring Incoming Transport Protocols

Gateways support the reception of both SOAP messages and standard XML message requests over JMS, MQ, and HTTPS. The ORACLE_HOME/owsm/config/gateway/gateway-config-installer.properties file for each gateway specifies how that gateway listens for messages in these different formats. There are sections in the gateway-config-installer.properties file for each of the protocols (HTTPS, JMS, and MQ), each associated with a pair of processable message types (SOAP or standard XML) (Table 5-1).

Table 5-1 Gateway Transport Protocols

Parameter	Description
JMS	Listens for SOAP messages arriving at a JMS queue.
JMSXML	Listens for XML (non-SOAP) messages sent to a JMS queue.
MQ	Listens on an MQ queue for SOAP messages.
MQXML	Listen on a MQ queue for XML (non-SOAP) messages.
HTTP	Listens on a HTTP port for SOAP or XML messages. (The gateway is enabled by default.)

The sections that follow describe the parameters for each of the following protocols:

• JMS – See Table 5-2 for more information.

• JMS XML – See Table 5-3 for more information.

• MQ – See Table 5-4 for more information.

• MQ XML – See Table 5-5 for more information.

Configuring the Incoming JMS Transport Protocol

JMS requires only one handshake for each session, rather than requiring a secure handshake for every message. JMS facilitates transport without the latency associated with HTTPS. You can set up JMS to transport either SOAP or XML messages.

The number of the JMS Servers that you need to deploy and configure for your system depends on the number of deployed Oracle WSM Monitors in your Oracle WSM environment. A single, centralized Oracle WSM Monitor requires only a single, central JMS server. Federated Oracle WSM Monitors may require separate messaging systems, and as a result, multiple JMS servers.

The gateway-config-installer.properties file has two JMS sections that specify properties required for starting the JMS request handler. The first section, JMS properties, contains the properties to use JMS to process SOAP messages. The second section, JMS XML, contains the properties to use JMS to process standard XML messages.

After you edit the gateway configuration properties file, you must redeploy the gateway using the wsmadmin deploy command for the changes to take effect.

Note:

Oracle Web Services Manager supports JMS queues to enable point-to-point functionality.

Enabling Oracle Web Services Manager to use JMS

To enable JMS in Oracle Web Services Manager, you must complete the following tasks:

• If you are using Tibco JMS, copy the tibjms.jar and tibcrypt.jar files to the correct location in your Oracle WSM installation, for example, to ORACLE_HOME/10.1.3.1/OracleAS_1/owsm/lib/custom. Unless you perform this task, the JMS feature will not work.

  Note:

  You do not need to copy the Java Archive (JAR) files if you are using Oracle JMS.

• Configure JMS listeners on a gateway.

• Register and configure a JMS service on a gateway (using JMSMessengerStep). See the Oracle Web Services Manager Administrator's Guide for more information.

To test whether you can connect over the JMS protocol, complete the following tasks:

• Test the configured JMS service using the Test Engine tool in the Oracle Web Services Manager Control.

• Enable the sending of Direct Internet Message Encapsulation (DIME) messages.

Table 5-2 lists the properties you can set for JMS transport message request handling.

Table 5-2 JMS Properties

Property	Description
gateway.listener.jms.Enabled	Supported values are true or false. Starts the JMS request handler when set to true. (The remainder of the parameters in this table are relevant only when this parameter is set to true).
gateway.listener.jms.useJndi	Supported values are true or false. Enables or disables JNDI for retrieving queue information.
gateway.listener.jms.sslEnabled	Supported values are true or false. If set to true, enables JMS communication over SSL.
gateway.listener.jms.queueName	The name of the queue where the JMS request handler listens. When JNDI is enabled, this is the JNDI name of the Queue.
gateway.listener.jms.retryInterval	The time in seconds that the gateway waits before checking JMS server availability. If the server is not available, the gateway pings and checks the server availability at the next retry interval.
gateway.listener.jms.defaultServiceId	The default service ID used when the destination service ID is not specified.
gateway.listener.jms.env.connectionFactory	The connection factory class name used to get the queue connection. JNDI looks up the connection factory to fetch the actual queue.
gateway.listener.jms.env.username	The user name that enables you to connect to the JMS server and fetch the queue.
gateway.listener.jms.env.password	The password for connecting to the JMS server. Use the encryption tool to ensure that your password is sent in an encrypted format.
gateway.listener.jms.env.url	The URL used to connect to the JMS server.
gateway.listener.jms.ssl.sslVendor	Supported values are J2SE and entrust6 for Tibco JMS. The vendor that provides the SSL certificates.
gateway.listener.jms.ssl.sslHostName	Name of the JMS server, expected in the JMS certificate.
gateway.listener.jms.ssl.clientIdentity	Client identity certificate or the path to the certificate file.
gateway.listener.jms.ssl.clientIdentityPassword	Password to decrypt the provided identity file. Use the encryption tool to ensure that your password is sent in an encrypted format.
gateway.listener.jms.ssl.trustCerts.cert	Trust certificate of the server or the path to the certificate file.
gateway.listener.jms.jndi.providerUrl	The jndi.providerURL that gets the jndi context.
gateway.listener.jms.jndi.providerCtxFactory	The jndi.providerContextFactory class used to get the JNDI context.
gateway.listener.jms.jndi.urlPackagePrefix	Value used to initialize the JNDI context.
gateway.listener.jms.jndi.username	User name for the JNDI lookup.
gateway.listener.jms.jndi.password	Password for the JNDI lookup. Use the encryption tool to ensure that your password is sent in an encrypted format.

Table 5-3 lists the properties you can set for JMS XML transport message request handling.

Table 5-3 JMS XML Properties

Property	Description
gateway.listener.jmsxml.enabled=false	Supported values are true or false. Starts the JMS XML request handler when set to true. (The remainder of the parameters in this table are relevant only when this parameter is set to true).
gateway.listener.jmsxml.useJndi	Supported values are true or false. Enables or disables JNDI for retrieving queue information.
gateway.listener.jmsxml.sslEnabled	Supported values are true or false. If set to true, enables JMSXML communication over SSL.
gateway.listener.jmsxml.queueName	The name of the queue where the JMS XML request handler listens. When JNDI is enabled, this is the JNDI name of the Queue.
gateway.listener.jmsxml.retryInterval	The time in seconds that the gateway waits before checking JMS server availability. If the server is not available, the gateway pings and checks the server availability at the next retry interval.
gateway.listener.jmsxml.defaultServiceId	The default service ID used when the destination service ID is not specified.
gateway.listener.jmsxml.env.connectionFactory	The connection factory class name used to get the queue connection. JNDI looks up the connection factory to fetch the actual queue.
gateway.listener.jmsxml.env.username	The user name that enables you to connect to the JMS server and fetch the queue.
gateway.listener.jmsxml.env.password	The password for connecting to the JMS server. Use the encryption tool to ensure that your password is sent in an encrypted format.
gateway.listener.jmsxml.env.url	The URL used to connect to the JMS server.
gateway.listener.jmsxml.ssl.sslVendor	Supported values are J2SE and entrust6 for Tibco JMS. The vendor that provides the SSL certificates.
gateway.listener.jmsxml.ssl.sslHostName	Name of the JMS server, expected in the JMS certificate.
gateway.listener.jmsxml.ssl.clientIdentity	Client identity certificate or the path to the certificate file.
gateway.listener.jmsxml.ssl.clientPassword	Password to decrypt the provided identity file. Use the encryption tool to ensure that your password is sent in an encrypted format.
gateway.listener.jmsxml.ssl.trustCerts.cert	Trust certificate of the server or the path to the certificate file.
gateway.listener.jmsxml.jndi.providerUrl	The jndi.providerURL that gets the jndi context.
gateway.listener.jmsxml.jndi.providerContextFactory	The jndi.providerContextFactory class used to get the JNDI context.
gateway.listener.jmsxml.jndi.urlPackagePrefix	Value used to initialize the JNDI context.
gateway.listener.jmsxml.jndi.username	User name for the JNDI lookup.
gateway.listener.jmsxml.jndi.password	Password for the JNDI lookup. Use the encryption tool to ensure that your password is sent in an encrypted format.

Configuring the Incoming MQ Transport Protocol

MQ series allows the use of the following Java implementations:

• MQSeries base classes for Java (MQ base Java) – Allows a program written in the Java programming language to connect to MQSeries as an MQSeries client. This involves direct connection to an MQSeries server, and enables Java applets, applications, and servlets to issue calls and queries to MQSeries.

• MQSeries classes for Java Message Service (MQ JMS) – A set of Java classes that implement Sun Microsystem's Java Message Service (JMS) interfaces to enable JMS programs to access MQSeries systems. Both the point-to-point and publish-and-subscribe models of JMS are supported.

Enabling Oracle Web Services Manager to use MQ

Oracle Web Services Manager uses MQSeries classes for Java (MQ base Java).

To enable MQ in Oracle Web Services Manager, complete the following tasks:

• Acquire an MQ license. The MQ license is not bundled with Oracle WSM, therefore, you must acquire the correct license. Then, you must copy the com.ibm.mq.jar file to the correct location in your Oracle WSM installation, for example, to ORACLE_HOME/owsm/lib/custom. Unless you perform this task, the MQ feature will not work.

• Configure MQ listeners on a gateway.

• Register and configure an MQ service on a gateway (using MQMessengerStep). See Oracle Web Services Manager Administrator's Guide for more information.

To test whether you can connect over the MQ protocol, complete the following tasks:

• Test the configured MQ service using the Test Engine tool in the Oracle Web Services Manager Control.

• Enable the sending of DIME messages.

Setting up MQ Listeners in a Gateway

MQ transport protocols listen for a client request to be processed on a configured MQ queue.

The gateway-config-installer.properties file has two MQ sections that specify properties required for starting the MQ request handler. The first section, MQ properties, contains the properties to use MQ to process SOAP messages. The second section, MQ XML, contains the properties to use MQ to process standard XML messages. After editing the gateway configuration file, you must redeploy the gateway using the wsmadmin deploy command for the changes to take effect.

Table 5-4 lists the properties you can set to configure MQ transport message request handling.

Table 5-4 MQ Properties

Property	Description
gateway.listener.mq.enabled	The default value is false. Starts the MQ request handler when set to true. (The rest of the parameters in this table are relevant only when the parameter on the left is set to true).
gateway.listener.mq.managerName	Name of the queue manager to which the application needs to connect to access the queues configured on the MQSeries server.
gateway.listener.mq.hostName	Valid name or IP address of the host where MQSeries server is running.
gateway.listener.mq.port	Valid port number of the MQSeries server listener.
gateway.listener.mq.username	User name by which the application can connect to the MQSeries Server.
gateway.listener.mq.password	Password for the user by which the application can connect to MQSeries.
gateway.listener.mq.channelName	Name of the channel which connects an application to a queue manager on a server machine for the transfer of MQ calls and responses.
gateway.listener.mq.queueName	Name of the queue where the MQ Listener waits for request messages.
gateway.listener.mq.retryInterval	Interval between retries for retrieving messages from the MQ server.
gateway.listener.mq.defaultServiceId	Service to which messages will be forwarded by the MQ listener if the incoming message does not specify a destination service.

Table 5-5 lists the properties you can set to configure MQ XML transport message request handling.

Table 5-5 MQ XML Properties

Property	Description
gateway.listener.mqxml.enabled	The default value is false. Starts the MQ XML request handler when set to true. (The remainder of the parameters in this table are relevant only when this parameter is set to true). To enable IBM MQ, set the value to true.
gateway.listener.mqxml.managerName	Name of the queue manager to which the application needs to connect to access the queues configured on the MQSeries server.
gateway.listener.mqxml.hostName	Valid name or IP address of the host where MQSeries server is running.
gateway.listener.mqxml.port	Valid port number of the MQSeries server listener.
gateway.listener.mqxml.username	User name by which the application can connect to the MQSeries Server.
gateway.listener.mqxml.password	Password for the user by which the application can connect to MQSeries.
gateway.listener.mqxml.channelName	Name of the channel which connects an application to a queue manager on a server machine for the transfer of MQ calls and responses.
gateway.listener.mqxml.queueName	Name of the queue where the MQ Listener waits for request messages.
gateway.listener.mqxml.retryInterval	Interval between retries for retrieving messages from the MQ server.
gateway.listener.mqxml.defaultServiceId	Service to which messages will be forwarded by the MQ listener if the incoming message does not specify a destination service.