This topic explains how to configure message proxies that send and receive messages over HTTP (including HTTPS). 

Version Compatibility

HTTP traffic files recorded in Virtualize or SOAtest 9.10.x and later cannot be used with 9.9.x verions and earlier.

In this section: 

You will need the host, port, and path of the service you are targeting in order to set up basic HTTP connection options. Use the settings you would normally use to directly message the service. 

Connection Settings

To specify basic HTTP Reverse proxy connection options, set the following service and listening details in the Proxy Settings Connection tab.

Proxy Settings (incoming) 

These settings specify where messages from the client should connect in order to communicate with the application under test:

Reverse Proxy: You can choose a Reverse Proxy HTTP Listener that you defined when creating the proxy (see Creating Proxies) from the menu or use the default listener.

You can also add Reverse Proxy HTTP Listeners from this dialog:

  1. Click New and specify a name for the listener.
  2. Click Add Port and enter a port number. You can enable the message proxy to automatically assign a port by specifying 0 as the port number. When the proxy is enabled, the assigned port number will appear in the console. The port is randomly assigned every time the message proxy is changed/enabled. You can also send a GET request to the messageProxies API endpoint to return the automatically assigned port number. See Testing through the REST API for additional information.  
  3. If the client sends traffic over SSL, enable the Secure option and enable your verification options. See SSL Settings for Reverse Proxy Listener Ports for details.
  4. Click OK to exit the port editor.
  5. Click Add to add additional ports to the proxy or OK again to finish adding the proxy.

Proxy listen path: Enter the path where the proxy should listen for incoming connections. To listen to all paths, select [All] from the menu.

No two message proxies can have HTTP proxy connections with the same proxy path or with a path that matches an existing virtual asset’s HTTP path.

See Service Forward Path and Proxy Listen Path for more details.

Proxy URL: Displays the URL that should be given to the AUT. See Directing AUTs to Proxies for additional information.

Service Connection (outgoing)

Specify the URL or path to a Virtual Asset or Message Proxy for the target application for both the primary and secondary connections. Primary and Secondary are set up the same way:

  • To specify the URL for the target application: choose Custom from the menu and enter the full URL, comprising of the service host, service port, and (optionally) forward path in the URL field. See the notes below regarding each of these components of the service URL. Note that query parameters will be ignored if specified in the URL field.
    • Service host: If you want the proxy to forward to a virtual asset on the local server without consuming an HTTP connection, enter host.virt.internal, localhost, or 127.0.0.1 as the service host rather than the actual hostname. When using localhost or 127.0.0.1, the service port must match the port Virtualize is deployed on; when using host.virt.internal the service port is not used. For example, a virtual asset deployed on http://localhost:9080/myVirtualAsset can also be reached using http://host.virt.internal/myVirtualAsset.
    • Service port: This is the port to which the proxy will send messages.
    • Forward path: If no forward path is specified, the Proxy listen path is used. If the HTTP proxy is sending messages to localhost, you must specify a forward path because the proxy doesn't allow forwarding to itself. If the forward path sends a redirect, the proxy will follow the redirect and then respond back. It will not pass the redirect back to the client. See Service Forward Path and Proxy Listen Path for more details.
  • To specify the path to a Virtual Asset or Message Proxy for the target application: choose Virtualize from the menu and enter the path to the Virtual Asset or Message Proxy in the Path field.

Options

Mode: Allows you to set the active forwarding connection when a primary and secondary connection exist. For example, during a recording session, a message proxy may forward to the live service as the primary connection and fall back to a virtual service as a secondary connection. In this case, you can set the HTTP mode to Primary and enable Use other connection if selected mode fails.

Once recording is complete and new virtual assets are generated, you may want to re-configure the proxy to forward to the virtual service first and fall back to the live service if a failure occurs. This change can be quickly applied by right-clicking the proxy and switching the HTTP mode to "secondary". The failover will be adjusted accordingly at runtime.

Use other connection if selected mode fails: Enable this option if you want traffic to be redirected to the backup proxy endpoint when the active connection (as determined by the Mode selected above) fails. The connection will be considered "failed" if the response status code is 400 level or higher.

Bypassing proxy failover

Message Responders can be configured to bypass this proxy failover for internally routed messages by enabling the Skip message proxy failover option.

If this option is not enabled, the active connection will be used for recording.

If this option is enabled, select a recording option from the Record menu:

  • Both connections: Records traffic for both the primary and secondary connections. Error messages from the active connection will not be recorded; instead, the messages will be sent to the backup connection and the responses will be recorded. Errors reported by the backup will be recorded.
  • Primary connection only: Records traffic for the active connection. Does not record errors.
  • Secondary connection only: Records traffic for the backup connection, including errors.

Valid HTTP response code ranges: Allows you to customize the message proxy's failover behavior so that it succeeds with HTTP response codes outside the 2xx range. Specify single codes and/or code ranges as a comma-separated list. For example, if you use "404, 500-599", a 404 code or any code in the 5xx range will be accepted. 

Learn responses: Enable this option if you want your internal endpoint to learn to emulate the responses recorded from a live endpoint. The internal endpoint must have a files responder (see Request/Response Files for more information). This option is only available when Use other connection if selected mode fails is enabled (see above). You can easily enable/disable learning by the proxy by right-clicking the proxy and switching the mode to Enable All or Disable All.

Security Tab Settings

The Service SSL section needs to be completed only if the service you are working with uses SSL.

If the service being virtualized and/or the application under test uses SSL and/or other authentication (basic/digest, Kerberos, NTLM), additional configuration may be required.For details on completing the Service SSL fields immediately below these fields, see Security Configuration.

Proxy Server Tab Settings

You can specify a server for the message proxy in this tab, which enables you to configure a different proxy server for traffic to and from different message proxies. This configuration provides control over which proxy server handles traffic between the application under test and a specific message proxy. 

To specify proxy settings at this level, provide the appropriate details in the proxy’s Proxy Server tab. 

SSL is not supported. 

Service Forward Path and Proxy Listen Path

In the simplest case, you can set Proxy listen path to the path of your service and leave Service forward path empty. With this configuration, the proxy will automatically forward all messages it receives on that path to the same path at the Service host and Service port

If you need the proxy to listen on a different path than the path of your service, set Service forward path to the actual path where you want received messages to be sent. The proxy will forward the path and any query parts to the target service. 

If the Proxy listen path and the Service forward path are different, then any segments in the request after the Proxy listen path will be appended to the forwarded request. The Proxy listen path is essentially being replaced with the Service forward path so that the entire path (as received by the proxy) gets sent to the service.

Using Wildcard Characters in Paths

You can use wildcard characters to specify dynamic path segments. For example, configuring the path as /path/*/service would enable the following paths to go to the same proxy: 

/path/1/service 

/path/2/service 

Wildcards can be used to replace an entire path segment. For example:

  • /path/*/service — valid
  • /path/1*2/service — not valid

The wildcard can only be used for one segment of the path. A path configured as /path/*/service will NOT match /path/1/2/service. If you want your path to match both /path/1/2/service and /path/3/4/service, use the pattern /path/*/*/service.

