? xdocs/stylesheets/site.vsl Index: xdocs/authentication.xml =================================================================== RCS file: /home/cvspublic/jakarta-commons/httpclient/xdocs/authentication.xml,v retrieving revision 1.1 diff -u -r1.1 authentication.xml --- xdocs/authentication.xml 20 Feb 2003 00:43:52 -0000 1.1 +++ xdocs/authentication.xml 20 Feb 2003 03:01:18 -0000 @@ -1,140 +1,148 @@ - - - - - - HttpClient Authentication Guide - Jeff Dever - Adrian Sutton - $Id: authentication.xml,v 1.1 2003/02/20 00:43:52 jsdever Exp $ - - - - -
- HttpClient supports three different types of http authentication schemes: - Basic, Digest and NTLM. These can be used to authenticate with http servers - or proxies. -
- -
-

HttpClient handles authenticating with servers almost transparently, - the only thing a developer must do is actually provide the login - credentials. These credentials are stored in the HttpState instance - and can be set or retrieved using the setCredentials(String realm, - Credentials cred) and getCredentials(String realm) - methods.

- -

Note: To set default Credentials for any realm that has not been - explicitly specified, pass in null as the value of - realm.

- -

The automatic authorization built in to HttpClient can be disabled - with the method setDoAuthentication(boolean doAuthentication) - in the HttpMethod class. The change only affects that method instance.

- -

Preemptive authentication can be enabled within HttpClient. In this - mode HttpClient will send the basic authentication response even before - the server gives an unauthorized response in certain situations, thus - reducing the overhead of making the connection. To enable this use the - following:

- -

setSystemProperty(Authenticator.PREEMPTIVE_PROPERTY, "true"); -

- -

The preemptive authentication conforms to rfc2617: - -

A client SHOULD assume that all paths at or deeper than the depth - of the last symbolic element in the path field of the Request-URI also - are within the protection space specified by the Basic realm value - of the current challenge. A client MAY preemptively send the - corresponding Authorization header with requests for resources in - that space without receipt of another challenge from the server. - Similarly, when a client sends a request to a proxy, it may reuse - a userid and password in the Proxy-Authorization header field without - receiving another challenge from the proxy server.
-

-
- -
-

Proxy authentication in HttpClient is almost identical to server - authentication with the exception that the credentials for each are - stored independantly. So for proxy authentication you must use - setProxyCredentials(String realm, Credentials cred) and - getProxyCredentials(String realm). As with server - authentication, passing null as the realm sets or returns - the default credentials.

-
- -
-

Basic authentication is the original and most compatible authentication - scheme for HTTP. Unfortunately, it is also the least secure as it sends - the username and password unencrypted to the server. Basic authentication - requires an instance of UsernamePasswordCredentials (which NTCredentials - extends) to be available, either for the specific realm specified by the - server or as the default credentials.

-
- -
-

Digest authentication was added in the HTTP 1.1 protocol and while - not being as widely supported as Basic authentication there is a great - deal of support for it. Digest authentication is significantly more - secure than basic authentication as it never transfers the actual - password across the network, but instead uses it to encrypt a "nonce" - value sent from the server.

- -

Digest authentication requires an instance of - UsernamePasswordCredentials (which NTCredentials extends) to be - available either for the specific realm specified by the server or as - the default credentials.

-
- -
-

NTLM is the most complex of the authentication protocols supported - by HttpClient. It is a proprietary protocol designed by Microsoft - with no publicly available specification. Early version of NTLM were - less secure than Digest authentication due to faults in the design, - however these were fixed in a service pack for Window NT 4 and the - protocol is now considered more secure than Digest authentication.

- -

NTLM authentication 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.

- -

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.

- -

-

    -
  1. 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).
  2. - -
  3. 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.
  4. - -
  5. 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.
  6. -
-

-
- - - -
+ + + + + + HttpClient Authentication Guide + Jeff Dever + Adrian Sutton + $Id: $ + + + + +
+

