Route via FTP(S) Assertion

gateway90
The
Route via FTP(S)
assertion is used to route requests from the Gateway to a back-end FTP(S) server, using passive mode FTP. You can configure the port number to use and which directory to use on the remote FTP server.
(1) The Gateway can be configured as an FTP(S) server in order to support FTP proxying. For more information, see Working with FTP Requests. (2) The Gateway does not support the use of elliptic curve certificates (ECC) as the client certificate for an outbound TLS connection.
If the routing is successful, the response message will contain the reply from the remote FTP server. For uploads, the response body will be empty; for lists or download requests, the body will contain the listing/file contents. The reply code and message from the remote FTP server will be set in the target message and made available in these context variables:
${
<prefix>
.ftp.replycode}
${
<prefix>
.ftp.replytext}
Where
"<prefix>"
is:
  • "response" if the Message Target is "Response"
  • the name of the target message variable if the Message Target is "Message Variable"
The Message Target is set in the [Connection] tab of the FTP(S) Routing Properties.
Example: Requesting the last modified time of a file
This simple example shows how you can use the Route via FTP(S) assertion to retrieve the modified timestamp of a file on a remote server using a HTTP GET Request and how the reply code and message are populated into context variables.
Precondition:
  • There is a remote FTP server "ftp.example.com" hosting the file
    /log_files/log.txt
    .
To request the modified timestamp from a remote server:
  1. Create the following simple policy fragment (properties settings to follow):
    Route via FTPS Server ftp.example.com
    Return Template Response to Requestor
  2. Configure the [Connection] tab in the FTP(S) Routing Properties as follows:
    • Protocol:
      FTPS with Explicit SSL (AUTH TLS/SSL)
    • Host name:
      ftp.example.com
    • Select "
      Verify server certificate
      "
    • Command:
      MDTM
    • Message Target:
      Message Variable
    • Target Message Variable:
      output
    • Directory:
      /log_files
    • Arguments:
      log.txt
    • Assertion Outcome:
      Fail on Transient or Permanent Negative Completion reply code
  3. Configure the Template Response Properties as follows:
    • Response HTTP Status:
      200
    • Response Content Type:
      text/html; charset=UTF-8
    • Response Body:
      <html><body> RESPONSE: ${output.ftp.replycode} ${output.ftp.replytext} </body></html>
This is the example in action:
  1. The service policy receives and processes an HTTP GET request.
  2. The Route via FTP(S) assertion retrieves the last modified date (MDTM command) of the file of specified file ('Directory' and 'Arguments') from the remote FTP server ('Host name').
  3. The success reply code and last modified date of the file are made available through the context variables
    ${output.ftp.replycode}
    and
    ${output.ftp.replytext}
    .
  4. The Return Template Response to Requestor Assertion returns an HTML message with the reply details to the client; for example:
    <html><body>
    RESPONSE: 213 20140224231131.616
    </body></html>
For a list of the supported FTP commands, see Listen Port Properties. For an example of how this assertion can be used with the listen ports to configure an extended FTP command support proxy, see Configuring the [FTP Settings] Tab.
FTP Cluster Properties for This Assertion
The cluster properties described in FTP Cluster Properties define the default FTP(S) listen port behavior. The following cluster properties are specific to the Route via FTP(S) assertion and have no effect on any listen ports.
Property
Description
ftp.globalMaxDownloadConcurrency
The maximum number of FTP downloads that may be executed concurrently by Route via FTP(S) assertions. This is a global limit across all such assertions.
Default:
64
ftp.globalMinDownloadConcurrency
The core number of FTP downloads that may be executed concurrently by Route via FTP(S) assertions. This is a global limit across all such assertions.
This is the number of threads in the pool under normal circumstances. Higher workloads will cause more threads to be created, up to the maximum defined by
ftp.globalMaxDownloadConcurrency
.
 
