Configuring HTTP Services

Contents

Overview

The Enterprise Gateway uses HTTP Services to service traffic from various HTTP-based sources. The following list summarizes the list of available HTTP Services:

HTTP Interfaces
HTTP Interfaces are used in the Enterprise Gateway to define the ports and IP addresses on which the Enterprise Gateway Process listens for incoming requests. HTTPS Interfaces can also be added, allowing you to select the SSL certificate to use to authenticate to clients and also what certificates are considered trusted for establishing SSL connections with clients.

Relative Path
While HTTP and HTTPS Interfaces open sockets and listen for traffic, Relative Paths can be configured so that when a request is received on that path, the Enterprise Gateway Process can map it to a specific policy.

Static Content Provider
A Static Content Provider can be used to serve static HTTP content from a particular directory. In this case, the Enterprise Gateway Process is effectively acting as a Web Server.

Servlet Applications
The Enterprise Gateway Process can act as a servlet container enabling you to drop servlets into the HTTP Services configuration. This functionality should only be used by developers with very specific requirements and under strict advice from the Oracle support team.

Packet Sniffer
Finally, you can add a Packet Sniffer to intercept network packets from the client, assemble these packets into complete HTTP messages, and then log these messages to an audit trail. Because the Packet Sniffer operates at the network layer (as opposed to a HTTP-based traffic monitor, which operates at the application layer), the packets are intercepted transparently to the client. Because of this, the Packet Sniffer is a type of passive service, which is typically used for SOA management and monitoring as opposed to general policy enforcement.

This topic describes how to configure the HTTP Services listed above.

HTTP Services Groups

An HTTP Services Group is a container around one or more HTTP Services. Usually, an HTTP Services Group is configured for a particular type of HTTP Service. For example, it would be typical to have an HTTP Interfaces Group that contains the configured HTTP Interfaces, and another Static Providers Group to manage Static Content Providers. While organizing HTTP Services by type eases the task of managing Services, the Enterprise Gateway is flexible enough to enable administrators to organize Services into Groups according to whatever scheme best suits their requirements.

This topic describes a situation where HTTP Services Groups can prove useful. It first considers an HTTP Service Group that handles HTTP traffic, and then shows how a second SSL Service Group can be used to process SSL traffic on a separate channel.

HTTP Services Groups should consist of at least one HTTP Interface together with at least one Relative Path. The HTTP Interface determines what TCP port the Process listens on, while the Relative Path can be used to map a request received on a particular path (request URI) to a specific policy.

You can add several HTTP Interfaces to the Groups, in which case requests received on any one of the opened ports are processed in the same manner. For example, it is possible for requests http://[HOST]:8080/test and http://[HOST]:8081/test to be both processed by the same policy (the one mapped to the /test Relative Path).

Similarly, you can add multiple Relative Paths to this HTTP Services Group, where each Path is bound to a specific Policy. For example, if a request is made to http://[HOST]:8080/a, it is processed by Policy A; whereas if a request is made to http://[HOST]:8080/b, it is handled by Policy B. As a side-effect of this configuration, requests made to the other Interface are also processed by the same policy, meaning that a request made to http://[HOST]:8081/b is also handled by Policy B.

Effectively, this means that the Relative Paths configured under the HTTP Services Group are bound to all HTTP Interfaces configured for that Group. In other words, if you have two Interfaces listening on ports 8080 and 8081, requests to http://[HOST]:8080/a and http://[HOST]:8081/a are handled identically by the Process.

But what happens if you want to make a distinction between receiving requests on the two different ports? For example, say you want requests to http://[HOST]:443/a to be processed by an SSL Validation policy, while requests for http://[HOST]:8080/a to be handled by a standard Schema Validation policy. How can you achieve this?

The addition of a new HTTP Services Group can resolve this issue. The new SSL HTTP Services Group opens a single HTTPS Interface that listens on port 443, and is configured with a Relative Path of /a to handle requests on this path. The configuration is summarized in the following table:

Services Group HTTP Port Relative Path Policy
HTTP Services Group 8080 /a Schema Validation Policy
SSL HTTP Services Group 443 /a SSL Validation Policy

With this configuration, when you receive a request on http://[HOST]:8080/a, it is handled by the Schema Validation Policy. But when you get a request to the SSL port on http://[HOST]:443/a it is processed by the SSL Validation Policy.

