-
-
Notifications
You must be signed in to change notification settings - Fork 5
Expand file tree
/
Copy pathauthentication.html
More file actions
280 lines (248 loc) · 19.3 KB
/
Copy pathauthentication.html
File metadata and controls
280 lines (248 loc) · 19.3 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>HttpClient - HttpClient Authentication Guide</title><style type="text/css" media="all">
@import url("./style/maven-base.css");
@import url("./style/maven-theme.css");@import url("./style/project.css");</style><link rel="stylesheet" href="./style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta><meta name="author" content="Jeff Dever"></meta><meta name="email" content="jsdever@apache.org"></meta><meta name="author" content="Adrian Sutton"></meta><meta name="email" content="adrian.sutton@ephox.com"></meta></head><body class="composite"><div id="banner"><a href="http://jakarta.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src="http://jakarta.apache.org/images/jakarta-logo.gif"></img></a><a href="http://jakarta.apache.org/httpcomponents/httpclient-3.x/" id="projectLogo"><img alt="HttpClient" src="./images/httpclient_logo.png"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">Last published: 18 August 2007
<span class="separator">|</span> Doc for 3.1
</div><div class="xright"></div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuOverview"><h5>Overview</h5><ul><li class="none"><a href="features.html">Features</a></li><li class="none"><a href="news.html">News</a></li><li class="none"><a href="status.html">Status</a></li><li class="none"><a href="downloads.html">Download</a></li><li class="none"><a href="http://wiki.apache.org/jakarta-httpclient/" class="externalLink" title="External Link">Wiki</a></li><li class="expanded"><a href="userguide.html">User Guide</a><ul><li class="none"><strong><a href="authentication.html">Authentication Guide</a></strong></li><li class="none"><a href="charencodings.html">Character Encodings</a></li><li class="none"><a href="cookies.html">Cookies</a></li><li class="none"><a href="exception-handling.html">Exception Handling</a></li><li class="none"><a href="logging.html">Logging Guide</a></li><li class="none"><a href="methods.html">Methods</a></li><li class="none"><a href="performance.html">Optimization Guide</a></li><li class="none"><a href="preference-api.html">Preference Architecture</a></li><li class="none"><a href="redirects.html">Redirects Handling</a></li><li class="none"><a href="http://svn.apache.org/viewvc/jakarta/httpcomponents/oac.hc3x/trunk/src/examples/" class="externalLink" title="External Link">Sample Code</a></li><li class="none"><a href="sslguide.html">SSL Guide</a></li><li class="none"><a href="threading.html">Threading</a></li><li class="none"><a href="troubleshooting.html">Trouble Shooting</a></li><li class="none"><a href="tutorial.html">Tutorial</a></li></ul></li><li class="none"><a href="developerguide.html">Developer Guide</a></li></ul></div><div id="menuProject_Documentation"><h5>Project Documentation</h5><ul><li class="none"><a href="index.html">About</a></li><li class="collapsed"><a href="project-info.html">Project Info</a></li><li class="collapsed"><a href="maven-reports.html">Project Reports</a></li><li class="none"><a href="development-process.html">Development Process</a></li></ul></div><div id="legend"><h5>Legend</h5><ul><li class="externalLink">External Link</li><li class="newWindow">Opens in a new window</li></ul></div><a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="./images/logos/mavenlogo_builtby_w.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="Introduction"></a><h2>Introduction</h2>
<p>HttpClient supports three different types of http authentication schemes:
Basic, Digest and NTLM. These can be used to authenticate with http servers
or proxies.</p>
<div class="subsection"><a name="Contents"></a><h3>Contents</h3>
<ul>
<li>
<a href="#Server_Authentication">Server Authentication</a>
<ul>
<li><a href="#Preemptive_Authentication">Preemptive Authentication</a></li>
<li><a href="#Security_aspects_of_server_authentication">Security aspects of server authentication</a></li>
</ul>
</li>
<li><a href="#Proxy_Authentication">Proxy Authentication</a></li>
<li>
<a href="#Authentication_Schemes">Authentication Schemes</a>
<ul>
<li><a href="#Basic">Basic</a></li>
<li><a href="#Digest">Digest</a></li>
<li><a href="#NTLM">NTLM</a></li>
<li><a href="#Alternate_authentication">Alternate authentication</a></li>
<li><a href="#Custom_authentication_scheme">Custom authentication scheme</a></li>
</ul>
</li>
<li><a href="#Examples">Examples</a></li>
<li><a href="#Known_limitations_and_problems">Known limitations and problems</a></li>
<li><a href="#Troubleshooting">Troubleshooting</a></li>
</ul>
</div>
</div><div class="section"><a name="Server_Authentication"></a><h2>Server Authentication</h2>
<p>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 <code>setCredentials(AuthScope authscope,
Credentials cred)</code> and <code>getCredentials(AuthScope authscope)</code>
methods.</p>
<p>The automatic authorization built in to HttpClient can be disabled
with the method <code>setDoAuthentication(boolean doAuthentication)</code>
in the HttpMethod class. The change only affects that method instance.</p>
<div class="subsection"><a name="Preemptive_Authentication"></a><h3>Preemptive Authentication</h3>
<p>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:</p>
<div class="source"><pre>client.getParams().setAuthenticationPreemptive(true);</pre></div>
<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>
<div class="source"><pre>Credentials defaultcreds = new UsernamePasswordCredentials("username", "password");
client.getState().setCredentials(new AuthScope("myhost", 80, AuthScope.ANY_REALM), defaultcreds);</pre></div>
<p>The preemptive authentication in HttpClient conforms to rfc2617:</p>
<blockquote>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.</blockquote>
</div>
<div class="subsection"><a name="Security_aspects_of_server_authentication"></a><h3>Security aspects of server authentication</h3>
<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 AuthScope.ANY authentication scope (<code>null</code> value
for host and/or realm) 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>
<div class="source"><pre>// To be avoided unless in debug mode
Credentials defaultcreds = new UsernamePasswordCredentials("username", "password");
client.getState().setCredentials(AuthScope.ANY, defaultcreds);</pre></div>
</div>
</div><div class="section"><a name="Proxy_Authentication"></a><h2>Proxy Authentication</h2>
<p>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
<code>setProxyCredentials(AuthScope authscope, Credentials cred)</code> and
<code>getProxyCredentials(AuthScope authscope)</code>.</p>
</div><div class="section"><a name="Authentication_Schemes"></a><h2>Authentication Schemes</h2>
<p>The following authentication schemes are supported by HttpClient.</p>
<div class="subsection"><a name="Basic"></a><h3>Basic</h3>
<p>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.</p>
</div>
<div class="subsection"><a name="Digest"></a><h3>Digest</h3>
<p>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.</p>
<p>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.</p>
</div>
<div class="subsection"><a name="NTLM"></a><h3>NTLM</h3>
<p>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.</p>
<p>NTLM authentication requires an instance of NTCredentials be
available for the <i>domain name</i> 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.
Also note that the username provided to the NTCredentials should not
be prefixed with the domain - ie: "adrian" is correct whereas
"DOMAIN\adrian" is not correct.</p>
<p>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.</p>
<p>
<ol>
<li>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).</li>
<li>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.</li>
<li>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.</li>
</ol>
</p>
<p>For a detailed explanation of how NTLM authentication works, please see
<a href="http://davenport.sourceforge.net/ntlm.html" class="externalLink" title="External Link">
http://davenport.sourceforge.net/ntlm.html</a>.</p>
</div>
<div class="subsection"><a name="Alternate_authentication"></a><h3>Alternate authentication</h3>
<p>Some servers support multiple schemes for authenticating users.
Given that only one scheme may be used at a time for authenticating, HttpClient
must choose which scheme to use. To accompish this, HttpClient uses an order of
preference to select the correct authentication scheme. By default
this order is: NTLM, Digest, Basic.
</p>
<p>In certain cases it may be desirable to change this default. The
default preference of the authentication schemes may be altered using the
'http.auth.scheme-priority' parameter. The parameter value is expected to be a List
of Strings containing names of authentication schemes in descending order of
preference.
</p>
<div class="source"><pre>HttpClient client = new HttpClient();
List authPrefs = new ArrayList(2);
authPrefs.add(AuthPolicy.DIGEST);
authPrefs.add(AuthPolicy.BASIC);
// This will exclude the NTLM authentication scheme
client.getParams().setParameter(AuthPolicy.AUTH_SCHEME_PRIORITY, authPrefs);</pre></div>
</div>
<div class="subsection"><a name="Custom_authentication_scheme"></a><h3>Custom authentication scheme</h3>
<p>HttpClient natively supports basic, digest, and NTLM authentication. It also contains
a mechanism to plugin additional custom authentication schemes via the
<a href="apidocs/org/apache/commons/httpclient/auth/AuthScheme.html">AuthScheme</a> interface.
The following steps are required to make use of a custom authentication scheme.
<ol>
<li>Implement the <code>AuthScheme</code> interface.</li>
<li>Register the custom <code>AuthScheme</code> with <a href="apidocs/org/apache/commons/httpclient/auth/AuthPolicy.html#registerAuthScheme(java.lang.String,%20java.lang.Class)">
AuthPolicy.registerAuthScheme()</a>.</li>
<li>Include the custom <code>AuthScheme</code> in the AuthPolicy.AUTH_SCHEME_PRIORITY preference
(see the <a href="#Alternate_authentication">Alternate authentication</a> section).</li>
</ol>
</p>
</div>
</div><div class="section"><a name="Examples"></a><h2>Examples</h2>
<p>There are a number of authentication examples in the <a href="http://svn.apache.org/viewvc/jakarta/httpcomponents/oac.hc3x/trunk/src/examples/" class="externalLink" title="External Link">example directory</a>, including:
<ul>
<li><a href="http://svn.apache.org/viewvc/jakarta/httpcomponents/oac.hc3x/trunk/src/examples/BasicAuthenticationExample.java?view=markup" class="externalLink" title="External Link">Basic authentication</a></li>
<li><a href="http://svn.apache.org/viewvc/jakarta/httpcomponents/oac.hc3x/trunk/src/examples/CustomAuthenticationExample.java?view=markup" class="externalLink" title="External Link">Custom authentication</a></li>
<li><a href="http://svn.apache.org/viewvc/jakarta/httpcomponents/oac.hc3x/trunk/src/examples/InteractiveAuthenticationExample.java?view=markup" class="externalLink" title="External Link">Interactive authentication</a></li>
</ul>
</p>
</div><div class="section"><a name="Known_limitations_and_problems"></a><h2>Known limitations and problems</h2>
<ol>
<li>
<p>
<strong>Authentication schemes that rely on persistent connection state do not work on Sun's JVMs
below 1.4 if SSL is used</strong>
</p>
<p>
For details please refer to the <a href="sslguide.html#Known%20limitations%20and%20problems">Known
limitations and problems</a> section of the <a href="sslguide.html">SSL Guide</a>
</p>
<p>
<strong>Workaround:</strong> Disable stale connection check or upgrade to Java 1.4 or above.
</p>
</li>
<li>
<p>
<strong>Cannot authenticate with Microsoft IIS using NTLM authentication scheme</strong>
</p>
<p>
NT Lan Manager (NTLM) authentication is a proprietary, closed challenge/response authentication
protocol for Microsoft Windows. Only some details about NTLM protocol are available through
reverse engineering. HttpClient provides limited support for what is known as NTLMv1, the early
version of the NTLM protocol. HttpClient does not support NTLMv2 at all.
</p>
<p>
<strong>Workaround:</strong> Disable NTLMv2. For details refer to this Microsoft Support
<a href="http://support.microsoft.com/default.aspx?scid=KB;en-us;239869" class="externalLink" title="External Link">Article</a>
</p>
</li>
</ol>
</div><div class="section"><a name="Troubleshooting"></a><h2>Troubleshooting</h2>
<p>Some authentication schemes may use cryptographic algorithms. It is recommended to include the
<a href="http://java.sun.com/products/jce/" class="newWindow" title="New Window" target="_blank">Java Cryptography Extension</a> in
your runtime environment prior to JDK 1.4. Also note that you must register the JCE
implementation manually as HttpClient will not do so automatically. For instance to
register the Sun JCE implementation, you should execute the following code before attempting
to use HttpClient.
</p>
<div class="source"><pre>
String secProviderName = "com.sun.crypto.provider.SunJCE");
java.security.Provider secProvider =
(java.security.Provider)Class.forName(secProviderName).newInstance();
Security.addProvider(secProvider);
</pre></div>
</div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2001-2007, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>