Extensions for HTTP Authentication in Apache Axis2/C

Authentication is the mechanism for identifying one's self. in the context of the Internet, authentication serves as the primary means for filtering access to protected resources. HTTP, the Hypertext Transfer Protocol, is an accepted standard for exchanging hypermedia in a distributed and collaborative environment. HTTP 1.1, [1] is the latest version of the protocol, in popular consumption.

Authentication on HTTP 1.1 is a framework supporting two popular mechanisms for requesting and providing credentials in non-secure environments [2]. One, being the simple passing of username and password as encoded text, known as Basic Access Authentication and the other based on cryptographic hashes, known as Digest Access Authentication.

This article by Senaka L. Fernando serves as a guide to using  Extensions for HTTP Authentication in Axis2/C.

Introduction

Axis2/C clients are able to consume a large share of WS-* enabled services, together with provision for supporting RESTful invocations. When dealing with HTTP servers and proxies in a real world production environment, authentication is a key requirement in restricting access to protected resources. HTTP Basic Authentication was supported since version 1.1.0 of Axis2/C that was released on 24th September 2007. Just only five months later, with version 1.3.0 released, Axis2/C now supports the complete HTTP authentication specification for both HTTP server and HTTP proxy. One of the main reasons why HTTP authentication has become an important feature of the Axis2/C client API, is the growing popularity of RESTful services demanding security in the absence of WS-*.

The inclusion of Client Side Extensions for HTTP Authentication will also extend a client's ability to consume services, giving them the opportunity to access servers and pass proxies to retrieve protected resources.

Axis2/C server side is reasonably premature in terms of HTTP authentication support. You can read more on server side and service level support towards the end of this article.

Applies To

Contents

1. Integration to Axis2/C Configuration
2. Client API Extensions
3. Using the Client API
4. Resolving Ambiguities
5. Pre-Determining Authentication Requirements
6. Using the Authentication Sample
7. Server Side and Service Level Support
8. Future
9. Summary

Integration to Axis2/C Configuration

Axis2/C includes the ability to specify configuration information while setting up the engine, on both the client and the server sides. This information is specified in a special file known as axis2.xml, [3]. Reading through the axis2.xml file, you would notice that it contains a section called Transport Outs. Axis2/C supports several Transport Out protocols including HTTP, HTTPS and TCP. Since HTTP authentication is an HTTP specific implementation, it would be meaningful only if you add authentication information to the HTTP and HTTPS protocols. Thus, to setup authentication, you would simply need to insert an additional parameter to the HTTP or HTTPS Transport Sender based on the type of channel you are using.

To setup HTTP authentication for servers (Basic or Digest), simply add the parameter, HTTP-Authentication, as given below:

<transportSender name="http" class="axis2_http_sender">
    <parameter name="PROTOCOL" locked="false">HTTP/1.1</parameter>
    <parameter name="HTTP-Authentication" username="[uname]" password="[passwd]" locked="true"/>
</transportSender>

Replace [uname] with your desired username and [passwd] with the desired password. As of now, the locked attribute is not used internally, and therefore makes no difference whether specified as "true" or "false". Here, I have taken the HTTP Transport Sender as an example:

Proxy support is added in two flavors. The first being you connect to a proxy directly providing authentication information, and the second, indirect connection to a proxy providing authentication information. In the first case, you will have to add a PROXY parameter, as:

<transportSender name="https" class="axis2_http_sender">
    <parameter name="PROTOCOL" locked="false">HTTP/1.1</parameter>
    <parameter name="PROXY" proxy_host="[host]" proxy_port="[port]" proxy_username="[uname]" 
        proxy_password="[passwd]" locked="true"/>
</transportSender>

You will have to specify the proxy host and port, by replacing [host] and [port] respectively. And, the credentials to be used in order authenticate yourself will have to be added by replacing [uname], and [passwd].

The second scenario is useful when you connect to a server or a proxy, that would connect to another down stream proxy that requires authentication in favor of granting access. In this kind of a situation you would not rather be aware of the host and port of the proxy in concern, and most importantly you will not have a direct route to that node. Under these circumstances, you may add authentication information as follows.

