# Connect to URL

## Contents
Overview General Configuration Trusted Certificates Client SSL Authentication HTTP Authentication Kerberos Authentication Behavior Advanced

## Overview
The Connect to URL filter is the simplest routing filter to use to connect to a target Web Service. To configure this filter to send messages to a Web Service, you need only enter the URL of the service in the URL field. If the Web Service is SSL enabled or requires mutual authentication, you can use the other tabs on the Connect to URL filter to configure this. Depending on how the Enterprise Gateway is perceived by the client, different combinations of routing filters can be used. Using the Connect to URL filter is equivalent to using the following combination of routing filters: Static Router Rewrite URL Connection The Connect to URL filter enables the Enterprise Gateway to act as the endpoint to the client connection (and not as a proxy), and to hide the deployment hierarchy of protected Web Services from clients. In other words, the Enterprise Gateway performs service virtualization. For an introduction to routing scenarios and the filters in the Routing category, see the Getting Started with Routing Configuration topic.
## General Configuration
Configure the following general settings: Name: Enter an appropriate name for the filter. URL: Enter the complete URL of the target Web Service.
## Trusted Certificates
When Enterprise Gateway connects to a server over SSL, it must decide whether to trust the server's SSL certificate. You can select a list of CA or server certificates from the Trusted Certificates tab that are considered trusted by Enterprise Gateway when connecting to the server specified in the URL field on this dialog. The table displayed on the Trusted Certificates tab lists all certificates imported into the Enterprise Gateway Certificate Store. To trust a certificate for this particular connection, select the box next to the certificate in the table.
## Client SSL Authentication
In cases where the destination server requires clients to authenticate to it using an SSL certificate, you must select a client certificate on the Client SSL Authentication tab. Select the checkbox next to the client certificate that you want to use to authenticate to the server specified in the URL field.
## HTTP Authentication
If the destination server requires clients to authenticate to it using HTTP basic or digest authentication, use the fields on this tab. None, HTTP Basic, or HTTP Digest: Select the method that you want to use to authenticate to the server. User Name: Enter the user name you want to use to authenticate to the server. Password: Enter the password for this user.
## Kerberos Authentication
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 Enterprise 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. You can configure Kerberos Clients globally on the External Connections tab in the Policy Studio. These can then be selected in the Kerberos Client drop-down list. For more details on configuring Kerberos Clients, see the Kerberos Client topic. Kerberos Service Principal: The Kerberos Client selected in the drop-down list 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. You can also configure Kerberos Principals globally on the External Connections tab in the Policy Studio. For more details on configuring Kerberos Principals, see the Kerberos Principals topic. 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 Connect to URL 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 Connect to URL filter to send the request to the Kerberos Service even if 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.
## Behavior
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 property, which is expanded to the specified value at runtime. Defaults to `${id}.out`.
Directory | Enter the directory that the file is saved to. You can specify this using a property, which is expanded to the specified value at runtime. Defaults to `${VINSTDIR}/message-archive`, where `VINSTDIR` is the root of your Enterprise Gateway installation.
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.
Call policy on Connection Failure | Select whether to execute a policy circuit 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.
## Advanced
This tab enables you to configure certain advanced features of the Connect to URL filter. The following configuration options are available: Handles Redirects: Specifies whether the Enterprise Gateway handles HTTP redirects, and connects to the redirect URL specified in the HTTP response. This setting is enabled by default. Send via Proxy: Select this option if the Enterprise Gateway must connect to the destination Web Service through an HTTP proxy. In this case, the Enterprise 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 Enterprise Gateway was not routing through a proxy, the request line is as follows:
    POST /services HTTP/1.1
Proxy Server: You can configure a specific proxy server to use for the connection in the Proxy Server field. Click the button next to this field, and select an existing proxy server in the dialog. You must have already configured the proxy server on the External Connections tab. For more details, see the Proxy Servers topic. Transparent Proxy (present client's IP address to server) Enables the use of the Enterprise 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 circuit 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 Enterprise Gateway supports. The Enterprise Gateway 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 hostname 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 Enterprise 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 Enterprise Gateway to always forward on the original `Host` header that it received from the client. Alternatively, to configure the Enterprise 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.