Configure HTTP services

Overview

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 Static content providers.
  • 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 Axway Support team. For more details, see Servlet applications.
  • 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.

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

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.

Default HTTP service groups

By default, the API Gateway ships with preconfigured HTTP services groups (for example, Default Services and Sample Services). These groups contains some general purpose default policies for use with an out-of-the-box installation of 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 details on the default service group used by the Admin Node Manager and API Gateway Analytics, see Configure management services.

Add an HTTP service group

To add a service group, perform the following steps:

  1. Right-click the API Gateway instance, and select Add HTTP Services.
  2. Enter a name for the group in the HTTP Services dialog.
  3. 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.
  4. 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 Add a CORS profile.

When an HTTP service group is created, you can configure it with the HTTP services described in this topic.

HTTP and HTTPS interfaces

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, select the HTTP Service group in the Policy Studio tree (for example, Environment Configuration > Listeners > API Gateway > Default Services). Right-click the Ports node, and select Add HTTP or Add HTTPS.

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

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

Configure Traffic Monitor settings

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.

Configure 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 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 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 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 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:
Click the browse button, and select a Threat Protection Profile to protect this interface with Apache ModSecurity threat protection rules. ModSecurity 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.

If no threat protection profiles have been configured, right-click the Threat Protection Profiles node in the dialog, and select Add a Threat Protection Profile. Configure the following settings:

  • Name: Enter a required profile name to display in Policy Studio.
  • Configuration directory: Enter the name of the directory that stores the threat protection configuration file. Defaults to ${environment.VDISTDIR}/system/conf/threat-protection/default.
  • Configuration file: Enter the threat protection configuration file name. Defaults to modsecurity.conf.
  • Rules directory: Enter the name of the subdirectory that stores the threat protection rules. Defaults to activated_rules.
  • Alert policy: Select an optional API Gateway policy to execute when a threat protection rule is triggered.

No threat protection profile is selected by default. When a profile is selected, all traffic is processed by the ModSecurity engine, and threats are rejected based on the configured rules. For more details on API firewalling, see the API Gateway Administrator Guide.

Configure 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 Configure conditions for HTTP interfaces.

HTTPS interfaces only

This section describes settings that apply to HTTPS interfaces only.

Configure Network settings

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.

For more details, see Manage X.509 certificates and keys in the API Gateway Policy Developer Guide.

Configure Mutual Authentication settings

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.

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

  1. Click the Add button to configure a server host name in the SSL Server Name Identifier (SNI) dialog.
  2. Specify the server host name in the Client requests server name field.
  3. Click Server assumes identity to import a Certificate Authority certificate into the 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. The default cipher string of FIPS:!SSLv3:!aNULL performs the following:

  • Enables FIPS-compatible cipher suites only
  • Explicitly blocks cipher suites that require SSLv3 or lower
  • Forces the use of TLSv1.2 only
  • Forbids unauthenticated cipher suites

For more information on the syntax of this setting, see the OpenSSL documentation:

https://www.openssl.org/docs/man1.0.2/apps/ciphers.html

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   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:
This setting specifies the parameters used to generate Diffie Hellman (DH) keys. The 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.

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 DH key parameters:

  • Enter a number (for example, 512 ), and the server automatically generates DH parameters with a prime number of the correct size.
  • 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.

Note   The EDH key is always used once only to guarantee forward secrecy. This ensures that if the key is compromised, previous keys will not be compromised.

SSL Protocol Options:
You can configure the following SSL protocol options:

Option Description
Do not use the SSL v2 protocol Specifies not to use SSL v2 for incoming connections to avoid any weaknesses in this protocol. This is selected by default.
Do not use the SSL v3 protocol Specifies not to use SSL v3 for incoming connections to avoid any weaknesses in this protocol. This is selected by default.
Do not use the TLS v1 protocol Specifies not to use TLS v1.0 for incoming connections to avoid any weaknesses in this protocol. This is selected by default.
Do not use the TLS v1.1 protocol Specifies not to use TLS v1.1 for incoming connections to avoid any weaknesses in this protocol. This is selected by default.
Do not use the TLS v1.2 protocol Specifies not to use TLS v1.2 to avoid any weaknesses in this protocol. This 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:

