Java example source code file (authentication.xml)

This example source code file (authentication.xml) is included in the DevDaily.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Java tags/keywords

authscope, authstate, cdata, defaulthttpclient, http, httpclient, httpget, license, microsoft, ntcredentials, the, this, usernamepasswordcredentials, windows

The authentication.xml example source code

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
                 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<!-- 
    ====================================================================
    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at
    
    http://www.apache.org/licenses/LICENSE-2.0
    
    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.
    ====================================================================
-->
<chapter id="authentication">
    <title>HTTP authentication
    <para>HttpClient provides full support for authentication schemes defined by the HTTP standard
        specification. HttpClient's authentication framework can also be extended to support
        non-standard authentication schemes such as <literal>NTLM and
            <literal>SPNEGO.
    <section>
        <title>User credentials
        <para>Any process of user authentication requires a set of credentials that can be used to
            establish user identity. In the simplest form user crednetials can be just a user name /
            password pair. <classname>UsernamePasswordCredentials represents a set of
            credentials consisting of a security principal and a password in clear text. This
            implementation is sufficient for standard authentication schemes defined by the HTTP
            standard specification.</para>
        <programlisting>
        <para>stdout >
        <programlisting>
        <para>NTCredentials is a Microsoft Windows specific implementation
            that includes in addition to the user name / password pair a set of additional Windows
            specific attributes such as a name of the user domain, as in Microsoft Windows network
            the same user can belong to multiple domains with a different set of
            authorizations.</para>
        <programlisting>
        <para>stdout >
        <programlisting>
    </section>
    <section>
        <title>Authentication schemes
        <para>The AuthScheme interface represents an abstract
            challenge-response oriented authentication scheme. An authentication scheme is expected
            to support the following functions:</para>
        <itemizedlist>
            <listitem>
                <para>Parse and process the challenge sent by the target server in response to
                    request for a protected resource.</para>
            </listitem>
            <listitem>
                <para>Provide properties of the processed challenge: the authentication scheme type
                    and its parameters, such the realm this authentication scheme is applicable to,
                    if available</para>
            </listitem>
            <listitem>
                <para>Generate authorization string for the given set of credentials and the HTTP
                    request in response to the actual authorization challenge.</para>
            </listitem>
        </itemizedlist>
        <para>Please note authentication schemes may be stateful involving a series of
            challenge-response exchanges.</para>
        <para>HttpClient ships with several AuthScheme
            implementations:</para>
        <itemizedlist>
            <listitem>
                <formalpara>
                    <title>Basic:
                    <para>Basic authentication scheme as defined in RFC 2617. This authentication
                        scheme is insecure, as the credentials are transmitted in clear text.
                        Despite its insecurity Basic authentication scheme is perfectly adequate if
                        used in combination with the TLS/SSL encryption.</para>
                </formalpara>
            </listitem>
            <listitem>
                <formalpara>
                    <title>Digest
                    <para>Digest authentication scheme as defined in RFC 2617. Digest authentication
                        scheme is significantly more secure than Basic and can be a good choice for
                        those applications that do not want the overhead of full transport security
                        through TLS/SSL encryption.</para>
                </formalpara>
            </listitem>
            <listitem>
                <formalpara>
                    <title>NTLM:
                    <para>NTLM is a proprietary authentication scheme developed by Microsoft and
                        optimized for Windows platforms. NTLM is believed to be more secure than
                        Digest. This scheme is requires an external NTLM engine to be functional. 
                        For details please refer to the <literal>NTLM_SUPPORT.txt document 
                        included with HttpClient distributions.</para>
                </formalpara>
            </listitem>
        </itemizedlist>
    </section>
    <section>
        <title>HTTP authentication parameters
        <para>These are parameters that be used to customize HTTP authentication process and
            behaviour of individual authentication schemes:</para>
        <itemizedlist>
            <listitem>
                <formalpara>
                    <title>'http.protocol.handle-authentication':
                    <para>defines whether authentication should be handled automatically. This
                        parameter expects a value of type <classname>java.lang.Boolean.
                        If this parameter is not set HttpClient will handle authentication
                        automatically.</para>
                </formalpara>
            </listitem>
            <listitem>
                <formalpara>
                    <title>'http.auth.credential-charset':
                    <para>defines the charset to be used when encoding user credentials. This
                        parameter expects a value of type <literal>java.lang.String. If
                        this parameter is not set <literal>US-ASCII will be used.
                </formalpara>
            </listitem>
        </itemizedlist>
    </section>
    <section>
        <title>Authentication scheme registry
        <para>HttpClient maintains a registry of available authentication scheme using
                <classname>AuthSchemeRegistry class. The following schemes are
            registered per default:</para>
        <itemizedlist>
            <listitem>
                <formalpara>
                    <title>Basic:
                    <para>Basic authentication scheme
                </formalpara>
            </listitem>
            <listitem>
                <formalpara>
                    <title>Digest:
                    <para>Digest authentication scheme
                </formalpara>
            </listitem>
        </itemizedlist>
        <para>Please note NTLM scheme is NOT registered per 
            default. The <literal>NTLM cannot be enabled per default due to licensing and 
            legal reasons. For details on how to enable <literal>NTLM support please see 
            <link linkend="ntlm">this section. 
    </section>
    <section>
        <title>Credentials provider
        <para>Credentials providers are intended to maintain a set of user credentials and to be
            able to produce user credentials for a particular authentication scope. Authentication
            scope consists of a host name, a port number, a realm name and an authentication scheme
            name. When registering credentials with the credentials provider one can provide a wild
            card (any host, any port, any realm, any scheme) instead of a concrete attribute value.
            The credentials provider is then expected to be able to find the closest match for a
            particular scope if the direct match cannot be found.</para>
        <para>HttpClient can work with any physical representation of a credentials provider that
            implements the <interfacename>CredentialsProvider interface. The default
                <interfacename>CredentialsProvider implementation called
                <classname>BasicCredentialsProvider is a simple implementation backed by
            a <classname>java.util.HashMap.
        <programlisting>
        <para>stdout >
        <programlisting>
    </section>
    <section>
        <title>HTTP authentication and execution context
        <para>HttpClient relies on the AuthState class to keep track of
            detailed information about the state of the authentication process. HttpClient creates
            two instances of <classname>AuthState in the course of HTTP request
            execution: one for target host authentication and another one for proxy authentication.
            In case the target server or the proxy require user authentication the respective
                <classname>AuthScope instance will be populated with the
                <classname>AuthScope, AuthScheme and
                <interfacename>Crednetials used during the authentication process.
            The <classname>AuthState can be examined in order to find out what kind of
            authentication was requested, whether a matching
                <interfacename>AuthScheme implementation was found and whether the
            credentials provider managed to find user credentials for the given authentication
            scope.</para>
        <para>In the course of HTTP request execution HttpClient adds the following authentication
            related objects to the execution context:</para>
        <itemizedlist>
            <listitem>
                <formalpara>
                    <title>'http.authscheme-registry':
                    <para>AuthSchemeRegistry instance representing the actual
                        authentication scheme registry. The value of this attribute set in the local
                        context takes precedence over the default one.</para>
                </formalpara>
            </listitem>
            <listitem>
                <formalpara>
                    <title>'http.auth.credentials-provider':
                    <para>CookieSpec instance representing the actual
                        credentials provider. The value of this attribute set in the local context
                        takes precedence over the default one.</para>
                </formalpara>
            </listitem>
            <listitem>
                <formalpara>
                    <title>'http.auth.target-scope':
                    <para>AuthState instance representing the actual target
                        authentication state. The value of this attribute set in the local context
                        takes precedence over the default one.</para>
                </formalpara>
            </listitem>
            <listitem>
                <formalpara>
                    <title>'http.auth.proxy-scope':
                    <para>AuthState instance representing the actual proxy
                        authentication state. The value of this attribute set in the local context
                        takes precedence over the default one.</para>
                </formalpara>
            </listitem>
        </itemizedlist>
        <para>The local HttpContext object can be used to customize
            the HTTP authentication context prior to request execution or examine its state after
            the request has been executed:</para>
        <programlisting>
    </section>
    <section>
        <title>Preemptive authentication
        <para>HttpClient does not support preemptive authentication out of the box, because if
            misused or used incorrectly the preemptive authentication can lead to significant
            security issues, such as sending user credentials in clear text to an unauthorized third
            party. Therefore, users are expected to evaluate potential benefits of preemptive
            authentication versus security risks in the context of their specific application
            environment and are required to add support for preemptive authentication using standard
            HttpClient extension mechanisms such as protocol interceptors.</para>
        <para>This is an example of a simple protocol interceptor that preemptively introduces an
            instance of <classname>BasicScheme to the execution context, if no
            authentication has been attempted yet. Please note that this interceptor must be added
            to the protocol processing chain before the standard authentication interceptors.</para>
        <programlisting>
    </section>

    <section id="ntlm">
        <title>NTLM Authentication
        <para>Currently HttpClient does not provide support for the NTLM authentication scheme out
            of the box and probably never will. The reasons for that are legal rather than 
            technical. However, NTLM authentication can be enabled by using an external 
            <literal>NTLM engine such as JCIFS
            </ulink> library developed by the Samba
            project as a part of their Windows interoperability suite of programs. For details 
            please refer to the <literal>NTLM_SUPPORT.txt document included with 
            HttpClient distributions.
        </para>
        <section>
            <title>NTLM connection persistence
            <para>NTLM authentication scheme is significantly more expensive
                in terms of computational overhead and performance impact than the standard 
                <literal>Basic and Digest schemes. This is likely to be
                one of the main reasons why Microsoft chose to make <literal>NTLM 
                authentication scheme stateful. That is, once authenticated, the user identity is 
                associated with that connection for its entire life span. The stateful nature of 
                <literal>NTLM connections makes connection persistence more complex, as 
                for the obvious reason persistent <literal>NTLM connections may not be 
                re-used by users with a different user identity. The standard connection managers 
                shipped with HttpClient are fully capable of managing stateful connections. However, 
                it is critically important that logically related requests within the same session 
                use the same execution context in order to make them aware of the current user 
                identity. Otherwise, HttpClient will end up creating a new HTTP connection for each 
                HTTP request against <literal>NTLM protected resources. For detailed 
                discussion on stateful HTTP connections please refer to 
                <link linkend="stateful_conn">this  section. 
            <para>As NTLM connections are stateful it is generally recommended
                to trigger <literal>NTLM authentication using a relatively cheap method,
                such as <literal>GET or HEAD, and re-use the same 
                connection to execute more expensive methods, especially those enclose a request
                entity, such as <literal>POST or PUT. 
            <programlisting>
        </section>
    </section>

</chapter>