HttpClient supports three different types of http authentication schemes: + Basic, Digest and NTLM. These can be used to authenticate with http servers + or proxies.

+
+ +
+

HttpClient handles authenticating with servers almost transparently, + the only thing a developer must do is actually provide the login + credentials. These credentials are stored in the HttpState instance + and can be set or retrieved using the setCredentials(String realm, + Credentials cred) and getCredentials(String realm) + methods.

+ +

Note: To set default Credentials for any realm that has not been + explicitly specified, pass in null as the value of + realm.

+ +

The automatic authorization built in to HttpClient can be disabled + with the method setDoAuthentication(boolean doAuthentication) + in the HttpMethod class. The change only affects that method instance.

+ + +

Preemptive authentication can be enabled within HttpClient. In this + mode HttpClient will send the basic authentication response even before + the server gives an unauthorized response in certain situations, thus reducing the overhead + of making the connection. To enable this use the following:

+ + setSystemProperty(Authenticator.PREEMPTIVE_PROPERTY, "true"); + +

The preemptive authentication conforms to rfc2617:

+ +
A client SHOULD assume that all paths at or deeper than the depth + of the last symbolic element in the path field of the Request-URI also + are within the protection space specified by the Basic realm value + of the current challenge. A client MAY preemptively send the + corresponding Authorization header with requests for resources in + that space without receipt of another challenge from the server. + Similarly, when a client sends a request to a proxy, it may reuse + a userid and password in the Proxy-Authorization header field without + receiving another challenge from the proxy server.
+
+
+ +
+

Proxy authentication in HttpClient is almost identical to server + authentication with the exception that the credentials for each are + stored independantly. So for proxy authentication you must use + setProxyCredentials(String realm, Credentials cred) and + getProxyCredentials(String realm). As with server + authentication, passing null as the realm sets or returns + the default credentials.

+
+ +
+

The following authentication schemes are supported by HttpClient.

+ +

Basic authentication is the original and most compatible authentication + scheme for HTTP. Unfortunately, it is also the least secure as it sends + the username and password unencrypted to the server. Basic authentication + requires an instance of UsernamePasswordCredentials (which NTCredentials + extends) to be available, either for the specific realm specified by the + server or as the default credentials.

+
+ + +

Digest authentication was added in the HTTP 1.1 protocol and while + not being as widely supported as Basic authentication there is a great + deal of support for it. Digest authentication is significantly more + secure than basic authentication as it never transfers the actual + password across the network, but instead uses it to encrypt a "nonce" + value sent from the server.

+ +

Digest authentication requires an instance of + UsernamePasswordCredentials (which NTCredentials extends) to be + available either for the specific realm specified by the server or as + the default credentials.

+
+ + +

NTLM is the most complex of the authentication protocols supported + by HttpClient. It is a proprietary protocol designed by Microsoft + with no publicly available specification. Early version of NTLM were + less secure than Digest authentication due to faults in the design, + however these were fixed in a service pack for Windows NT 4 and the + protocol is now considered more secure than Digest authentication.

+ +

NTLM authentication 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.

+ +

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.

+ +

+

    +
  1. 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).
  2. + +
  3. 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.
  4. + +
  5. 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.
  6. +
+

+
+
+ +
+

There is an example of using authentication available in the + example directory in CVS. The particulary example is the + BasicAuthenticationExample.

+
+ + + +
Index: xdocs/navigation.xml =================================================================== RCS file: /home/cvspublic/jakarta-commons/httpclient/xdocs/navigation.xml,v retrieving revision 1.4 diff -u -r1.4 navigation.xml --- xdocs/navigation.xml 20 Feb 2003 00:43:52 -0000 1.4 +++ xdocs/navigation.xml 20 Feb 2003 03:01:18 -0000 @@ -15,11 +15,15 @@ - - - - - + + + + + + + + +