Using HTTP Services Groups in this way, you can configure the Process to dispatch requests received on the same path (for example, /a) to different policies depending on the port on which the request was accepted.

Default HTTP Service Groups
By default, the Enterprise Gateway ships with two pre-configured HTTP Services Groups (Default Services and Management Services). By default, Management Services are not visible in the Policy Studio, but can be made visible using the Preferences menu in the Policy Studio. The Default Services Group contains some general purpose default policies for use with an out-of-the-box installation of the Enterprise Gateway. In addition to these two pre-configured Service Groups, you can add new HTTP Services Groups for situations like the one described above where you want to dispatch requests to different policies, based on the port on which the requests are received.

For more details on the default Management Services Group, please see the Note on Management Services section below.

Adding an HTTP Service Group
To add a Service Group, right-click the Process, and select the Add HTTP Services menu option. Enter a name for the group in the HTTP Services dialog. If you want to monitor traffic processed by this Service Group using Service Monitor, check the Include in real time monitoring checkbox. Please refer to the Service Monitor Install Guide for more information on installing and setting up the Enterprise Gateway to store real-time monitoring data that can then be used by Service Monitor to produce graphical reports in a web-based interface.

When a Service Group has been created, the following types of HTTP Services can be associated with it.

HTTP and HTTP Interfaces

An HTTP Interface defines the address and port that the Enterprise Gateway Process listens on. There are two types of Interface: the HTTP Interface and the HTTPS Interface. The HTTP interface handles standard non-authenticated HTTP requests, while the HTTPS interface can accept mutually authenticated SSL connections.

To create an HTTP Interface, right-click the name of the HTTP Service Group (for example, Default Services) in the tree view of the Policy Studio, and select Add Interface from the menu options. To create an HTTP Interface, select the HTTP option. To create an HTTPS Interface, select the HTTPS menu option.

The following fields are common to both the HTTP Interface and HTTPS Interface dialogs, and must be configured for both types of interface:

Port
The port number that the Enterprise Gateway Process listens on for incoming HTTP requests.

Address
This is the IP address or host of the network interface on which the Enterprise Gateway Process listens. For example, you can configure the Process to listen on port 80 on the external IP address of a machine, while having a Web server running on the same port but on the internal IP address of the same machine. By entering, *, the Process listens on all interfaces available on the machine hosting the Enterprise Gateway.

Protocol Version
Configure the Internet Protocol version that this Interface uses. You can enable support for IPv4, IPv6, or both of these protocol versions.

Backlog
When the Process is busy handling concurrent requests, it is possible for the operating system to accept additional incoming connections. In such cases, a backlog of connections can build up while the operating system waits for the Process to finish handling current requests.

The Backlog value specified here is the maximum number of connections that the Process allows the operating system to accept and queue up until the Process is ready to read them. There is obviously a trade off: the larger the backlog, the larger the memory usage; the smaller the backlog, the greater the potential for dropped connections.

Idle Timeout
The Enterprise Gateway supports the use of HTTP 1.1 persistent connections. The Idle Timeout is the time that the Process waits after sending a response over a persistent connection before it closes the connection.

Typically, a client tells the Process that it wants to use a persistent connection. The Process acknowledges this instruction and decides to keep the connection open for a certain amount of time after sending the response to the client. If the client does not reuse the connection by sending up another request within the Idle Timeout period, the Process closes the connection.

Active Timeout
When the Process receives a large HTTP request, it reads the request off the network as it becomes available. If the time between reading successive blocks of data exceeds the Active Timeout, the Process closes the connection.

This guards against a client closing the connection while in the middle of sending data. Imagine the client's network connection is pulled out of the machine while in the middle of sending data to the Process. When the Process has read all the available data off the network, it waits the Active Timeout period of time before closing the connection.

Maximum Memory per Request
The maximum amount of memory that the Process allocates to each request, not including the HTTP body.

Trace level
The level of trace output. The possible values in order of least verbose to most verbose output are:

  • FATAL
  • ERROR
  • INFO
  • DEBUG
  • DATA

The default trace level is read from the system settings.