https://www.openssl.org/docs/man1.0.2/apps/ciphers.html

Configure management services

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 interfaces and policies are displayed in the Policy Studio tree:

  • The Management Services policy container is displayed under the Policies node.
  • The Management Services HTTP interfaces are displayed under the Environment Configuration > Listeners node.
Note   Changing the HTTP interfaces, relative path, servlet applications, or static content provider exposed under the Management Services group can prevent the Admin Node Manager from functioning correctly. Because of this, the Management Services group should only be modified under strict supervision from the Axway Support team.

Management services group

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 Change the management services port.

For details on how to use the Management Services interface to configure HTTP security headers included in the API Gateway response, see Customize HTTP security headers.

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

Request processing cycle

For example, with the default configuration, assume that a request is received on http://localhost:8090/api. 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. 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 /api/. Because the request is received on the /api/ path, this matches the /api/ Servlet, which is invoked.

Change the management services port

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

  1. Select the Environment Configuration > Listeners > Node ManagerManagement Services > Ports node in the Policy Studio tree.
  2. In the Interfaces pane on the right, right-click the Management HTTPS 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. Use the updated port number in the URL to reconnect Policy Studio (for example, https://HOST:8091/api).

Customize HTTP security headers

You can also edit the Management Services group used by the Admin Node Manager to customize the HTTP security headers that are included in the API Gateway response (on port 8090). You can edit the Admin Node Manager configuration using either Policy Studio or Entity Explorer.

Edit Admin Node Manager configuration in Policy Studio

Perform the following steps:

  1. In Policy Studio, select File > New Project, enter a project Name, and click Next.
  2. Select From existing configuration for the project starting point, and click Next.
  3. Click the browse button, select the following directory, and click Finish:
  4. INSTALL_DIR/apigateway/conf/fed
  5. Select the Environment Configuration > Listeners > Node ManagerManagement Services > Paths node in the Policy Studio tree.
  6. In the Resolvers pane on the right, under Paths > /, right-click the / Static Content node, and select Edit.
  7. On the General tab in the dialog, under Add additional headers to HTTP responses, click Add.
  8. Enter the HTTP security header name/value pair in the dialog. For example:
    • HTTP Header: X-XSS-Protection
    • Value: 1; mode=block
  1. Repeat to add any additional HTTP security header name/value pairs (for example, Strict-Transport-Security or Public-Key-Pins).
  2. In the Resolvers pane, under Paths, right-click the Login Static Content node, and select Edit.
  3. On the General tab in the dialog, under Add additional headers to HTTP responses, click Add to add the HTTP security headers that you added under the / Static Content node.
  4. After editing the configuration, manually copy the project .xml and .md5 files (for example, in C:\Users\dev\apiprojects) to INSTALL_DIR/conf/fed/, and make a backup.
  5. Restart the Admin Node Manager.

Edit Admin Node Manager configuration in Entity Explorer

Perform the following steps:

  1. Change to the following directory:
  2. INSTALL_DIR/apigateway/posix/bin
  3. Enter the esexplorer command.
  4. Select Store > Connect, and browse to the following file:
  5. INSTALL_DIR/apigateway/conf/fed/configs.xml
  6. In the tree on the left, select System Components > ServiceManagement Services > /,*, expand the /,* Static Content node, and right-click to select Add a new Property.
  7. In the name row on the right, double-click the Value field, and enter the name of the HTTP security header (for example, X-XSS-Protection).
  8. Right-click under this field, select Create a value, and in the value row, double-click to enter the Value of the HTTP security header (for example, 1; mode=block).
  1. Repeat to add any additional HTTP security header name/value pairs (for example, Strict-Transport-Security or Public-Key-Pins).
  2. Click Update to save the changes.
  3. Select System Components > ServiceManagement Services, expand the /login/,* Static Content node, right-click to select Add a new Property, and add the HTTP security headers that you added under the /,* Static Content node.
  4. Click Update to save the changes.
  5. Restart the Admin Node Manager.
Note   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 Axway Support team.

Related Links