Contents
The Connection filter makes the connection to the remote Web Service. It relies on connection details that are set by the other filters in the Routing category. Because the Connection filter connects out to other services, it negotiates the SSL handshake involved in setting up a mutually authenticated secure channel.
Depending on how the API Gateway is perceived by the client, different combinations of routing filters can be used. For an introduction to using the various filters in the Routing category, see the topic on Getting Started with Routing Configuration.
Enter an appropriate name for the filter in the Name field. Click the tabs to configure the various aspects of the Connection filter.
This section lists all CA certificates that have been imported into the Oracle Certificate Store. Select the certificates that the API Gateway considers to be trusted when it attempts to establish a connection to a remote server. The remote server's SSL certificate must be issued by one of the selected trusted certificates on this tab.
You can configure the API Gateway to authenticate itself to the remote Web Service. It does so using the certificate selected on this tab.
The API Gateway can use both HTTP basic and HTTP digest authentication to authenticate to the remote server. In both cases, the User Name and Password of a user must be specified in the fields provided.
The settings on this tab enable you to authenticate to a Kerberos Service by sending a Kerberos service ticket in the HTTP request to that service.
Note | |
---|---|
You can also configure the API Gateway to authenticate to a Kerberos Service by including the relevant Kerberos tokens inside the XML message. For more details, see the Kerberos Client Authentication topic. |
Kerberos Client:
The selected Kerberos Client has two roles. First, it must obtain a Kerberos TGT (Ticket Granting Ticket). Second, it uses this TGT to obtain a service ticket for the Kerberos Service Principal selected below.
Click the button on the right, and select a previously configured Kerberos Client in the tree. To add a Kerberos Client, right-click the Kerberos Clients tree node, and select Add Kerberos Client. Alternatively, you can add Kerberos Clients under the External Connections node in the Policy Studio tree view. For more details, see the Kerberos Clients topic.
Kerberos Service Principal:
The Kerberos Client selected above must obtain a ticket from the Kerberos Ticket Granting Server (TGS) for the selected Kerberos Service Principal. The Service Principal can be used to uniquely identify the Service in the Kerberos realm. The TGS grants a ticket for the selected Principal, which the client can then send to the Kerberos Service. The Principal in the ticket must match the Kerberos Service's Principal for the client to be successfully authenticated.
Click the button on the right, and select a previously configured Kerberos Principal
in the tree (for example, the default HTTP/host Service Principal
). To
add a Kerberos Principal, right-click the Kerberos Principals tree
node, and select Add Kerberos Principal.
Alternatively, you can add Kerberos Principals under the External
Connections node in the Policy Studio tree view. For more details, see the
topic on Kerberos Principals.
Send token with first request:
In some cases, the client may not authenticate (send the Authorization
HTTP header) to the Kerberos Service on its first request. The Kerberos Service should
then respond with an HTTP 401 response containing a WWW-Authenticate:
Negotiate
HTTP header. This header value instructs the client to authenticate
to the server by sending up the Authorization
header. The client then
sends up a second request, this time with the Authorization
header,
which contains the relevant Kerberos token. Select this option to force the
Connection filter to always send the
Authorization
HTTP header that contains the Kerberos Service ticket
on its first request to the Kerberos Service.
Send body only after establish context:
You can configure the Kerberos client to only send the message body after the context has been fully established (the client has mutually authenticated with the service).
Pass when service returns 200 even if context not established:
In some rare cases, a Kerberos Service may return a 200 OK
response to a Kerberos Client's initial request even though the security
context has not yet been fully established. This 200 OK
response may not contain the WWW-authenticate
HTTP
header.
By selecting this option, you are instructing the Connection filter to send the request to the Kerberos Service despite that the context has not been established. It is the responsibility of the Kerberos Service to decide whether to process the request depending on the status of the security context.
The Behavior tab enables you to configure Retries and Failure Settings. By default, both of these sections are collapsed. Click a section to expand it.
Retries:
To specify the retry settings for this filter, complete the following fields:
Perform Retries | Select whether the filter performs retries. By default, this setting is not selected, no retries are performed, and all Retries settings are disabled. This means that the filter only attempts to perform the connection once. |
Retry On |
Select the HTTP status ranges on which retries can be performed. If a host
responds with an HTTP status code that matches one of the selected ranges,
this filter performs a retry. Select one or more ranges in the table (for
example, Client Error 400-499 ). For details on adding custom
HTTP status ranges, see the next subsection.
|
Retry Count |
Enter the maximum number of retries to attempt. The default is 5 .
|
Retry Interval (ms) |
Enter the amount of time to delay between retries in milliseconds. The default
is 500 ms.
|
Adding HTTP Status Ranges
To add an HTTP status range to the default list displayed in the Retry On table, click the Add button. In the Configure HTTP Status Code dialog, complete the following fields:
Name | Enter a name for the HTTP status range. |
Start status | Enter the first HTTP status code in the range of status codes that you wish to monitor. |
End status | Enter the last HTTP status code in the range of status codes that you wish to monitor. |
If you wish to monitor one specific status code only, enter the same code in
the Start status and End status fields. Click
OK to finish. You can manage existing HTTP status ranges using
the Edit and Delete buttons.
Failure Settings:
To specify the failure settings for this filter, complete the following fields:
Consider SLA Breach as Failure |
Select whether to attempt the connection if a configured SLA has been
breached. This is not selected by default. If this option is selected,
and an SLA breach is encountered, the filter returns false .
|
Save Transaction on Failure (for replay) | Select whether to store the incoming message in the specified directory and file if a failure occurs during processing. This is not selected by default. |
File name |
Enter the name of the file that the message content is saved to. You can
specify this using a selector, which is expanded to the specified value at
runtime. Defaults to ${id}.out . For more details on
selectors, see Selecting Configuration Values at Runtime.
|
Directory |
Enter the directory that the file is saved to. You can specify this using
a selector, which is expanded to the specified value at runtime. Defaults
to ${environment.VINSTDIR}/message-archive , where
VINSTDIR is the location of a running API Gateway
instance.
|
Maximum number of files in directory |
Enter the maximum number of files that can be saved in the directory.
Defaults to 500 .
|
Maximum file size |
Enter the maximum file size in MB. Defaults to 1000 .
|
Include HTTP Headers | Select whether to include HTTP headers in the file. HTTP headers are not included by default. |
Include Request Line | Select whether to include the HTTP request line from the client in the file. The request line is not included by default. |
Call policy on Connection Failure | Select whether to execute a policy in the event of a connection failure. This is not selected by default. |
Connection Failure Policy | Click the browse button on the right, and select the policy to run in the event of a connection failure in the dialog. |
This tab enables you to configure certain advanced features of the Connection filter. The following configuration options are available:
Handles Redirects:
Specifies whether the API Gateway handles HTTP redirects, and connects to the redirect URL specified in the HTTP response. This setting is enabled by default.
Forward spurious received Content headers:
Specifies whether the API Gateway sends any content-related message headers
when sending an HTTP request with no message body to the HTTP server. For
example, you can select this setting if content-related headers are required
by an out-of-band agreement. If there is no body in the outbound request, any
content-related headers from the original inbound HTTP request are forwarded.
These are extracted from the http.content.headers
message attribute,
which is generally populated by the API Gateway for the incoming call. This
attribute can be manipulated in a policy using the appropriate filters,
if required. This setting is not enabled by default.
Send via Proxy:
Select this option if the API Gateway must connect to the destination Web
Service through an HTTP proxy. In this case, the API Gateway includes
the full URL of the destination Web Service in the request line of the
HTTP request. For example, if the destination Web Service resides at
http://localhost:8080/services
, the request
line is as follows:
POST http://localhost:8080/services HTTP/1.1
If the API Gateway is not routing through a proxy, the request line is as follows:
POST /services HTTP/1.1
Proxy Server:
When Send via Proxy is selected, you can configure a specific proxy server to use for the connection. Click the button next to this field, and select an existing proxy server in the dialog. To add a proxy server, right-click the Proxy Servers tree node, and select Add a Proxy Server. Alternatively, you can configure Proxy Servers under the External Connections node in the Policy Studio tree. For more details, see the topic on Proxy Servers.
Transparent Proxy (present client's IP address to server)
Enables the use of the API Gateway as a transparent proxy
on Linux systems with the TPROXY
kernel option set. When selected,
the IP address of the original client connection that caused the policy
to be invoked is used as the local address of the connection to the destination
server.
For more details, see Configuring a Transparent Proxy.
Ciphers:
The Ciphers field enables the administrator to specify the ciphers that the server supports. The server sends this list of supported ciphers to the destination server, which then selects the highest strength common cipher as part of the SSL handshake. The selected cipher is then used to encrypt the data as it is sent over the secure channel.
HTTP Host Header:
An HTTP 1.1 client must send a Host
header in all HTTP 1.1 requests. The Host
header identifies
the host name and port number of the requested resource as specified in the
original URL given by the client.
When routing messages on to target Web Services, the API Gateway can forward on
the Host
as received from the client, or it can specify the
address and port number of the destination Web Service in the Host
header that it routes onwards.
Select Use Host header specified by client to force
the API Gateway to always forward on the original Host
header that it received from the client. Alternatively, to configure
the API Gateway to include the address and port number of the destination Web
Service in the Host
header, select the
Generate new Host header radio button.