Transparent Proxy (allow bind to foreign address)
Enables the use of the Enterprise Gateway as a transparent proxy on Linux systems with the TPROXY kernel option set. When selected, the value in the Address field can specify any IP address, and incoming traffic for the configured address/port combinations is handled by the gateway. For more details and an example, see Configuring a Transparent Proxy.

Configuring Conditions for an HTTP Interface
You can configure the Enterprise Gateway to bring down an active HTTP Interface if certain conditions fail to hold. For example, the HTTP Interface can be brought down if a Remote Host is not available or if a physical network interface on the machine on which the Enterprise Gateway is running loses connectivity to the network.

For more information on configuring conditions for HTTP Interfaces, see the Configuring Conditions for HTTP Interfaces help page.

HTTPS Interfaces Only

You must complete the same fields for an HTTPS Interface (on the Network tab) as for an HTTP Interface, with the addition of the following configuration options:

X.509 Certificate
Click the X.509 Certificate button to select the certificate that the Enterprise Gateway uses to authenticate itself to clients during the SSL handshake. The list of certificates currently stored in the Certificate Store is displayed. Select a single certificate from this list.

SSL Server Name Identifier (SNI)
You can specify the hostnames that are requested by clients in the SSL Server Name Identifier (SNI) table. SNI is an optional TLS feature whereby the client indicates to the server the hostname used to resolve the server's address. This enables a server to present different certificates for clients to ensure the correct site is contacted.

For example, the server IP address is 192.168.0.1. The DNS is consulted by clients to resolve a hostname to an address, and the server address is contacted using TCP/IP. If both www.acme.com and www.anvils.com resolve to 192.168.0.1, without SNI, the server does not know which hostname the client uses to resolve the address, because it is not party to the client's DNS name resolution. The server may be able to certify itself as either service, but when the connection is established, it does not know which hostname the client connects to.

With SNI, the client provides the name of the host (for example, www.anvils.com) in the initial SSL exchange, before the server presents its certificate in its distinguished name (for example, CN=www.anvils.com). This enables the server to certify itself correctly as providing a service for the client's requested hostname.

To specify an SNI, perform the following steps:

  1. Click the Add button to configure a server hostname in the SSL Server Name Identifier (SNI) dialog.
  2. Specify the server hostname in the Client requests server name field.
  3. Click the Server assumes identity button to import a Certificate Authority certificate into the Trusted Certificate Store.
  4. Click OK.

Ciphers
You can specify the ciphers that the server supports in the Ciphers field. The server selects the highest strength cipher (that is also supported by the client) from this list as part of the SSL handshake. For more information on the syntax of this setting, please see the OpenSSL documentation.

SSL session cache size
You can specify the maximum number of SSL sessions that this HTTPS interface can handle simultaneously in the SSL session cache size field.

Mutual Authentication
You can configure clients to authenticate to the Enterprise Gateway on the Mutual Authentication tab. The following options are available:

  • Ignore Client Certificates
    The Enterprise Gateway ignores client certificates if they are presented during the SSL handshake.
  • Accept Client Certificates
    Client certificates are accepted when presented to the Enterprise Gateway, but clients that do not present certificates are not rejected.
  • Require Client Certificates
    The Enterprise Gateway only accepts connections from clients that present a certificate during the SSL handshake.

Client certificates are typically issued by a Certificate Authority (CA). In most cases, the CA includes a copy of its certificate in the client certificate so that consumers of the certificate can decide whether or not to trust the client based on the issuer of the certificate.

It is also possible that a chain of CAs were involved in issuing the client certificate. For example, a top-level organization-wide CA (for example, Company CA) may have issued department-wide CAs (for example, Sales CA, QA CA, and so on), and each department CA would then be responsible for issuing all department members with a client certificate. In such cases, the client certificate may contain a chain of one or more CA certificates.

You can use the Maximum depth of client certificate chain field to configure how many CA certificates in a chain of one or more are trusted when validating the client certificate. By default, only one issuing CA certificate is used, and this certificate must be checked in the list of trusted root certificates. If more than one certificate is used, only the top-level CA must be considered trusted, while the intermediate CA certificates are not.

Root Certificate Authorities trusted for mutual authentication
Select the root CA certificates that the Enterprise Gateway considers trusted when authenticating clients during the SSL handshake. Only certificates signed by the CAs selected here are accepted.

