Oracle® Fusion Middleware
Part 8. API Gateway Instances

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

HTTP Interfaces

HTTP Interfaces are used in the API Gateway to define the ports and IP addresses on which the API Gateway instance listens for incoming requests. You can also add HTTPS Interfaces and select the SSL certificate to use to authenticate to clients, and the certificates that are considered trusted for establishing SSL connections with clients.

Relative Path

While HTTP and HTTPS Interfaces open sockets and listen for traffic, you can configure Relative Paths so that when a request is received on that path, the API Gateway instance can map it to a specific policy, or chain of policies.

Static Content Provider

You can use a Static Content Provider to serve static HTTP content from a particular directory. In this case, the API Gateway instance is effectively acting as a Web Server.

Servlet Applications

The API Gateway instance can act as a servlet container, which enables you to drop servlets into the HTTP Services configuration. This 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 them into complete HTTP messages, and log these messages to an audit trail. Because the Packet Sniffer operates at the network layer (unlike an HTTP-based traffic monitor at the application layer), the packets are intercepted transparently to the client. This means that the Packet Sniffer is a passive service, which is typically used for management and monitoring instead of general policy enforcement. For more details, see Packet Sniffers.

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 is 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 API Gateway is flexible enough to enable administrators to organize Services into Groups according to whatever scheme best suits their requirements.

This section describes a scenario where HTTP Services Groups can prove useful. It first describes an HTTP Service Group that handles HTTP traffic, and then shows how you can use a second SSL Service Group to process SSL traffic on a separate channel.

HTTP Interfaces and Relative Paths

HTTP Services Groups should consist of at least one HTTP Interface together with at least one Relative Path. The HTTP Interface determines which TCP port the API Gateway instance listens on, while you can use the Relative Path to map a request received on a particular path (request URI) to specific policies. 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, http://[HOST]:8080/test and http://[HOST]:8081/test requests can both be processed by the same policy (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 or chain of policies. 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. 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 API Gateway instance.

Example HTTP Service Group

What happens if you want to distinguish between receiving requests on the two different ports? For example, 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.

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:

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 API Gateway instance 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 API Gateway ships with pre-configured HTTP Services Groups (for example, Default Services and Management Services). By default, Management Services are not displayed in the Policy Studio, but can be displayed using the Preferences menu. The Default Services Group contains some general purpose default policies for use with an out-of-the-box installation of the API Gateway. In addition to the pre-configured Service Groups, you can add new HTTP Services Groups when you wish 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, see the section called “Management Services”.

Adding an HTTP Service Group

To add a Service Group, right-click the API Gateway instance, 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 API Gateway Analytics, select the Include in real time monitoring checkbox. For details on configuring the API Gateway to store real-time monitoring data, which can be used to produce graphical reports in a web-based interface, see the Real-Time Monitoring Settings.

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

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

To create an HTTP Interface, under the HTTP Service Group (for example, Default Services) in the Policy Studio tree, right-click Ports, and select Add HTTP or Add HTTPS.

Configuring Network Settings

The following fields on the Network tab 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 API Gateway instance listens on for incoming HTTP requests.

Address:

The IP address or host of the network interface on which the API Gateway instance listens. For example, you can configure the instance 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 instance listens on all interfaces available on the machine hosting the API Gateway.

Protocol:

Select the Internet Protocol version that this Interface uses. You can select IPv4, IPv6, or both of these protocol versions. Defaults to IPv4.

Trace level:

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

The default trace level is read from the system settings.

Enable interface:

Deselect this setting to disable this HTTP interface. This setting is enabled by default.

Configuring Traffic Monitor Settings

The fields on the Traffic Monitor tab are common to both the HTTP Interface and HTTPS Interface dialogs. To override the system-level settings at the HTTP or HTTPS interface level, select Override settings for this port, and configure the following options:

For more details, see Configuring Traffic Monitoring.

Configuring Advanced Settings

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

Backlog:

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

The specified Backlog value is the maximum number of connections that the API Gateway instance allows the operating system to accept and queue up until the instance is ready to read them. There is 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 API Gateway supports the use of HTTP 1.1 persistent connections. The Idle Timeout is the time that the API Gateway instance waits after sending a response over a persistent connection before it closes the connection. Defaults to 60000 milliseconds (60 seconds).

Typically, a client tells the instance that it wants to use a persistent connection. The instance 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 instance closes the connection.

Active Timeout:

When the API Gateway instance 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 instance closes the connection. Defaults to 60000 milliseconds (60 seconds).

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 instance. When the instance 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 API Gateway instance allocates to each request, not including the HTTP body.

Input Encodings:

Click the browse button to specify the HTTP content encodings that the API Gateway can accept from peers. The available content encodings include gzip and deflate. By default, the content encodings configured in the Default Settings are used. You can override this setting at the HTTP interface level and in the Remote Host Settings. For more details, see the topic on Compressed Content Encoding.

Output Encodings:

Click the browse button to specify the HTTP content encodings that the API Gateway can apply to outgoing messages. The available content encodings include gzip and deflate. By default, the content encodings configured in the Default Settings are used. You can override this setting at the HTTP interface level and in the Remote Host Settings. For more details, see the topic on Compressed Content Encoding.

Transparent Proxy - allow bind to foreign address:

Enables the use of the API 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 API Gateway. For more details and an example, see Configuring a Transparent Proxy.

Configuring Conditions for an HTTP Interface

You can configure the API 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 API 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.

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 setting:

X.509 Certificate:

Click the X.509 Certificate button to select the certificate that the API 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.

Configuring Mutual Authentication Settings

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

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.

Maximum depth of client certificate chain:

You can use this 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 API Gateway considers trusted when authenticating clients during the SSL handshake. Only certificates signed by the CAs selected here are accepted.

Configuring Advanced SSL Settings

You can complete the following settings on the Advanced (SSL) tab:

Check that the SSL certificate's Subject CN resolves to network address:

When this setting is selected the API Gateway attempts to resolve the SSL certificate's Subject Common Name (CN) to the network address configuring the SSL interface. If the Subject CN cannot be resolved to the network address, a warning is output in the error traces. This setting is selected by default. You can deselect this setting to disable checking the certificate's Subject CN.

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:

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, see the OpenSSL documentation.

SSL session cache size:

Specifies the number of idle SSL sessions that can be kept in memory. Defaults to 32. If there are more than 32 simultaneous SSL sessions, this does not prevent another SSL connection from being established, but means that no more SSL sessions are cached. A cache size of 0 means no cache, and no outbound SSL connections are cached.

At DEBUG level or higher, the API Gateway outputs trace when an entry goes into the cache, for example:

DEBUG   09:09:12:953 [0d50] cache SSL session 11AA3894 to support.acme.com:443

If the cache is full, the output is as follows:

DEBUG   09:09:12:953 [0d50] enough cached SSL sessions 11AA3894 to 
support.acme.com:443 already

Ephemeral DH key parameters:

The Diffie Hellman (DH) key agreement algorithm is used to negotiate a shared secret between two SSL peers. This enables two parties without prior knowledge of each other to jointly establish a shared secret key over an insecure communication channel. The Ephemeral DH key parameters setting specifies the parameters used to generate the DH keys.

When DH key parameters are not specified, the SSL client uses the public RSA key in the server's certificate to encrypt data sent to the SSL server, and establish a shared secret with the server. However, if the RSA key is ever discovered, any previously recorded encrypted conversations can be decrypted. DH key agreement offers Perfect Forward Secrecy (PFS) because there is no such key to be compromised.

There are two options when setting the DH parameters: you can enter a number (for example, 512), and the server automatically generates DH parameters with a prime number of the correct size. Alternatively, you can paste the Base64 encoding of an existing serialized DH parameters file. You can use standard DH parameters based on known good prime numbers. OpenSSL ships with the dh512.pem and dh1024.pem files. For example, you can set the DH parameters to the following Base64-encoded string in pdh512.pem:

-----BEGIN DH PARAMETERS-----
MEYCQQD1Kv884bEpQBgRjXyEpwpy1obEAxnIByl6ypUM2Zafq9AKUJsCRtMIPWakXUGfnHy9iUsiGSa6q6Jew1X
pKgVfAgEC
-----END DH PARAMETERS-----

The DH parameters setting is required if the server is using a DSA-keyed certificate, but also has an effect when using RSA-based certificates. DH (or similar) key agreement is required for DSA-based certificates because DSA keys cannot be trivially used to encrypt data like RSA keys can.

SSL Protocol Options:

You can configure the following SSL protocol options:

A Relative Path binds policies to a specific relative path location (for example /healthcheck). When the API Gateway receives a request on this relative path, it invokes the specified policies. For details on how to configure policies, see Part 4, “Governance”.

To configure a Relative Path for a given HTTP Service Group, under the Service Group in the tree view, right-click Paths, and select Add Relative Path. Alternatively, you can also click the Add Relative Path button at the bottom of the policy canvas beside the Context drop-down list. Complete the following settings on the Configure Relative Path dialog:

Enable this path resolver:

You can specify whether to enable listening on the specified path. This is enabled by default.

Policies:

On the Policies tab, specify the relative path and the policies that are called. The API Gateway invokes the selected policies when it receives a request on the specified path. You can specify a single policy or a chain of policies. Policies are called in the order displayed on this tab. Complete the following fields:

When you select multiple policies to form a policy chain, the behavior is the same as for a policy shortcut chain filter. Policies are only evaluated when selected, and when the policy can be reached. If any reachable policy fails, the chain fails, and no more policies are evaluated.

Audit Settings:

The Audit Settings tab enables you to configure the logging level for all filters executed on the relative path, and to configure when message payloads are logged.

You can configure the following Logging Level settings on all filters executed on the specified relative path:

For more details on logging levels, and on how to configure logging for a specific filter, see the Log Level and Message topic.

You can configure the following Payload Logging settings on the specified relative path:

For details on how to log message payloads at any point in a specific policy, see the Log Message Payload topic.

Select the Include in server access log records setting if you wish to add this relative path to the API Gateway Access Log. This enables the Access Log at the service level. This setting is not selected by default. For more details, see the topic on Access Log Settings.

HTTP Method:

The HTTP Method tab enables you to configure an accepted HTTP Method (for example, POST). The default is *, which means that all HTTP Methods are accepted. You can override the default behavior, and select an appropriate HTTP method for the relative path from the list.

You can configure multiple HTTP methods on paths of the same name. This enables you to call different policies for different HTTP methods, as shown in the following example:

In this example, the /test path is configured three times, each using a different HTTP Method as follows:

A Web Service Resolver is used to identify messages destined for a Web Service, and to map them to the Service Handler (Web Service Filter) for that Web Service. When you import a WSDL file, a new Web Service Resolver node is created for each imported Web Service in the Services tree view. You can edit the Web Service Resolver settings by right-clicking this tree node, and selecting Edit.

The following settings are available in the Web Service Resolver dialog:

Enable this web service resolver:

Specify whether to enable this Web Service resolver. This is enabled by default.

Name:

You can edit the name of the Web Service Resolver.

Web Service:

Click the browse button to select a Web Service to resolve to. Defaults to the Web Service imported into the Web Services Repository when this resolver was created.

Policy:

On the Policy tab, select the path and the policies to use for the Web Service. You can specify a single policy or a chain of policies. Policies are called in the order displayed on this tab. The global request policy, the policy automatically generated when the WSDL file is imported, and the global response policy are all selected in a chain by default. Complete the following fields:

Policies are only evaluated when selected, and when the policy can be reached. If any selected policy fails, the chain fails, and no more policies are evaluated.

Audit:

The Audit tab enables you to configure the logging level for all filters executed on the Web Service, and to configure when message payloads are logged. The default logging level for all filters on the Web Service is Failure. These logging settings are the same as those already described for the Audit tab used for the Relative Path. For more details, see Relative Paths.

Editing Service Handler Options

You also edit options for the Service Handler for the Web Service. Right-click the Web Service Resolver node, and select Quick-Edit Policy to display a dialog that enables you to configure the following options:

These options enable you to configure the underlying auto-generated Service Handler (Web Service Filter) without navigating to it in the Policies tree. These are the most commonly modified Web Service Filter options after importing a WSDL file. Changes made in this dialog are visible in the underlying Web Service Filter. For more details, see the Web Service Filter topic.

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 API Gateway instance, and select the Static Content Provider menu option. Complete the following fields on the General tab:

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.

HTTP Method:

The HTTP Method tab enables you to configure an accepted HTTP Method (for example, POST). The default is *, which means that all HTTP Methods are accepted. You can override the default behavior, and select an appropriate HTTP method for this resolver from the list.

Developers may wish to write their own Java servlets and deploy them under the API 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 API Gateway is running.

There are a few default Servlet Applications available under the Management Services group. By default, this services group is not displayed, but can be displayed using the Preferences dialog in the Policy Studio. For example, the /configuration/ Servlet Application updates configuration information for the API Gateway.

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.

HTTP Method:

The HTTP Method tab enables you to configure an accepted HTTP Method (for example, POST). The default is *, which means that all HTTP Methods are accepted. You can override the default behavior, and select an appropriate HTTP method for this resolver from the list.

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 API 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.

The Management Services group exposes a number of services used by the Admin Node Manager and Oracle API Gateway Analytics for remote configuration and monitoring. By default, this group is not displayed in the Policy Studio tree view. However, you can view it by selecting the Window -> Preferences main menu option, and selecting Show Management Services. 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:

By default, the Admin Node Manager 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 API Gateway configuration data. By default, the Oracle API Gateway Analytics exposes all its management services on port 8040. For more details, see the section called “Changing the Management Services Port”.

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:

Servlet Application: /configuration/

The Policy Studio running on a different host to the API Gateway can connect to this URL to remotely configure the API Gateway. For example if the API 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 API Gateway on the SERVER host.

The default Management Services port used by the Admin Node Manager is 8090. To specify a different port, perform the following steps: