Index: authentication.xml =================================================================== RCS file: /home/cvspublic/jakarta-commons/httpclient/xdocs/authentication.xml,v retrieving revision 1.5.2.3 diff -u -r1.5.2.3 authentication.xml --- authentication.xml 21 Aug 2003 16:07:31 -0000 1.5.2.3 +++ authentication.xml 31 May 2004 11:59:21 -0000 @@ -6,6 +6,7 @@ HttpClient Authentication Guide Jeff Dever Adrian Sutton + Oleg Kalnichevski $Id: authentication.xml,v 1.5.2.3 2003/08/21 16:07:31 oglueck Exp $ @@ -22,8 +23,8 @@ 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.

+ String host, Credentials cred) and getCredentials(String realm, + String host) methods.

Note: To set default Credentials for any realm that has not been explicitly specified, pass in null as the value of @@ -41,7 +42,15 @@ client.getState().setAuthenticationPreemptive(true); -

To enable preemptive authentication by default for all newly created +

Preemptive authentication mode also requires default Credentials to be set + for the target or proxy host against which preemptive authentication is to be + attempted. Failure to provide default credentials will render the preemptive + authentication mode ineffective.

+ +Credentials defaultcreds = new UsernamePasswordCredentials("username", "password"); +client.getState().setCredentials(null, "myhost", defaultcreds); + +

To enable preemptive authentication by default for all newly created HttpState's, a system property can be set, as shown below.

setSystemProperty(Authenticator.PREEMPTIVE_PROPERTY, "true"); @@ -58,6 +67,26 @@ a userid and password in the Proxy-Authorization header field without receiving another challenge from the proxy server. + + +

Use default credentials with caution when developing applications + that may need to communicate with untrusted web sites or web + applications. When preemptive authentication is activated or credentials + are not explicitly given for a specific authentication realm and host + HttpClient will use default credentials to try to authenticate with the + target site. If you want to avoid sending sensitive credentials to an untrusted + site, narrow the credentials scope as much as possible: always specify the + host and, when known, the realm the credentials are intended for.

+

+ It is highly recommended to avoid setting credentials for any host and realm + (null host and null authentication realm) in productive + applications. Use the least restrictive credentials scope when debugging only +

+// To be avoided unless in debug mode +Credentials defaultcreds = new UsernamePasswordCredentials("username", "password"); +client.getState().setCredentials(null, null, defaultcreds); + +
@@ -150,9 +179,9 @@
-

There is an example +

There is an example of basic authentication available in the - example directory in CVS. + example directory in CVS.