Relative Paths

The Relative Path binds a policy to a specific relative path. When the Enterprise Gateway receives a request on this relative path, it invokes the specified policy. For more information on configuring policies, see Policy Configuration.

To configure a Relative Path for a given HTTP Service Group, right-click the Service Group in the tree view, and select the Add Relative Path option from the drop-down menu. Relative Paths are added using the Configure Relative Path dialog. Complete the following fields on this dialog:

Relative Path
Requests received on this relative path are processed by the policy selected in the Policy field.

Policy
The Enterprise Gateway invokes the policy selected when it receives a request on the path specified in the Relative Path field.

Static Content Provider

A Static Content Provider can be used in conjunction with an HTTP Interface to serve static content from a specified directory. A relative path is associated with each Static Content Provider so that requests received on this path are dispatched directly to the Provider and are not mapped to a Policy in the usual manner.

For example, you can configure a Static Content Provider to serve content from the c:\docs folder (on a Windows system) when it receives requests on the relative path /docs.

To add a Static Content Provider, right-click the Service Group under the Process, and select the Static Content Provider menu option. Complete the following fields on the Static Content Provider dialog:

Relative Path
Enter the path that you want to receive requests for static content on.

Content Directory
Enter or browse to the location of the directory that you want to serve static content from.

Index File
Enter the name of the file that you want to use as the index file for content retrieved from the directory specified in the field above. This file is retrieved by default if no resource is explicitly specified in the request URI. For example, if the client requests http://[HOST]:8080/docs (with only a relative path specified as opposed to a specific resource), the file specified here will be retrieved. This file must exist in the directory specified in the previous field.

Allow Directory Listings
If this option is selected, the Static Content Provider returns full directory listings for requests specifying a relative path only. For example, if this option is selected, and if a request is received for http://[HOST]:8080/docs/samples, the list of directories under this directory is returned, assuming that this directory exists on the file system. This option can be turned off to prevent attacks where a hacker can send up different request URIs in the hope that the server returns some information about the directory structure of the server.

Servlet Applications

Developers may wish to write their own Java servlets and deploy them under the Enterprise Gateway to serve HTTP traffic. Conversely, they may wish to remove some of the default servlets from the out-of-the-box configuration (for example, to remove the ability to view logging remotely). This pairing down of unwanted functionality may be required to further lock down the machine on which the Enterprise Gateway is running.

Note:
Adding and removing Servlet Applications should be performed only by developers with very specific requirements and under strict guidance from the Oracle Support team. These instructions simply outline how to configure the fields on the dialogs used to set up Servlet Applications. For more detailed instructions, please contact the Oracle Support Team.

There are a few default Servlet Applications available under the Management Services group. By default, this services group is not visible, but can be displayed using the Preferences dialog on the Policy Studio. The following table describes the default servlets:

Servlet Application Use
/configuration/ Updates configuration information for the Enterprise Gateway.
/runtime/ Deploys to the server after an update has been made to a policy.
/monitoring/ Displays real-time monitoring of server transactions.

Please note that deleting any of these Servlet Applications may prevent the Enterprise Gateway from functioning correctly. Default Servlet Applications should only be deleted under strict supervision of the Oracle Support team.

To add a new Servlet Application, right-click the Services Group that you wish to add the servlet to, and select Add Servlet Application. Configure the following fields on the Servlet Application dialog:

Relative Path
Enter the servlet context in this field. You can add multiple servlets under this context, where each servlet is mapped to a unique URI.

Session Timeout
Enter the timeout in seconds after which an inactive session is closed. Click OK.

The new Servlet Application now appears in the Policy Studio tree view. To add a new servlet, right-click the new Servlet Application, and select Add Servlet. Configure the following fields on the Servlet dialog:

URI
The path entered here maps incoming requests on a particular request URI to the Java servlet class entered in the field below. This path must be unique across all Servlets that are added under this Servlet Application (servlet context).

Class
Enter the fully qualified class name of the servlet class. This class can be added to the server runtime by adding the JAR, class file, or package hierarchy to the [VINSTDIR]/ext/lib folder, where VINSTDIR points to the root of your Enterprise Gateway installation.

Read Timeout
Specify the time in seconds that the servlet should wait before closing an idle connection.

Servlet Properties
You can configure properties for each servlet by clicking the Add button, and entering a name and value in the fields provided on the Properties dialog.

Packet Sniffers

Packet Sniffers are a type of passive service. Rather than opening up a TCP port and actively listening for requests, the Packet Sniffer passively reads raw data packets off the network interface. The Sniffer assembles these packets into complete messages that can then be passed into an associated policy.

Because the Packet Sniffer operates passively (does not listen on a TCP port) and, therefore, completely transparently to the client, it is most useful for monitoring and managing Web Services. For example, the Sniffer can be deployed on a machine running a Web Server acting as a container for Web Services. Assuming that the Web Server is listening on TCP port 80 for traffic, the Packet Sniffer can be configured to read all packets destined for port 80 (or any other port, if necessary). The packets can then be marshaled into complete HTTP/SOAP messages by the Sniffer and passed into a policy that logs the message to a database, for example.

Important Note
On Linux and Solaris platforms, the Enterprise Gateway must be started by the root user to gain access to the raw packets.

Because Packet Sniffers are mainly for use as passive monitoring agents, they are usually created in their own HTTP Service Group. For example, you can create a new Service Group for this purpose by right-clicking the Process, selecting the Add HTTP Services menu option, and entering Packet Sniffer Group on the HTTP Services dialog.

You can then add a Relative Path Service to this Group by right-clicking the Packet Sniffer Group, and selecting the Add Relative Path menu option. Enter a path in the field provided, and select the policy that you want to dispatch messages to when the Packet Sniffer detects a request for this path (after it assembles the packets). For example, if the Relative Path is configured as /a, and the Packet Sniffer assembles packets into a request for this path, the request is dispatched to the policy selected in the Relative Path service.

Finally, you can add the Packet Sniffer itself by right-clicking the Packet Sniffer Group node, selecting Packet Sniffer, and then the Add menu option. Complete the following fields on the Packet Sniffer dialog:

Device to Monitor
Enter the name or identifier of the network interface that the Packet Sniffer will monitor. The default entry is any, but it is important to note that this is only valid on Linux. On UNIX-based systems, network interfaces are usually identified using names like eth0, eth1, and so on. On Windows, these names are more complicated, for example, \Device\NPF_{00B756E0-518A-4144 ... }.

Filter
You can configure the Packet Sniffer to only intercept certain types of packets. For example, it can ignore all UDP packets, only intercept packets destined for port 80 on the network interface, ignore packets from a certain IP address, listen for all packets on the network, and so on.

The Packet Sniffer uses the libpcap library filter language to achieve this. This language has a complicated but powerful syntax that enables you to filter what packets are intercepted and what packets are ignored. As a general rule, the syntax consists of one or more expressions combined with conjunctions, such as and, or, and not. The following table lists a few examples of common filters and explains what they filter:

Filter Expression What does it filter?
port 80 Capture only traffic for the HTTP Port (80).
host 192.168.0.1 Capture traffic to and from IP address 192.168.0.1.
tcp Capture only TCP traffic.
host 192.168.0.1 and port 80 Capture traffic to and from port 80 on IP address 192.168.0.1.
tcp portrange 8080-8090 Capture all TCP traffic destined for ports from 8080 through to 8090.
tcp port 8080 and not src host 192.168.0.1 Capture all TCP traffic destined for port 8080 but not from IP address 192.168.0.1.

The default tcp filter simply captures all TCP packets arriving on the network interface. For more information on how to configure filter expressions like these, see the tcpdump man pages.

Promiscuous Mode
When listening in promiscuous mode, the Packet Sniffer captures all packets on the same Ethernet network, regardless of whether or not the packets are addressed to the network interface that the Sniffer is monitoring.

Note on Management Services

The Management Services group exposes a number of services that are used for remote configuration and monitoring. By default, this group is not visible in the Policy Studio tree view. However, you can view it by selecting the Settings -> Preferences main menu option, and selecting the Show Management Services checkbox. Click the Apply button to view the services. This setting also displays the Management Services under the Policies node in the Policy Studio tree view.

By default, the Management Services group consists of the following:

HTTP Interface: Port 8090
By default, the Enterprise Gateway exposes all its management services on port 8090 so that they can be configured remotely. At startup, the Policy Studio can connect to this port to read and write Enterprise Gateway configuration data. For more details, see Changing the Management Services Port below.

Relative Path: /
The / Relative Path is mapped to a default management policy called Protect Management Interface, which is available under the Management Services Policy Container. This policy performs HTTP Basic Authentication and passes control to the Call Internal Service filter. This is a special filter that dispatches a message to a Servlet Application or Static Content Provider based on the path on which the request was received.

For example, with the default configuration, assume that a request is received on http://localhost:8090/configuration. The following steps summarize the request processing cycle:

  1. When a Relative Path of / is configured, it matches all incoming requests, and requests are dispatched to whatever policy the Relative Path is mapped to. In this case, the Relative Path is mapped to the Protect Management Interface policy, and so the request is passed to this policy.

  2. The Protect Management Interface policy performs HTTP basic authentication on the originator of the request. Authentication is necessary because all configuration operations are considered privileged operations and should only be carried out by those with the authority to do so. If the originator can be successfully authenticated, the Call Internal Service filter is invoked.

  3. The Call Internal Service filter is a special filter that passes messages to a Servlet Application or Static Content Provider. In this case, because the message is received on the management interface (port 8090), the filter attempts to match the Relative Path on which the request was received against all the Servlets and Content Providers configured in the same Services Group as this interface.

  4. The configured Servlets and Content Providers for the Management Services group include /configuration/, /runtime/, and /monitoring/. Because the request is received on the /configuration/ path, this matches the /configuration/ Servlet Application, which is invoked.

Servlet Application: /configuration/
The Policy Studio running on a different host to the Enterprise Gateway can connect to this URL to remotely configure the Enterprise Gateway. For example if the Enterprise Gateway is running on a host called SERVER, the Policy Studio can connect to http://SERVER:8090/configuration/ on startup so that it can remotely configure policies running at the Enterprise Gateway on the SERVER host.

Servlet Application: /runtime/
This application is used to receive remote requests to deploy to the server (for example, by the Policy Studio). When policy updates are made by the Policy Studio, it is necessary to deploy them to the server so that the policy updates can take effect immediately. Policy deployment requests are sent to this application.

Static Content: /monitoring/
You can remotely view real-time traffic analysis of the Enterprise Gateway. To do this, open a browser, and point it at http://SERVER:8090/monitoring/, where the Enterprise Gateway is running on a host named SERVER. The /monitoring/ Static Content Provider then serves a HTML page containing an embedded flash component that displays real-time monitoring.

Important Note
Changing the Interfaces, Relative Path, Servlet Applications, or Static Content Provider exposed under the Management Services group may prevent the Enterprise Gateway from functioning correctly. Because of this, the Management Services group is hidden by default, and should only be modified under strict supervision from the Oracle Support team.

Changing the Management Services Port

The default Management Services port is 8090. To specify a different port, perform the following steps:

  1. In the Policy Studio main menu, select Settings -> Preferences, and ensure that the Show Management Services checkbox is selected.
  2. On the Policy Studio Services tab, right-click the Management Service HTTP Interface, and select Edit.
  3. Specify an updated value in the Port field (for example, 8091), and click OK.
  4. Click the Deploy button in the Policy Studio toolbar, or press F6 to deploy the update.
  5. Restart Policy Studio. You must restart Policy Studio when Management Services are updated.
  6. If you were connected to the Policy Center server, you can use the same URL to reconnect Policy Studio. If you were connected to the Enterprise Gateway server, you must use the updated port number in the URL to reconnect Policy Studio (for example, http://localhost:8091/configuration/deployments/DeploymentService).
  7. In the Policy Studio, on the Enterprise Gateway Dashboard, the Enterprise Gateway Process is displayed as uncontactable because it still uses the original port number.
  8. Click the Manage Processes button, select the Enterprise Gateway Process in the Processes list, and click the Connection tab.
  9. Specify the updated port number in the URL field, click Update, and click OK.
  10. Wait for the server to be notified about the process URL change (for example, 60 seconds), and then refresh the Enterprise Gateway Dashboard.
  11. The Process is now displayed as deployed, and you can edit its configuration.

Important Note
As stated earlier, you should only modify Management Services under strict advice and supervision from the Oracle Support team.