olegk 2004/06/01 13:57:59
Modified: httpclient/xdocs 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
1.10 +35 -5 jakarta-commons/httpclient/xdocs/authentication.xml
Index: authentication.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/authentication.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- authentication.xml 21 Aug 2003 16:08:54 -0000 1.9
+++ authentication.xml 1 Jun 2004 20:57:59 -0000 1.10
@@ -22,8 +22,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 +41,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 +66,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">
@@ -155,7 +185,7 @@
<a
href="http://cvs.apache.org/viewcvs.cgi/jakarta-commons/httpclient/src/examples/";>example
directory</a> in CVS.
</p>
</section>
-
+
<section name="Troubleshooting">
<p>Some authentication schemes may use cryptographic algorithms. It is
recommended to include the
<a href="http://java.sun.com/products/jce/"; target="_blank">Java
Cryptography Extension</a> in
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
