How to Configure a Proxy for Ivy SOAP and REST Clients
We recently had several support questions related to using Ivy web clients to consume web services located behind a proxy. Because Ivy uses two different technology stacks for SOAP and REST clients, configuring the use of a proxy is - as is to be expected - different for each stack.
We will explain how to set this up for the two technologies in this blog post, but first, let's look at the basics:
How Does a Proxy Work?
Think of a proxy as a remote controlled web service client: It performs all actions that a web service client would do - the controlling web service client forwards the unchanged requests to the proxy, instead of executing them itself.
A direct access from a web service client to its server involves these interactions:
When using a proxy, the interaction changes as follows:
Internal and External Services
You may have services that are provided inside your private network, and others which are available "in the web", i.e. in the public internet.
Internal services are usually accessed without using the proxy, while external services require the use of a proxy if your IT has set up such a proxy - a Corporate Proxy.
To allow the web service client to determine whether a service is internal or not, a non-proxy-host-list is provided. Internal services are on the list, external services are not.
A missing non-proxy-host-list is interpreted as an empty non-proxy-host-list and will force even local requests to be executed via the proxy.
How to Specify Proxy Information
To direct a web service client to use a proxy, you need to define the following items:
The proxy parameters:
The non-proxy-host-list (optional) - a "|" separated list of hostnames that are considered internal.
Calling Web Services via a Proxy
As stated above, we use different technology stacks to call SOAP web services (Apache CXF) and REST web services (Eclipse Jersey). These two libraries use different properties to define proxy parameters.
Calling SOAP Web Services via Proxy
This uses either CXF (Ivy > 7.1) or Axis (Ivy <= 7.0). For CXF, you need to define the following properties for your Web Service Client:
- proxy.host
- proxy.port
- proxy.nonProxyHost
- proxy.auth.scheme
- proxy.auth.username
- proxy.auth.password
You do this by adding the necessary properties to the web service client:
Calling REST Web Services via a Proxy
This uses the JAX-RS reference implementation Jersey 2.
For Jersey, you need to define the following properties in the Client Definition:
- jersey.config.client.proxy.uri ("https://proxy.domain.tld:port")
- jersey.config.client.proxy.username
- jersey.config.client.proxy.password
You do this by adding the necessary properties to the web service client:
Restrictions
Non-Proxy-Hosts-List
There is no non-proxy-hosts-list for our REST Client. If you specify a proxy, the client will always call via proxy.
If you do not specify a non-proxy-hosts-list for a SOAP Client, then all requests will be sent via proxy.
proxy.pac
Often, proxy.pac files are evaluated by browsers to find how a certain service has to be called.
We do not support proxy.pac; you need to "hard code" how your SOAP and REST Clients shall access their services.
Proxy Authentication
We do only support HTTP Basic Authentication and HTTP Digest Authentication for the proxy for SOAP Clients.
We do only support HTTP Basic Authentication for the proxy for REST Clients.
We do not support NTLM authentication for the proxy.
Note: In this situation, we have seen successful use of the following solution:
There is a local proxy available that you can install on your engine in order for it to proxy your requests to the Corporate Proxy: You specify this piece of software as your Web Service Client proxy.
You set it up with the required NTLM Corporate Proxy credentials.
Once set up, your request will go to this local proxy, and is then forwarded to the Corporate Proxy using NTLM authentication.
The Corporate Proxy sends its response back to the local proxy.
The local proxy forwards it to your client.
One such utility is CNTLM: https://sourceforge.net/projects/cntlm/.