Default:
32
ftp.globalMaxDownloadQueue
The maximum number of FTP downloads that may be waiting to execute concurrently by Route via FTP(S) assertions. This is a global limit across all such assertions.
Default:
64
Using the Assertion
  1. Do one of the following:
    • To add the assertion to the Policy Development window, see Adding an Assertion.
    • To change the configuration of an existing assertion, proceed to step 2 below.
  2. When adding the assertion, the
    FTP(S) Routing Properties
    automatically appear; when modifying the assertion, right-click
    Route via FTP(S) Server
    in the policy window and select
    FTP(S) Routing Properties
    or double-click the assertion in the policy window. The assertion properties are displayed. These properties are organized across the following tabs:
    Connection
    Authentication
    Advanced
  3. Configure each tab as necessary. Refer to the appropriate section below for a complete description of each tab.
    Tip:
    If you are unsure of the settings to use, consult with the FTP server administrator.
  4. Click [
    OK
    ] when done.
Configuring the [Connection] Tab
The [Connection] tab is used to configure the FTP connection.
  1. Configure the
    Connection Settings
    section as follows:
    Setting
    Description
    Protocol
    Choose the protocol to use:
    • FTP (unsecured):
      Information is submitted unencrypted.
    • FTPS with Explicit SSL (AUTH TLS/SSL):
      Information is encrypted using explicit SSL (RFC2228).  
    • FTPS with Implicit SSL:
      Information is encrypted using implicit SSL.
    Host name
    Enter the hostname of the FTP(S) server machine or a context variable that will contain the hostname. This name is verified against the X.509 certificate
    Port number
    Specify the port number or a context variable to use for the security method chosen. These defaults are used:
    • FTP (unsecured)
      and
      FTPS with Explicit SSL:
      port
      21
    • FTPS with Implicit SSL:
      port
      990
    Connect timeout
    Specify the connection timeout period. The default is 10 seconds.
    Verify server certificate
    If encryption is used, select this check box to verify the server's certificate against the trust store in the Gateway. For more information, see Managing Certificates
    Test Connection
    Click this button to test your FTP connection. This button is available only when all required information is entered in the properties dialog.
    The [
    Test Connection
    ] button cannot properly verify the connection if a context variable was used in the password, directory, or command.
  2. Configure the Command Settings section as follows:
    Setting
    Description
    Command
    Choose an FTP command to send to the FTP server, or choose
    From Variable
    to retrieve the command from the "Command Variable" field. For a list of the supported FTP commands, see Listen Port Properties.
    The FTP command handling setting in the associated FTP listen port may impact how the command is interpreted. For more information, see Listen Port Properties.
    Command Variable
    If the raw FTP command is being retrieved from a context variable, enter the variable here.
    Message Source
    From the drop-down list, select the source message of any data that is expected to accompany the selected command. Choose from
    Request
    ,
    Response
    , or any Message context variables that have been defined so far.
    Message Target
    Specify the target message where reply data from the FTP server should be stored, including the reply code, reply text, and any file or list data. Choose from
    Response
    or any Message context variables that will receive this information.
    Target Message Variable
    If the message target is a variable, enter the variable name. If this variable does not exist, it will be created.
    Directory
    Specify the remote directory on the FTP server to use or a context variable that will contain the directory name. You will be warned if the context variable specified does not exist at that particular point in the policy.
    Leave blank to use the default root directory defined by the FTP server.
    Arguments
    Enter any arguments or parameters required by the FTP command. For most common commands, the argument will be a file or directory name, but other commands may support other arguments.
    The Arguments field replaces both the "Auto-generate file name" and "Specify pattern" options found in the Route via FTP(S) assertion prior to version 8.2.0.
     
    Examples of arguments:
    • To ensure a unique file name for an upload request, you can use the context variable
      ${requestID}
      as the argument. This is the behavior of the "Auto-generate file name" option available in versions prior to 8.2.0.
    • To define a specific custom file name, enter the file name here. For example if you are using an upload-type command, entering
      myFile.txt
      will cause a file named "myFile.txt" to be created on the remote FTP server that contains the contents of the message body. This is the same as selecting the "Specify pattern" option prior to version 8.2.0.
      The arguments can be created dynamically by including context variables within the pattern. For example, the pattern
      "fromGateway-${requestId}"
      will name all the uploaded files
      "fromGateway-"
      followed by the request ID. You will be warned if the context variable specified does not exist at that particular point in the policy. 
    • To list the contents of a specific directory (other than the current working directory), enter the name of that directory as the argument. For example, the Directory field contains "/users/jsmith". To list the contents of the "downloads" directory (assuming "/users/jsmith/downloads"), enter "downloads" in the Argument field.
  3. Indicate how the assertion will respond to error reply codes from the target FTP server. Choose the appropriate
    Assertion Outcome
    from the drop-down list:
    • Fail on all Permanent Negative Completion reply codes (result: fail on all codes >=500)
    • Fail on Transient OR Permanent Negative Completion reply codes (result: fail on all codes >=400)
    • Never fail as long as target replies. This option allows FTP clients in a proxy scenario to receive useful responses that will, in most cases, reveal the reasons for failures (for example, insufficient privileges, incorrectly formatted arguments, etc.).
