HTTP Transport

This document is all about HTTP sender and HTTP receiver, and how they work in Axis2.

Send your feedback or questions to: axis-dev@ws.apache.org. Prefix subject with [Axis2]. To subscribe to mailing list see here.

Content

CommonsHTTPTransportSender
- HTTPS support
Timeout Configuration
HTTP Version Configuration
Proxy Authentication
Basic,Digest and NTLM Authentication

CommonsHTTPTransportSender

This is the default transport sender that is used in Server API as well as Client API. As the name implies it is based on commons-httpclient-3.0.1. In order to acquire the maximum flexibility, this sender has implemented POST interface and GET interface. GET and HTTP interfaces are also involved in axis2 REST support.

Chunking and KeepAlive support is also integrated via the facilities provided by commons-httpclient along with HTTP 1.1 support.

<transportSender/> element is used to define transport senders in the axis2.xml as follows:

<transportSender name="http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender">
        <parameter name="PROTOCOL" locked="false">HTTP/1.1</parameter>
        <parameter name="Transfer-Encoding">chunked</parameter>
</transportSender>

Above code snippet shows a simplest configuration of the transport sender for common use. <parameter/> element introduces the additional parameters that should be compliant with the sender. HTTP PROTOCOL version sets as HTTP/1.0 or HTTP/1.1. Default version is HTTP/1.1. It should be noted that chunking support is available only for HTTP/1.1. Thus, even if the user turn on "chunking", if the HTTP version is 1.0, this setting will be ignored by the transport framework. KeepAlive property is default in version 1.1.

Some absolute properties are provided in runtime such as character encoding style (UTF-8, UTF-16 etc) etc, are provided via MessageContext.

HTTPS support

It should be noted that CommonsHTTPTransportSender can be used to communicate over https.

<transportSender name="https" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender">
        <parameter name="PROTOCOL" locked="false">HTTP/1.1</parameter>
        <parameter name="Transfer-Encoding">chunked</parameter>
</transportSender>

Please note that https works only when the server does not expect to authenticate the clients and where the server has the clients' public keys in its trust store.

Timeout Configuration

There are two timeout exists in transport level. They are called, Socket timeout and Connection timeout. This can be configured in deployment time or in run time. In deployment time, user has to add the following lines in axis2.xml.

For Socket timeout:

<parameter name="SO_TIMEOUT" locked="false">some_int_value</parameter>

For Connection timeout:

 <parameter name="CONNECTION_TIMEOUT" locked="false">some_int_value</parameter>

In runtime it's set as follows in the Stub.

...
Options options = new Options();
options.setProperty(HTTPConstants.SO_TIMEOUT,new Integer(timeOutInMilliSeconds));
options.setProperty(HTTPConstants.CONNECTION_TIMEOUT,new Integer(timeOutInMilliSeconds));

// or

options.setTimeOutInMilliSeconds(timeOutInMilliSeconds);
...

HTTP Version Configuration

The default HTTP version is 1.1. There are two methods in which user can change HTTP version to 1.0

By defining version in Axis2.xml as shown below.

 <parameter name="PROTOCOL" locked="false">HTTP/1.0</parameter>

Or user can change version at runtime by doing the following

...
options.setProperty(org.apache.axis2.context.MessageContextConstants.HTTP_PROTOCOL_VERSION,org.apache.axis2.transport.http.HTTPConstants.HEADER_PROTOCOL_10);
...

Proxy Authentication

Commons-http client has the inbuilt ability to support proxy authentication. Axis2 uses deployment time and runtime mechanisms to authenticate proxies. In deployment time, user has to change the Axis2.xml as follows. This authentication will be available in http and https.

<transportSender name="http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender">
        <parameter name="PROTOCOL" locked="false">HTTP/1.1</parameter>
        <parameter name="PROXY" proxy_host="proxy_host_name" proxy_port="proxy_host_port" locked="true>userName:domain:passWord</parameter>
</transportSender>

For a particular proxy, if authentication is not available fill "userName:domain:passWord"as "anonymous:anonymous:anonymous".

At runtime user can override the PROXY settings with an Object of HttpTransportProperties.ProxyProperties. On the stub initiate an object of prior and set it to the MessageContext's property bag via HttpConstants.PROXY. On the stub, it depicts as follows,

...
Options options = new Options();
....

HttpTransportProperties.ProxyProperties proxyProperties = new HttpTransportProperties.new ProxyProperties();
proxyProperties.setProxyHostName(....);
proxyProperties.setProxyPort(...);
...
options.setProperty(HttpConstants.PROXY, proxyProperties);
....

The above code would eventually override the deployment proxy configuration settings.

Basic,Digest and NTLM Authentication

HttpClient supports three different types of http authentication schemes: Basic, Digest and NTLM. Based on the challenge provided by server httpclient automatically selects the authentication scheme the request should be authenticated with. The most secure will be NTLM and least secure will be Basic.

NTLM is the most complex of the authentication protocols supported by HttpClient. It requires an instance of NTCredentials be available for the domain name of the server or the default credentials. Note that since NTLM does not use the notion of realms HttpClient uses the domain name of the server as the name of the realm. Also note that the username provided to the NTCredentials should not be prefixed with the domain - ie: "axis2" is correct whereas "DOMAIN\axis2" is not correct.

There are some significant differences in the way that NTLM works compared with basic and digest authentication. These differences are generally handled by HttpClient, however having an understanding of these differences can help avoid problems when using NTLM authentication.

NTLM authentication works almost exactly the same as any other form of authentication in terms of the HttpClient API. The only difference is that you need to supply 'NTCredentials' instead of 'UsernamePasswordCredentials' (NTCredentials actually extends UsernamePasswordCredentials so you can use NTCredentials right throughout your application if need be).
The realm for NTLM authentication is the domain name of the computer being connected to, this can be troublesome as servers often have multiple domain names that refer to them. Only the domain name that HttpClient connects to (as specified by the HostConfiguration) is used to look up the credentials. It is generally advised that while initially testing NTLM authentication, you pass the realm in as null which is used as the default.
NTLM authenticates a connection and not a request, so you need to authenticate every time a new connection is made and keeping the connection open during authentication is vital. Due to this, NTLM cannot be used to authenticate with both a proxy and the server, nor can NTLM be used with HTTP 1.0 connections or servers that do not support HTTP keep-alives.

Axis2 also allows to add a custom Authentication Scheme to httpclient.

The static inner bean Authenticator of HttpTransportProperties will hold the state of the server to be authenticated with. Once filled it has to be set to the Options's property bag with the key as HTTPConstants.AUTHENTICATE. Following code snippet shows the way of configuring the transport framework to use Basic Authentication

 ...
 Options options = new Options();
 
 HttpTransportProperties.Authenticator
                       auth = new HttpTransportProperties.Authenticator();
            auth.setUsername("username");
            auth.setPassword("password");
            // set if realm or domain is know

 options.setProperty(org.apache.axis2.transport.http.HTTPConstants.BASIC_AUTHENTICATE,auth);
 ...