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 @@
<title>HttpClient Authentication Guide</title>
<author email="[EMAIL PROTECTED]">Jeff Dever</author>
<author email="[EMAIL PROTECTED]">Adrian Sutton</author>
+ <author email="oleg -at- ural.ru">Oleg Kalnichevski</author>
<revision>$Id$</revision>
</properties>
@@ -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 <code>setCredentials(String
realm,
- Credentials cred)</code> and <code>getCredentials(String realm)</code>
- methods.</p>
+ String host, Credentials cred)</code> and <code>getCredentials(String
realm,
+ String host)</code> methods.</p>
<p><i>Note:</i> To set default Credentials for any realm that has not
been
explicitly specified, pass in <code>null</code> as the value of
@@ -41,7 +42,15 @@
<source>client.getState().setAuthenticationPreemptive(true);</source>
- <p>To enable preemptive authentication by default for all newly created
+ <p>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.</p>
+
+<source>Credentials defaultcreds = new UsernamePasswordCredentials("username",
"password");
+client.getState().setCredentials(null, "myhost", defaultcreds);</source>
+
+ <p>To enable preemptive authentication by default for all newly created
<tt>HttpState</tt>'s, a system property can be set, as shown below.</p>
<source>setSystemProperty(Authenticator.PREEMPTIVE_PROPERTY,
"true");</source>
@@ -58,6 +67,28 @@
a userid and password in the Proxy-Authorization header field without
receiving another challenge from the proxy server.</blockquote>
</subsection>
+ <subsection name="Security aspects of server authentication">
+
+ <p>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.
+ </p>
+ <p>
+ Setting credentials with <code>null</code> 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.
+ </p>
+<source>// To be avoided unless in debug mode
+Credentials defaultcreds = new UsernamePasswordCredentials("username", "password");
+client.getState().setCredentials(null, null, defaultcreds);</source>
+
+ </subsection>
</section>
<section name="Proxy Authentication">
@@ -150,9 +181,9 @@
</section>
<section name="Examples">
- <p>There is an <a
href="http://cvs.apache.org/viewcvs.cgi/*checkout*/jakarta-commons/httpclient/src/examples/BasicAuthenticatonExample.java?rev=HEAD&content-type=text/plain";>example</a>
+ <p>There is an <a
href="http://cvs.apache.org/viewcvs.cgi/jakarta-commons/httpclient/src/examples/BasicAuthenticationExample.java?rev=1.1.2.3&only_with_tag=HTTPCLIENT_2_0_BRANCH";>example</a>
of basic authentication available in the
- <a
href="http://cvs.apache.org/viewcvs.cgi/jakarta-commons/httpclient/src/examples/";>example
directory</a> in CVS.
+ <a
href="http://cvs.apache.org/viewcvs.cgi/jakarta-commons/httpclient/src/examples/?only_with_tag=HTTPCLIENT_2_0_BRANCH";>example
directory</a> in CVS.
</p>
</section>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