You can use the dynamic segment from the listen path as part of the forward path. There are two ways to do this:

  • If you want traffic to be forwarded to the path where the request was received, leave the forward path empty.
  • If the forward path is different and the dynamic value needs to be used, configure it using environment variable syntax. For example:
    listen path: /path/*/service
    forward path: /asset/path/${1}/service

The dynamic listen path segments represented by the wildcards can be accessed using environment variable syntax. The occurrence of the wildcard is used as the variable name; in other words, the first occurrence of the wildcard is ${1}, the second is ${2}, the third is ${3}, etc.  In the following example, ${2} refers to the second occurrence of the wildcard (which was "bank" in the request path):

listen path: /path/*/service/*/account
forward path: /asset/path/${2}/service/${1}/account

request path: /path/1/service/bank/account
forward path: /asset/path/bank/service/1/account

Header Alterations

In most cases, the proxy will pass all headers directly to and from the target service. Some content-length related headers may be changed to suit how the proxy server works. For example, the proxy server doesn't support responding with the "chunked" transfer encoding and will replace "host" headers sent to match its own host name (however, it does support receiving chunked requests and chunked responses from the target service).

Setting the Target Service

A proxy can use a virtual or test asset on a server as its target service. 

  1. Set the service host and port to that of the Virtualize Server where the virtual asset is deployed. If you want the proxy to forward to a virtual asset on the local server without consuming an HTTP connection, enter, host.virt.internallocalhost, or 127.0.0.1 rather than the actual hostname. When using localhost or 127.0.0.1, the service port must match the port Virtualize is deployed on; when using host.virt.internal, the service port is not used.
  2. Set the proxy connection’s Service forward path to the virtual asset’s path (found in the virtual asset’s Transports > HTTP tab, under HTTP endpoint).

Chunking/Unchunking Behavior

The proxy supports receiving chunked requests and chunked responses from the target service. If a service response uses HTTP chunking, proxies will unchunk responses before they are returned to the original caller/AUT.

Additional HTTP Message Proxy Configuration

You can create a properties file to configure additional Reverse Proxy HTTP Listener settings. The properties file allows you to fine-tune Reverse Proxy HTTP Listener performance and specify additional SSL settings.

  1. Create a plain text file and specify the properties you want to set (see Reverse Proxy HTTP Listener Message Proxy Performance Properties and Reverse Proxy HTTP Listener Message Proxy SSL Properties). 
  2. Save the file to the VirtualAssets or TestAssets directory in your workspace and name it "embeddedServer.properties".

The file will be read every time a proxy with a Reverse Proxy HTTP Listener is enabled.

Reverse Proxy HTTP Listener Properties

embedded.connector.maxHttpHeaderSizeSpecify the maximum size of the request and response HTTP header (bytes). If not specified, this attribute is set to 8192 (8 KB).
embedded.connector.parseBodyMethods

Specify HTTP methods to use when parsing application/x-www-form-urlencoded request bodies for request parameters identically to POST, especially when you want to support POST-style semantics for PUT requests. Comma separate entries. TRACE is forbidden. The default is POST.

embedded.connector.relaxedPathChars

Specify characters that should be allowed in URI paths in unencoded form. The value may be any combination of the following characters:

" < > [ \ ] ^ ` { | }

Any other characters present in the value will be ignored. If this property is not included, Tomcat will reject unencoded forms of the above characters in URI paths.

Refer to the Tomcat documentation for additional information: https://tomcat.apache.org/tomcat-8.5-doc/config/http.html.

embedded.connector.relaxedQueryChars

Specify characters that should be allowed in URI queries in unencoded form. The value may be any combination of the following characters:

" < > [ \ ] ^ ` { | }

Any other characters present in the value will be ignored. If this property is not included, Tomcat will reject unencoded forms of the above characters in URI queries.

Refer to the Tomcat documentation for additional information: https://tomcat.apache.org/tomcat-8.5-doc/config/http.html.

Reverse Proxy HTTP Listener Message Proxy Performance Properties

All properties are optional and non-integer values will be ignored.

embedded.connector.maxThreads

Specify the maximum number of request-processing threads the connector should create. This property determines the maximum number of simultaneous requests that can be handled. Default is 200.

embedded.connector.minThreads

Specify the minimum number of threads that should always be running. Default is 10.

embedded.connector.acceptors

Specify the number of threads that should be used to accept connections. Increase this value on machines with multiple CPUs or when you are using several non-keep-alive connections. 1 or 2 is adequate in most cases. Default is 1.

embedded.connector.idleTimeoutSpecify how many milliseconds the connector should wait for another HTTP request before closing the connection. Specify -1 to allow the connector to wait indefinitely. Default is use connectTimeout.
embedded.connector.soLingerTime

Specify how many milliseconds the sockets used by the connector should linger when the sockets are closed. Lingering is disabled by default.

embedded.connector.acceptorPriorityDeltaSpecify the priority of the acceptor threads used to accept new connections. See the java.lang.Thread JavaDoc for additional details. Default is 5.
embedded.connector.acceptQueueSize

Specify the maximum queue length for incoming connection requests when all possible request processing threads are in use. Any requests received when the queue is at capacity will be refused. Default is 100.

embedded.connector.connectTimeoutSpecify how many milliseconds the connector should wait for the request URI line to be presented after accepting a connection. Enter -1 to allow the connector to wait indefinitely. Default is 60000.

Reverse Proxy HTTP Listener Message Proxy SSL Properties

embedded.ssl.includeProtocols

Comma-separated list of SSL protocols to support for HTTPS connections. If specified, only the protocols in the list will be supported by the SSL implementation in the JVM. If this property is not set, the protocols supported by the JVM are used (excluding SSLv2 and SSLv3 if the JVM enables either or both of them by default).

embedded.ssl.includeCipherSuites

Comma-separated list of encryption ciphers to support for HTTPS connections. Use the JSSE cipher naming convention to specify the ciphers. If the property is set, only the ciphers in the list will be supported by the SSL implementation. If this property is not set, the JVM's default cipher suites, except for suites that are not considered secure, will be supported. As a result, a very limited set of ciphers will be available by default for older JVMs.

embedded.ssl.useCipherSuitesOrder

Set to true to enforce the server's cipher order (from the ciphers setting). Set to false to choose the first acceptable cipher suite presented by the client. This feature requires Java 8 or later. Default is undefined, which will result in the order being defined by the JSSE implementation.

embedded.ssl.maxCertPathLength

The maximum number of intermediate certificates that will be allowed when validating client certificates. Default is 5.

embedded.ssl.crlPathSets the path to the file containing the certificate revocation list used for verifying client certificates. If not defined, client certificates will not be checked against a certificate revocation list.
embedded.ssl.keyManagerAlgorithmSets the certificate encoding algorithm to be used. By default, KeyManagerFactory.getDefaultAlgorithm() is used, which returns SunX509 for Sun JVMs. IBM JVMs return IbmX509.
embedded.ssl.truststoreAlgorithmSets the algorithm used for truststore. If not specified, the default value returned by javax.net.ssl.TrustManagerFactory.getDefaultAlgorithm() is used.
embedded.ssl.useKeyManagerAlgorithmForTruststoreIf set to true, the key manager algorithm is used as the truststore algorithm. This takes precedent over the embedded.ssl.truststoreAlgorithm property. Default is False.

Example: Sending Traffic to a Service

Assume that we want to create a message for a service that is normally accessed at http://example.parasoft.com:9080/BookStore. We could create an HTTP Reverse proxy with the settings: 

  • Proxy listen path: /BookStore
  • Service host: example.parasoft.com
  • Service port: 9080
  • Service forward path: [empty]

This configuration will listen on /BookStore and forward all traffic to the actual bookstore service.

If we wanted to listen on a path other than the service path, we would change the configuration of the proxy as follows:

  • Service forward path: /BookStore
  • Proxy listen path: /SomeOtherPath

This would route traffic from /SomeOtherPath on the proxy to the actual bookstore service. 

In both cases, all traffic that goes to those paths (including sub paths) is sent to the service. In the second example, traffic sent to /SomeOtherPath/SubPath would be sent to /BookStore/SubPath. Because queries are preserved, /SomeOtherPath?param=value would be sent to /BookStore?param=value.

Forwarding Requests to Services that Require Case-sensitive Header Names

If you are using the desktop's server, your message proxy headers will be lowercased and may fail to function properly when requests are forwarded to a service that requires case-sensitive HTTP header names.

You can create a _global.headers file in the /VirtualAssets/ directory and add the headers using the specific capitalization you want to pass. Right-click the server in the UI and re-deploy all virtual assets to begin using this file in your environment.

You can also address HTTP header capitalization issues for specific message proxies. Create a <PROXY-NAME>.headers file in the /VirtualAssets/ directory and add the headers using the specific capitalization you want to pass for the specific proxy. This file will apply to specific proxy and override the global file. Right-click the server in the UI and re-deploy all virtual assets to begin using this file in your environment.

Example Headers File

X-AUTHORIZATION
ANOTHER-HEADER
HEADER3

Example: Sending Traffic to a Virtual Asset

A proxy can also send traffic to a virtual asset. In that case, enter the host and port information for the Virtualize Server as if were just another service.

For example, to send traffic to a virtual asset on a remote server, you might use: 

  • Proxy listen path: /proxyPath
  • Service host: server.parasoft.com
  • Service port: 9080
  • Service forward path: /assetPath

To send traffic to a virtual asset on a local server using an HTTP Listener, you might use:

  • Reverse Proxy: 7070
  • Service host: [Virtualize]

To send traffic to a virtual asset on a local server without an HTTP Listener, you might use:

  • Proxy listen path: /proxyPath
  • Service host: [Virtualize]
  • Service forward path: /assetPath

The HTTP Reverse proxy makes no distinction between a virtual asset and an actual service. Both are configured the same way. However, if the Default HTTP Reverse proxy (without an HTTP Listener) is sending to [Virtualize] or localhost, you must specify Service forward path because the proxy doesn't allow forwarding to itself.

Forwarding Requests to Services that Require Case-sensitive Header Names

If you are using the Virtualize desktop's server, your message proxy headers will be lowercased and may fail to function properly when requests are forwarded to a service that requires case-sensitive HTTP header names. See Forwarding Requests to Services that Require Case-sensitive Header Names for details.


Security Configuration

There are two aspects of configuration for security: 

  • If the service to which you are forwarding the traffic uses SSL and/or access authentication, you need to perform proxy-level configuration (from the proxy’s UI controls).
  • If the AUT uses SSL and/or access authentication, you need to perform server-level Configuration (for the Tomcat-based server).

Depending on your configuration, you configure either security setting or both.

Proxy-level Configuration

Proxy-level security configuration, which is relevant if the service to which you are forwarding the traffic uses SSL and/or access authentication, covers:

SSL

For SSL, additional settings are required. In the lower part of the configuration panel, you need to specify whether to:

  • Enable trust for self-signed certificates.
  • Enable trust for all certificates.
  • Set a trust store to validate server certificates.

Additionally, you need to provide the information needed to use a specific key store and certificate so Parasoft can determine which certificate to present to a server (for example, for 2-way SSL).

SSL Configuration Panel Fields

OptionDescription
Use SSL when connecting to the serviceEnables the SSL.
Trust all server certificates

If enabled, any certificate will be accepted. No validation will be performed.

This option disables trust validation when the message proxy establishes the connection with the service; it makes it accept the connection with any certificate that is presented by the service.In general, this option should be enabled if certificate trust is not a focus for the environment where SOAtest or Virtualize is deployed.

Accept self-signed certificates

If enabled, certificates will be accepted as long as the validation method java.security.cert.X509Certificate.checkValidity() returns true on them, which effectively checks if the current date and time are within the validity period given in the certificate. The certificate trust path will not be evaluated and the provided Trust-store configuration will not be applied.

This option determines if certificates presented by the service and are not signed by a trusted certificate authority are trusted.In general, this option should be enabled if certificate trust is not a focus for the environment where SOAtest or Virtualize is deployed.

Note that the Truststore configuration (described below) is applicable only if Trust all server certificates and Accept self-signed certificates are both disabled.

Keystore Configuration Panel Fields

OptionDescription
Key store fileSpecifies the path to the key store file. The keystore determines the certificates and keys that are presented by the message proxy to the service during the SSL handshake.
Key store passwordSpecifies the password to access the key store.
Key store typeSpecifies the type of the key store.
CertificateSpecifies the alias of the certificate to use when authenticating to a server.

After completing the keystore detail, click the Load and choose the certificate alias to present to the server from the Certificate menu. If the Certificate menu is not populated when you click Load, you may have entered the incorrect password or keystore type.

 

Truststore Configuration Panel Fields

These fields are applicable only if Trust all and Accept self-signed certificates (described above) are both disabled.

OptionDescription
Key store file

Specifies the path to the truststore file. The truststore determines the certificates that the message proxy should trust when handshaking with the service. If the service presents a certificate that is not included in this store, the connection will be refused. If no truststore is provided, the default JRE truststore will be used. 

This option is only applicable if Trust all server certificates is disabled.

Key store passwordSpecifies the password to access the truststore.
Key store typeSpecifies the type of the truststore.


NTLM Settings Panel Fields

OptionDescription
Use NTLMSpecifies whether the service requires NTLM authentication.
UsernameSpecifies the username for NTLM authentication.
PasswordSpecifies the password for NTLM authentication.


Kerberos Panel Fields

OptionDescription
Kerberos service principalSpecifies the service principal to authenticate the request.

Basic/Digest Authentication

If the application under test provides Basic and Digest authentication credentials as part of the request and transmits them as part of the HTTP header, the proxy will pass them along to the service unmodified (the same way it handles other HTTP headers). 

NTLM Authentication

If your service requires NTLM authentication, provide the username/password in the NTLM section.

Kerberos Authentication

If your service requires Kerberos authentication, set the Kerberos Service Principal in the Kerberos Authentication section.

Server-level Configuration

Server-level security configuration, which is relevant if the AUT uses SSL and/or access authentication, can involve:

Configuring the SOAtest and Virtualize Server

You can change the default port number (9080), enable SSL, and configure other server settings. See Server Configuration for details. 

Using NTLM with WAFFLE

To use the third-party library WAFFLE for NTLM:

  1. Copy the following jar files into tomcat's lib directory: jna.jar, platform.jar, wafflejna.jar.
  2. Add the following to the server.xml file in the tomcat/conf/ directory.

    <Context>
      <Valve className="waffle.apache.NegotiateAuthenticator" principalFormat="fqn" roleFormat="both"/> 
      <Realm className="waffle.apache.WindowsRealm" /> </Context> 

    Where is server.xml?

    If you installed SOAtest but not Virtualize: Launch SOAtest, ensure that at least one responder has been created, then modify the server.xml file at <INSTALL-DIR>/plugins/com.parasoft.ptest.libs.web_<VERSION>/root/tomcat/conf/.

    If you installed Virtualize but not SOAtest: Launch Virtualize, ensure that at least one responder has been created, then modify the server.xml file at <INSTALL-DIR>/plugins/com.parasoft.ptest.libs.web_<VERSION>/root/tomcat/conf/.

    If you installed Virtualize and SOAtest together: Launch Virtualize, ensure that at least one responder has been created, then modify the server.xml file at <INSTALL-DIR>/plugins/com.parasoft.ptest.libs.web_<VERSION>/root/tomcat/conf/.

  3. Add the following to the web.xml file in the tomcat/conf/ directory.

    <security-role> 
      <role-name>Everyone</role-name> 
    </security-role> 
    <security-constraint> 
      <display-name>Waffle Security Constraint</display-name> 
      <web-resource-collection> 
        <web-resource-name>Protected Area</web-resource-name> 
        <url-pattern>/*</url-pattern> 
      </web-resource-collection> 
      <auth-constraint> 
        <role-name>Everyone</role-name> 
      </auth-constraint> 
    </security-constraint> 
  4. Restart the server.

For more details, see the Single Sign-On: Tomcat Negotiate Authenticator (Kerberos + NTLM) w/ Waffle Tutorial and the WAFFLE home page.

Using Unsupported Configurations (Kerberos with WAFFLE, JAAS)

WAFFLE includes support for Kerberos authentication; see the WAFFLE home page for directions and support. 

JAAS is another option for configuring the Tomcat-based Virtualize Server to perform Kerberos authentication. Consult Tomcat for directions on how to use JAAS.

  • No labels