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 NTLM and SPNEGO.

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. 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. stdout > 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. stdout >

The AuthScheme interface represents an abstract challenge-response oriented authentication scheme. An authentication scheme is expected to support the following functions: Parse and process the challenge sent by the target server in response to request for a protected resource. Provide properties of the processed challenge: the authentication scheme type and its parameters, such the realm this authentication scheme is applicable to, if available Generate authorization string for the given set of credentials and the HTTP request in response to the actual authorization challenge. Please note authentication schemes may be stateful involving a series of challenge-response exchanges. HttpClient ships with several AuthScheme implementations: 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. 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. 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 supported only partially and requires an external NTLM engine. For details please refer to the NTLM_SUPPORT.txt document included with HttpClient distributions. SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) is a GSSAPI "pseudo mechanism" that is used to negotiate one of a number of possible real mechanisms. SPNEGO's most visible use is in Microsoft's HTTP Negotiate authentication extension. The negotiable sub-mechanisms include NTLM and Kerberos supported by Active Directory. Presently HttpClient supports Kerberos sub-mechanism only.

These are parameters that be used to customize HTTP authentication process and behaviour of individual authentication schemes: defines whether authentication should be handled automatically. This parameter expects a value of type java.lang.Boolean. If this parameter is not set HttpClient will handle authentication automatically. defines the charset to be used when encoding user credentials. This parameter expects a value of type java.lang.String. If this parameter is not set US-ASCII will be used. Defines the order of preference for supported AuthSchemes when authenticating with the target host. This parameter expects a value of type java.util.Collection. The collection is expected to contain java.lang.String instances representing an id of an authentication scheme. Defines the order of preference for supported AuthSchemes when authenticating with the proxy host. This parameter expects a value of type java.util.Collection. The collection is expected to contain java.lang.String instances representing an id of an authentication scheme. For example, one can force HttpClient to use a different order of preference for authentication schemes authpref = new ArrayList(); authpref.add(AuthPolicy.BASIC); authpref.add(AuthPolicy.DIGEST); httpclient.getParams().setParameter(AuthPNames.PROXY_AUTH_PREF, authpref); ]]>

HttpClient maintains a registry of available authentication scheme using AuthSchemeRegistry class. The following schemes are registered per default: Basic authentication scheme Digest authentication scheme Please note NTLM and SPNEGO schemes are NOT registered per default. For details on how to enable NTLM support please refer to the NTLM_SUPPORT.txt document included with HttpClient distributions. SPNEGO setup tends to be system specific and must be properly configured in order to be functional. See section on SPNEGO authentication for details.

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. HttpClient can work with any physical representation of a credentials provider that implements the CredentialsProvider interface. The default CredentialsProvider implementation called BasicCredentialsProvider is a simple implementation backed by a java.util.HashMap. stdout >

HttpClient relies on the AuthState class to keep track of detailed information about the state of the authentication process. HttpClient creates two instances of 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 AuthScope instance will be populated with the AuthScope, AuthScheme and Crednetials used during the authentication process. The AuthState can be examined in order to find out what kind of authentication was requested, whether a matching AuthScheme implementation was found and whether the credentials provider managed to find user credentials for the given authentication scope. In the course of HTTP request execution HttpClient adds the following authentication related objects to the execution context: AuthSchemeRegistry instance representing the actual authentication scheme registry. The value of this attribute set in the local context takes precedence over the default one. CookieSpec instance representing the actual credentials provider. The value of this attribute set in the local context takes precedence over the default one. AuthState instance representing the actual target authentication state. The value of this attribute set in the local context takes precedence over the default one. AuthState instance representing the actual proxy authentication state. The value of this attribute set in the local context takes precedence over the default one. 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:

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. This is an example of a simple protocol interceptor that preemptively introduces an instance of 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.

SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) is designed to allow for authentication to services when neither end knows what the other can use/provide. It is most commonly used to do Kerberos authentication. It can wrap other mechanisms, however the current version in HttpClient is designed solely with Kerberos in mind. Client Web Browser does HTTP GET for resource. Web server returns HTTP 401 status and a header: WWW-Authenticate: Negotiate Client generates a NegTokenInit, base64 encodes it, and resubmits the GET with an Authorization header: Authorization: Negotiate <base64 encoding>. Server decodes the NegTokenInit, extracts the supported MechTypes (only Kerberos V5 in our case), ensures it is one of the expected ones, and then extracts the MechToken (Kerberos Token) and authenticates it. If more processing is required another HTTP 401 is returned to the client with more data in the the WWW-Authenticate header. Client takes the info and generates another token passing this back in the Authorization header until complete. When the client has been authenticated the Web server should return the HTTP 200 status, a final WWW-Authenticate header and the page content.

SPNEGO authentication scheme is compatible with Sun Java versions 1.5 and up. The Sun JRE provides the supporting classes to do nearly all the kerberos and SPNEGO token handling. This means that a lot of the setup is for the GSS classes. The NegotiateScheme is a simple class to handle marshalling the tokens and reading and writing the correct headers. The best way to start is to grab the KerberosHttpClient.java file in examples and try and get it to work. There are a lot of issues that can happen but if lucky it'll work without too much problem. It should also provide some output to debug with. In windows it should default to using the logged in credentials, this can be overridden by using 'kinit' e.g. $JAVA_HOME\bin\kinit testuser@AD.EXAMPLE.NET, which is very helpful for testing and debugging issues. Remove the cache file created to revert back to the windows Kerberos cache. Make sure to list domain_realms in the krb5.conf file. This is a major source of problems.

This documentation assumes you are using windows but much of the information applies to Unix as well. The org.ietf.jgss classes have lots of possible configuration parameters, mainly in the krb5.conf/krb5.ini file. Some more info on the format at http://web.mit.edu/kerberos/krb5-1.4/krb5-1.4.1/doc/krb5-admin/krb5.conf.html.

The following configuration is a basic setup that works in Windows XP against both IIS7 and JbossNegotiate modules. The system property java.security.auth.login.config can be use to point at the login.conf file. login.conf content may look like the following:

If unspecified the system default will be used. Override if needed by the setting system property java.security.krb5.conf to point at a custom krb5.conf file. krb5.conf content may look like the following:

To allow windows to use the current users tickets system property javax.security.auth.useSubjectCredsOnly must be set to false and Windows registry key allowtgtsessionkey should be added and set correctly to allow session keys to be sent in the Kerberos Ticket-Granting Ticket. On the Windows Server 2003 and Windows 2000 SP4, here is the required registry setting: Here is the location of the registry setting on Windows XP SP2:

Please note SPNEGO authentication scheme is NOT active per default! In order to activate SPNEGO support an instance of NegotiateSchemeFactory class must be created and registered with the authentication scheme registry of HttpClient. There are several methods that can be used to customize the behaviour of NegotiateSchemeFactory.

Strips the port off service names e.g. HTTP/webserver.ad.example.net:8080 -> HTTP/webserver.ad.example.net Found it useful when using JbossNegotiation.

If using Java 1.5 or a Kerberos ticket an attempt will be made to wrap it up into a SPNEGO token. Again for JbossNegotiation. II7 accepts plain Kerberos tickets.

Use this method to inject a custom SpnegoTokenGenerator class to do the Kerberos to SPNEGO token wrapping. BouncySpnegoTokenGenerator implementation is provided as unsupported contribution from the contrib package. This requires the BouncyCastle libs "http://www.bouncycastle.org/java.html"