Return-Path: Delivered-To: apmail-jakarta-commons-dev-archive@www.apache.org Received: (qmail 4996 invoked from network); 1 Jun 2004 20:57:06 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199) by minotaur-2.apache.org with SMTP; 1 Jun 2004 20:57:06 -0000 Received: (qmail 18523 invoked by uid 500); 1 Jun 2004 20:57:14 -0000 Delivered-To: apmail-jakarta-commons-dev-archive@jakarta.apache.org Received: (qmail 18325 invoked by uid 500); 1 Jun 2004 20:57:12 -0000 Mailing-List: contact commons-dev-help@jakarta.apache.org; run by ezmlm Precedence: bulk List-Unsubscribe: List-Subscribe: List-Help: List-Post: List-Id: "Jakarta Commons Developers List" Reply-To: "Jakarta Commons Developers List" Delivered-To: mailing list commons-dev@jakarta.apache.org Received: (qmail 18286 invoked by uid 500); 1 Jun 2004 20:57:12 -0000 Received: (qmail 18271 invoked by uid 99); 1 Jun 2004 20:57:12 -0000 Received: from [209.237.227.194] (HELO minotaur.apache.org) (209.237.227.194) by apache.org (qpsmtpd/0.27.1) with SMTP; Tue, 01 Jun 2004 13:57:12 -0700 Received: (qmail 4660 invoked by uid 1624); 1 Jun 2004 20:56:52 -0000 Date: 1 Jun 2004 20:56:52 -0000 Message-ID: <20040601205652.4659.qmail@minotaur.apache.org> From: olegk@apache.org To: jakarta-commons-cvs@apache.org Subject: cvs commit: jakarta-commons/httpclient/xdocs authentication.xml X-Virus-Checked: Checked X-Spam-Rating: minotaur-2.apache.org 1.6.2 0/1000/N olegk 2004/06/01 13:56:52 Modified: httpclient/xdocs Tag: HTTPCLIENT_2_0_BRANCH authentication.xml Log: PR #29062 ([API Doc] Improve the description of the preemptive authentication) Contributed by Oleg Kalnichevski Reviewed by Michael Becke Revision Changes Path No revision No revision 1.5.2.4 +37 -6 jakarta-commons/httpclient/xdocs/authentication.xml Index: authentication.xml =================================================================== RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/authentication.xml,v retrieving revision 1.5.2.3 retrieving revision 1.5.2.4 diff -u -r1.5.2.3 -r1.5.2.4 --- authentication.xml 21 Aug 2003 16:07:31 -0000 1.5.2.3 +++ authentication.xml 1 Jun 2004 20:56:52 -0000 1.5.2.4 @@ -6,6 +6,7 @@ HttpClient Authentication Guide Jeff Dever Adrian Sutton + Oleg Kalnichevski $Id$ @@ -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,28 @@ 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. +

+

+ Setting credentials with null host and realm values is highly + discouraged in production applications. Doing this will result in the credentials + being sent for all authentication attempts (all requests in the case of + preemptive authentication). Use of this setting should be limited to debugging + only. +

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

There is an example +

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

--------------------------------------------------------------------- To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org For additional commands, e-mail: commons-dev-help@jakarta.apache.org