For more details on the FTP reply codes, see https://en.wikipedia.org/wiki/List_of_FTP_server_return_codes.
Configuring the [Authentication] Tab
The [Authentication] tab is used to configure authentication to the remote FTP server.
  1. Choose
    Pass through credentials in request
    to use the credentials contained in the request.Choose
    Specify user credentials
    to manually enter the credentials to use, and then enter the user name and password:
    • User name
    • Stored password:
      Use a password from the secure password store on the Gateway. Choose the password to use from the drop-down list. Note: Only stored passwords may be used here—you cannot type in a password (to do this, use the "Password expression" option instead). To define a stored password, click [
      Managed Stored Passwords
      ]. For more information, see Managing Stored Passwords.
    • Password expression:
      Use the password in the specified expression. You may specify context variables or embed context variables within the expression. Note: Entering a password expression is not recommended, as it is stored in plaintext form and is less secure. For maximum security, use the "Stored password" option instead.
    • Context variable in password
      : Select this check box to allow the assertion to correctly recognize context variables used in the Password expression field; for example, you will be using the
      ${secpass.*}
      context variables. For more information, see Stored Password Properties.
    For security purposes, the user name and password are automatically deleted when you close the properties and "Specify" is not selected. You do not need to manually clear these fields.
  2. Supply digital certificate for client authentication:
    Select this check box to use a client certificate from a private keystore for FTPS authentication, then choose the certificate from the dropdown list. This option is available only if a private keystore has been defined.
Configuring the [Advanced] Tab
The [Advanced] tab is used to configure additional properties for the FTP routing.
  • Override maximum message size:
    By default, the maximum response message size is 2GB. Select this check box to download messages larger than this limit or to impose a specific limit. You can also allow message of unlimited size, however this is not recommended as this may adversely affect Gateway performance.
  • Current WSS header handling:
    Specify how to handle the security header.
    Option
    Description
    Don't modify the request Security header
    Instructs the Gateway to leave the security header in the outgoing SOAP request message as-is. The security header in the request may still have been modified if the Gateway needed to decrypt any encrypted material during message processing.
    Use this setting if the protected service needs to do its own checking of the request's original security header, or if the protected service does not care whether its request messages have a security header.
    For best performance, use this setting whenever possible to minimize the amount of per-request message modification.
    Do not modify the Security header if the policy uses WS-Security. For more information, see the Add or Remove WS-Security Assertion.
    Remove Layer 7 actor and mustUnderstand attributes from processed Security header
    Instructs the Gateway to remove the 'mustUnderstand' attribute and 'Layer 7' actor from the security header in the outgoing SOAP message.
    Use this setting if the presence of the Layer 7 actor causes issues with the back-end service. In certain cases, this actor may cause the back-end service to ignore the Security headers because it believes it is addressed to someone else. You will also use this setting if the back-end service does not support Security and would reject a request with 'mustUnderstand' asserted on the Security header.
    An alternative might be to remove the Security header completely, however this will incur a performance penalty for the extra processing required to remove these from the messages. You may want to keep the Security headers intact for logging purposes.
    Remove processed Security header from request before routing
    Instructs the Gateway to remove any security header that was processed by the gateway before forwarding the request to the protected service.
    Use this setting when the protected service is not expecting security headers in the forwarded SOAP requests.