<transportSender name="https" class="axis2_http_sender">
    <parameter name="PROTOCOL" locked="false">HTTP/1.1</parameter>
    <parameter name="PROXY" proxy_username="[uname]" proxy_password="[passwd]" locked="true"/>
</transportSender>

In here, you will have to replace [uname] and [passwd] appropriately, with your credentials.

The distinction of HTTP authentication for servers and HTTP authentication for proxies, mainly in terms of policy, requires two separate authentication schemes which is the reason to why you have to specify authentication information in two locations rather than one. It is also an added plus, giving you the ability to maintain two sets of credentials.

It is important to note that axis2.xml will not be encrypted by any means, during any operational stage of the Axis2/C engine. As a result, your username, and most importantly the password will be clearly visible to any party who has access to your axis2.xml file. Thus, make sure to take all necessary precautions to ensure the protection of your privacy.

Client API Extensions

The client API extensions are provided as a secure alternative to specifying authentication information in the axis2.xml file. It also serves as an entry point from source code, for specifying credentials required for HTTP authentication. The mechanism of providing your username and password is the setting of an option for the Service Client, which is achieved using an Axis2 Options object. In addition to providing your username and password, you also have the option to provide your preferred authentication scheme, as either "Basic" or "Digest". By providing your preferred authentication scheme you will basically force the Axis2/C engine to use your desired scheme.

It is important to know that, when using HTTP authentication for proxies, you can't select "Digest" as your preferred authentication scheme if you use any other type of request other than HTTP Head requests, [4].

If you chose "Basic", the transport sender will add an Authorization header for HTTP authentication for servers, and a Proxy-Authorization header for HTTP authentication for proxies - for each outgoing request. If your choice was Digest, your authentication details will be appended to the outgoing request only once requested by the target server or proxy. In a Digest operation, The first request made will be an HTTP Head request, [4] which will contain no payload in both outgoing request and incoming response. Then the authentication information would be added to the next request sent. If this second request fails with an 403 Unauthorized status code, the transport sender will retry sending it based on the authentication information requested on the second response that failed.

If you did not provide your preferred authentication scheme (in which case you set it as NULL), the engine will decide on the required authentication scheme based on the first response that failed.

This above mentioned behavior can be summarized in a workflow as shown below.

Using the Client API

Setting up HTTP authentication information for servers requires you to make use of the following method,

axis2_options_set_http_auth_info(options, env, [uname], [passwd], [mode]);

You will have to replace [uname] and [passwd] with your desired username and password, whilst [mode] is one of "Basic" , "Digest" or NULL, which is explained in the section above (see Client API Extensions). Similarly to setup HTTP authentication information for proxies you will have to call,

axis2_options_set_proxy_auth_info(options, env, [uname], [passwd], [mode]);

The above mentioned method caters for both types of proxies (direct and indirect) discussed above (see Intergration to Axis2/C Configuration). However, if you are setting up a connection to a proxy to which you are directly connected, you have the liberty of using another method for this purpose.

axis2_svc_client_set_proxy_with_auth(service_client, env, [host], [port], [uname], [passwd]);

You will have to provide host, port, username and password when attaching a connection to a proxy in your Service Client. In here, however, you can't specify your preferred method of authentication.

Resolving Ambiguities

Having mentioned the various possibilities of specifying authentication information, you might wonder on which specification will be preferred to the other. When it comes to HTTP authentication for servers, credentials specified in code have higher priority to that of what is specified in the axis2.xml file. And, when it comes to HTTP authentication for proxies, credentials specified as an option of the Service Client has the highest priority. Next to it is the axis2_svc_client_set_proxy_with_auth method. The credentials specified in the axis2.xml has the least priority. The specification with the highest priority will be chosen if it exists, and so on and so forth.

This mechanism of resolving ambiguities was chosen, having in mind the most generic as well as the most specific way of providing authentication information per outgoing request made by the Axis2/C engine.

Pre-Determining Authentication Requirements

In a non-secure environment such as a TCP/IP network through a non SSL connection, exposing authentication information might introduce a potential security threat. This mainly affects the insecure HTTP Basic Authentication scheme. Another requirement would be to identify which type of authentication is required so that a intermediary cannot request HTTP Basic Authentication where a user would rather be interested in a HTTP Digest Authentication mechanism, and vice versa.

