Contents
The API Gateway uses HTTP Services to handle traffic from various HTTP-based sources. The available HTTP Services are as follows:
HTTP interfaces
HTTP interfaces define the ports and IP addresses on which the API Gateway instance listens for incoming requests. You can also add HTTPS interfaces to specify SSL certificates to authenticate to clients, and certificates considered trusted for establishing SSL connections with clients.
Relative path
You can configure relative paths so that when a request is received on a specific path, the API Gateway instance can map it to a specific policy, or chain of policies. For more details, see Configure relative paths.
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. For more details, see Configure relative paths
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. For more details, see Configure relative paths
Packet sniffer
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, you could 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 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 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.
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:
| 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
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.
By default, the API Gateway ships with preconfigured 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 preconfigured service groups, you can add new HTTP
services groups 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”.
To add a service group, perform the following steps:
-
Right-click the API Gateway instance, and select Add HTTP Services.
-
Enter a name for the group in the HTTP Services dialog.
-
To enable Cross Origin Resource Sharing (CORS) for this HTTP service, select CORS tab, and click the button on the right to select a preconfigured CORS profile. By default, no profile is selected, which means that CORS is disabled. For details on CORS, see Cross-Origin Resource Sharing.
-
In the Select CORS Profile dialog, if no profiles have already been configured, right-click CORS Profiles, and select Add a CORS Profile. You can also right-click an existing profile, and select Edit to update its settings. For details on CORS settings, see the section called “Add a CORS profile”.
When an HTTP service group is created, you can configure it with the HTTP services described in this topic.
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.
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:
-
FATAL -
ERROR -
INFO -
DEBUG -
DATA
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.
The fields on the Traffic Monitor tab are common to the HTTP Interface and HTTPS Interface dialogs. To override the system-level settings at HTTP or HTTPS interface level, select Override settings for this port, and configure the relevant options. For more details, see the API Gateway Administrator Guide.
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 the API Gateway instance allows the operating system to accept and queue up until the instance is ready to read them. 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 in bytes that the API Gateway instance allocates to each request. For more details, see General settings in the API Gateway Administrator Guide.
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 Configure a transparent proxy.
Include correlation ID in headers:
Specifies whether to insert the correlation ID in outbound messages. For the
HTTP transport, this means that an X-CorrelationID header is added
to the outbound message. This is a transaction ID that is tagged to each message
transaction that passes through the API Gateway, and which is used for traffic
monitoring in the API Gateway Manager web console.
You can use the correlation ID to search for messages in the console. You can also
access the its value using the id message attribute in an API Gateway
policy. An example correlation ID value is Id-54bbc74f515d52d71a4c0000.
This setting is selected by default.
Threat Protection Settings:
Select whether to Protect this interface with Threat Protection rules using Apache ModSecurity. This is a toolkit for real-time HTTP traffic monitoring, logging, and access control, which helps to mitigate application-level threats to APIs. The ModSecurity engine is embedded in API Gateway to provide API firewalling. This setting is not selected by default. When this is selected, all traffic is processed by the ModSecurity engine, and threats are rejected based on the configured rules. For more details, see the API Gateway Administrator Guide.
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 details, see the Configure conditions for HTTP interfaces topic.
This section describes settings that apply to 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 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.
You can configure clients to authenticate to the API Gateway on the Mutual Authentication tab. The following options are available:
-
Ignore Client Certificates
The API Gateway ignores client certificates if they are presented during the SSL handshake.
-
Accept Client Certificates
Client certificates are accepted when presented to the API Gateway, but clients that do not present certificates are not rejected.
-
Require Client Certificates
The API 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.
A chain of CAs can also issue 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 is then 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.
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 host names requested by clients in the SSL Server Name Identifier (SNI) table. SNI is an optional TLS feature where the client indicates to the server the host name used to resolve the server 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 host name 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 host name the client uses to resolve
the address, because it is not party to the client DNS name resolution. The server
may certify itself as either service, but when the connection is established, it
does not know which host name 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 host name.
To specify an SNI, perform the following steps:
-
Click the Add button to configure a server host name in the SSL Server Name Identifier (SNI) dialog.
-
Specify the server host name in the Client requests server name field.
-
Click Server assumes identity to import a Certificate Authority certificate into the Certificate Store.
-
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, 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.
![[Tip]](../common_oracle/images/admon/tip.png) |
Tip |
|---|---|
|
You can use this setting to improve performance because it caches the slowest part of establishing the SSL connection. A new connection does not need to go through full authentication if it finds its target in the cache. |
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:
| Option | Description |
|---|---|
| Use EDH key once only | Creates a new key from the DH parameters for every SSL session. This is not strictly necessary if you are sure of the quality of the prime number in the DH key parameters. When using well-known DH parameters like the example above, you can leave this option unselected. However, given a bad prime number in the parameters, gathering enough key exchanges from a single DH key can allow an eavesdropper to work out the DH key used. Selecting this option slows down the SSL session establishment and has a negative impact on performance. |
| Do not use the SSL v1 protocol | Specifies not to use SSL v1 to avoid any weaknesses in this protocol. This option is not selected by default. |
| Do not use the SSL v2 protocol | Specifies not to use SSL v2 to avoid any weaknesses in this protocol. This option is not selected by default. |
| Do not use the SSL v3 protocol | Specifies not to use SSL v3 to avoid any weaknesses in this protocol. This option is not selected by default. |
| Do not use the TLS v1 protocol | Specifies not to use TLS v1 to avoid any weaknesses in this protocol. This option is not selected by default. |
| Prefer local cipher preferences over client's proposal | When choosing a cipher during the SSL/TLS handshake, the client's preferences are selected by default from the list of ciphers supported by the client and the server. When this option is selected, the server's preferences are used instead. This option is not selected by default. For more details on ciphers, see the OpenSSL documentation |
The Management Services group exposes a number of services used by the Admin Node Manager and API Gateway Analytics for remote configuration and monitoring. The Management Services server process, interfaces, and policies are displayed in the Policy Studio tree. The Management Services policy container is displayed in the tree under the Policies node. The Management Services HTTP interfaces are displayed under the Listeners node under the server instance.
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 API Gateway Analytics
exposes all its management services on port 8040. For more details, see
the section called “Change 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 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:
-
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. -
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.
-
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.
-
The configured Servlets and Content Providers for the Management Services group include
/configuration/and/api/. 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 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.
![[Important]](../common_oracle/images/admon/important.png) |
Important |
|---|---|
|
Changing the interfaces, relative path, servlet applications, or static content provider exposed under the Management Services group may prevent the Admin Node Manager 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. |
The default management services port used by the Admin Node Manager is 8090. To specify a different port, perform the following steps:
-
Under the Listeners node in the Policy Studio tree, right-click the Management Services HTTP Interface, and select Edit.
-
Specify an updated value in the Port field (for example,
8091), and click OK. -
Click the Deploy button in the Policy Studio toolbar, or press F6 to deploy the update.
-
Restart Policy Studio. You must restart Policy Studio when Management Services are updated.
-
Use the updated port number in the URL to reconnect Policy Studio (for example,
https://HOST:8091/api).
|
Important |
|---|---|
|
Management Services apply to the Admin Node Manager and API Gateway Analytics only. You should only modify Management Services under strict advice and supervision from the Oracle Support team. |