Pre-determining whether authentication is required will require testing. You can set an option on the Service Client instructing it to test either HTTP authentication for server or proxy using the methods below.

axis2_options_set_test_http_auth(options, env, AXIS2_TRUE);
axis2_options_set_test_proxy_auth(options, env, AXIS2_TRUE);

To disable the test-mode, simply call the method once again using AXIS2_FALSE instead of AXIS2_TRUE. Once enabled, the Service Client will continue to operate in test-mode unless you explicitly disable it. Under the test-mode, no authentication information will be sent with outgoing messages. Thus, it has even higher priority than the above mentioned methods (see Resolving Ambiguities). However, the test-mode would pass messages that do not require authentication without failure, and a successful communication can be achieved.

The next step will be to identify whether authentication was actually required. You can use the Service Client to determine whether authentication was required for any outgoing message, once that message has been sent. Therefore, from the next message onwards you can provide necessary authentication information. Thus, if an authentication failure occurred or if authentication was required and the Service Client was operating in the test-mode, the methods shown below would return "AXIS2_TRUE". Therefore, they can be used to determine HTTP authentication for server, or HTTP authentication for proxy requirements.

axis2_svc_client_get_http_auth_required(svc_client, env);
axis2_svc_client_get_proxy_auth_required(svc_client, env);

Once this step has been completed, you also can determine the type of authentication required. However, the type of authentication required will only be available if and only if the methods mentioned above (see above) return AXIS2_TRUE. The method for determining the type of authentication required for HTTP authentication for server or proxy is,

axis2_svc_client_get_auth_type(svc_client, env);

Please note that you have just a single method for both authentication schemes, unlike all other instances. This is because only one authentication scheme can fail at a time. And, if HTTP authentication for server and HTTP authentication for proxy are both to fail, HTTP authentication for proxy will fail first. This is because in a client-server communication the server would be the last down stream node reachable by the client's request. This will be the entity that responds to the request made. All upstream nodes would rather be considered as proxies.

Using the Authentication Sample

The Axis2/C distribution comes with a sample that reveals the usage of Client Side Extensions for HTTP Authentication. This can be found in the clients sub folder found inside samples/user_guide (or samples\user_guide on MS Windows systems), by the name echo_blocking_auth. It provides a simple command line interface where you can input HTTP authentication information for both server and proxy. In addition to that, it will also indicate whether authentication was required and vice versa. You can find an online version at, [5].

Server Side and Service Level Support

As of version 1.3.0, Axis2/C still does not support server side authentication for the Simple Axis2 HTTP Server. However, you can setup HTTP authentication on Apache Server or on IIS, if you are using the respective modules rather.

The HTTP 1.1 Authentication Framework also leaves room for Application Layer, [6], use of HTTP Basic Authentication as means of resource level access restriction. However, the ability to use HTTP authentication as a tool to authenticate users in RESTful Services, is not fully supported by Axis2/C yet. Rather, a user is given the opportunity to read incoming transport headers and derive credentials used in HTTP Basic Authentication. This can be done by setting the exposeHeaders parameter value as true instead of false under the respective transport sender.

<parameter name="exposeHeaders" locked="true">true</parameter>

Future

In the near future, we hope to improve support for Service Level Authentication even further, especially for RESTful services, where RESTful services could request authentication information using transport headers instead of the XML payload, if they were unavailable.

Among improvements to the Client API are, provisions to do NTLM Authentication using the libcurl based transport in Axis2/C, and , as a whole, extending Client Side Extensions for HTTP Authentication to cover the libcurl based transport. These can be listed as features of future releases.

Summary

HTTP authentication, as specified in the HTTP 1.1 Authentication Framework Specification, [2], is a mechanism to support filtering access to protected resources. HTTP based transports, can make use of this framework to filter access to resources. Web services made available in such environments are naturally enforced with these restrictions. Axis2/C Client Side Extensions for HTTP Authentication provides clients with the ability to communicate with services in such restricted environments.

HTTP based applications are also given the ability to use HTTP Basic Authentication as means of application layer filtering, for accessing protected resources. Axis2/C does not fully support this feature at  service level at the present, but, we look forward to do seing that facility added in the near future.

References

Author

Senaka L. Fernando, Team Member, Apache Axis2/C, senaka at wso2 dot com