7 Network Working Group K. Jaganathan
8 Request for Comments: 4559 L. Zhu
9 Category: Informational J. Brezak
14 SPNEGO-based Kerberos and NTLM HTTP Authentication
20 This memo provides information for the Internet community. It does
21 not specify an Internet standard of any kind. Distribution of this
26 Copyright (C) The Internet Society (2006).
30 This document describes how the Microsoft Internet Explorer (MSIE)
31 and Internet Information Services (IIS) incorporated in Microsoft
32 Windows 2000 use Kerberos for security enhancements of web
33 transactions. The Hypertext Transport Protocol (HTTP) auth-scheme of
34 "negotiate" is defined here; when the negotiation results in the
35 selection of Kerberos, the security services of authentication and,
36 optionally, impersonation (the IIS server assumes the windows
37 identity of the principal that has been authenticated) are performed.
38 This document explains how HTTP authentication utilizes the Simple
39 and Protected GSS-API Negotiation mechanism. Details of Simple And
40 Protected Negotiate (SPNEGO) implementation are not provided in this
45 1. Introduction ....................................................2
46 2. Conventions Used in This Document ...............................2
47 3. Access Authentication ...........................................2
48 3.1. Reliance on the HTTP/1.1 Specification .....................2
49 4. HTTP Negotiate Authentication Scheme ............................2
50 4.1. The WWW-Authenticate Response Header .......................2
51 5. Negotiate Operation Example .....................................4
52 6. Security Considerations .........................................5
53 7. Normative References ............................................6
58 Jaganathan, et al. Informational [Page 1]
60 RFC 4559 HTTP Authentication in Microsoft Windows June 2006
65 Microsoft has provided support for Kerberos authentication in
66 Microsoft Internet Explorer (MSIE) and Internet Information Services
67 (IIS), in addition to other mechanisms. This provides the benefits
68 of the Kerberos v5 protocol for Web applications.
70 Support for Kerberos authentication is based on other previously
71 defined mechanisms, such as SPNEGO Simple And Protected Negotiate
72 (SPNEGO) [RFC4178] and the Generic Security Services Application
73 Program Interface(GSSAPI).
75 2. Conventions Used in This Document
77 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
78 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to
79 be interpreted as described in [RFC2119].
81 3. Access Authentication
83 3.1. Reliance on the HTTP/1.1 Specification
85 This specification is a companion to the HTTP/1.1 specification
86 [RFC2616], and it builds on the authentication mechanisms defined in
87 [RFC2617]. It uses the augmented BNF section of that document (2.1),
88 and it relies on both the non-terminals defined in that document and
89 other aspects of the HTTP/1.1 specification.
91 4. HTTP Negotiate Authentication Scheme
93 Use of Kerberos is wrapped in an HTTP auth-scheme of "Negotiate".
94 The auth-params exchanged use data formats defined for use with the
95 GSS-API [RFC2743]. In particular, they follow the formats set for
96 the SPNEGO [RFC4178] and Kerberos [RFC4121] mechanisms for GSSAPI.
97 The "Negotiate" auth-scheme calls for the use of SPNEGO GSSAPI tokens
98 that the specific mechanism type specifies.
100 The current implementation of this protocol is limited to the use of
101 SPNEGO with the Kerberos and Microsoft(NT Lan Manager) NTLM
104 4.1. The WWW-Authenticate Response Header
106 If the server receives a request for an access-protected object, and
107 if an acceptable Authorization header has not been sent, the server
108 responds with a "401 Unauthorized" status code, and a "WWW-
109 Authenticate:" header as per the framework described in [RFC2616].
110 The initial WWW-Authenticate header will not carry any gssapi-data.
114 Jaganathan, et al. Informational [Page 2]
116 RFC 4559 HTTP Authentication in Microsoft Windows June 2006
119 The negotiate scheme will operate as follows:
121 challenge = "Negotiate" auth-data
122 auth-data = 1#( [gssapi-data] )
124 The meanings of the values of the directives used above are as
129 If the gss_accept_security_context returns a token for the client,
130 this directive contains the base64 encoding of an
131 initialContextToken, as defined in [RFC2743]. This is not present in
132 the initial response from the server.
134 A status code 200 status response can also carry a "WWW-Authenticate"
135 response header containing the final leg of an authentication. In
136 this case, the gssapi-data will be present. Before using the
137 contents of the response, the gssapi-data should be processed by
138 gss_init_security_context to determine the state of the security
139 context. If this function indicates success, the response can be
140 used by the application. Otherwise, an appropriate action, based on
141 the authentication status, should be taken.
143 For example, the authentication could have failed on the final leg if
144 mutual authentication was requested and the server was not able to
145 prove its identity. In this case, the returned results are suspect.
146 It is not always possible to mutually authenticate the server before
147 the HTTP operation. POST methods are in this category.
149 When the Kerberos Version 5 GSSAPI mechanism [RFC4121] is being used,
150 the HTTP server will be using a principal name of the form of
153 4.2. The Authorization Request Header
155 Upon receipt of the response containing a "WWW-Authenticate" header
156 from the server, the client is expected to retry the HTTP request,
157 passing a HTTP "Authorization" header line. This is defined
158 according to the framework described in [RFC2616] and is utilized as
161 credentials = "Negotiate" auth-data2
162 auth-data2 = 1#( gssapi-data )
170 Jaganathan, et al. Informational [Page 3]
172 RFC 4559 HTTP Authentication in Microsoft Windows June 2006
175 This directive contains the base64 encoding of an
176 InitialContextToken, as defined in [RFC2743].
178 Any returned code other than a success 2xx code represents an
179 authentication error. If a 401 containing a "WWW-Authenticate"
180 header with "Negotiate" and gssapi-data is returned from the server,
181 it is a continuation of the authentication request.
183 A client may initiate a connection to the server with an
184 "Authorization" header containing the initial token for the server.
185 This form will bypass the initial 401 error from the server when the
186 client knows that the server will accept the Negotiate HTTP
189 5. Negotiate Operation Example
191 The client requests an access-protected document from server via a
192 GET method request. The URI of the document is
193 "http://www.nowhere.org/dir/index.html".
195 C: GET dir/index.html
197 The first time the client requests the document, no Authorization
198 header is sent, so the server responds with
200 S: HTTP/1.1 401 Unauthorized
201 S: WWW-Authenticate: Negotiate
203 The client will obtain the user credentials using the SPNEGO GSSAPI
204 mechanism type to identify generate a GSSAPI message to be sent to
205 the server with a new request, including the following Authorization
208 C: GET dir/index.html
209 C: Authorization: Negotiate a87421000492aa874209af8bc028
211 The server will decode the gssapi-data and pass this to the SPNEGO
212 GSSAPI mechanism in the gss_accept_security_context function. If the
213 context is not complete, the server will respond with a 401 status
214 code with a WWW-Authenticate header containing the gssapi-data.
216 S: HTTP/1.1 401 Unauthorized
217 S: WWW-Authenticate: Negotiate 749efa7b23409c20b92356
219 The client will decode the gssapi-data, pass this into
220 Gss_Init_security_context, and return the new gssapi-data to the
226 Jaganathan, et al. Informational [Page 4]
228 RFC 4559 HTTP Authentication in Microsoft Windows June 2006
231 C: GET dir/index.html
232 C: Authorization: Negotiate 89a8742aa8729a8b028
234 This cycle can continue until the security context is complete. When
235 the return value from the gss_accept_security_context function
236 indicates that the security context is complete, it may supply final
237 authentication data to be returned to the client. If the server has
238 more gssapi data to send to the client to complete the context, it is
239 to be carried in a WWW-Authenticate header with the final response
240 containing the HTTP body.
242 S: HTTP/1.1 200 Success
243 S: WWW-Authenticate: Negotiate ade0234568a4209af8bc0280289eca
245 The client will decode the gssapi-data and supply it to
246 gss_init_security_context using the context for this server. If the
247 status is successful from the final gss_init_security_context, the
248 response can be used by the application.
250 6. Security Considerations
252 The SPNEGO HTTP authentication facility is only used to provide
253 authentication of a user to a server. It provides no facilities for
254 protecting the HTTP headers or data including the Authorization and
255 WWW-Authenticate headers that are used to implement this mechanism.
257 Alternate mechanisms such as TLS can be used to provide
258 confidentiality. Hashes of the TLS certificates can be used as
259 channel bindings to secure the channel. In this case clients would
260 need to enforce that the channel binding information is valid. Note
261 that Kerb-TLS [RFC2712] could be used to provide both authentication
262 and confidentiality, but this requires a change to the TLS provider.
264 This mechanism is not used for HTTP authentication to HTTP proxies.
266 If an HTTP proxy is used between the client and server, it must take
267 care to not share authenticated connections between different
268 authenticated clients to the same server. If this is not honored,
269 then the server can easily lose track of security context
270 associations. A proxy that correctly honors client to server
271 authentication integrity will supply the "Proxy-support: Session-
272 Based-Authentication" HTTP header to the client in HTTP responses
273 from the proxy. The client MUST NOT utilize the SPNEGO HTTP
274 authentication mechanism through a proxy unless the proxy supplies
275 this header with the "401 Unauthorized" response from the server.
282 Jaganathan, et al. Informational [Page 5]
284 RFC 4559 HTTP Authentication in Microsoft Windows June 2006
287 When using the SPNEGO HTTP authentication facility with client-
288 supplied data such as PUT and POST, the authentication should be
289 complete between the client and server before sending the user data.
290 The return status from the gss_init_security_context will indicate
291 that the security context is complete. At this point, the data can
292 be sent to the server.
294 7. Normative References
296 [RFC2743] Linn, J., "Generic Security Service Application Program
297 Interface Version 2", 2, Update 1", 2743, January 2000.
299 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
300 Requirement Levels", BCP 14, RFC 2119, March 1997.
302 [RFC4178] Zhu, L., Leach, P., Jaganathan, K., and W. Ingersoll, "The
303 Simple and Protected GSS-API Generic Security Service
304 Application Program Interface (GSS-API) Negotiation
305 Mechanism", 4178, October 2005.
307 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
308 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
309 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
311 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S.,
312 Leach, P., Luotonen, A., and L. Stewart, "HTTP
313 Authentication: Basic and Digest Access Authentication",
316 [RFC2712] Medvinsky, A. and M. Hur, "Addition of Kerberos Cipher
317 Suites to Transport Layer Security (TLS)", RFC 2712,
320 [RFC4121] Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos
321 Version 5 Generic Security Service Application Program
322 Interface (GSS-API) Mechanism: Version 2", RFC 4121, July
338 Jaganathan, et al. Informational [Page 6]
340 RFC 4559 HTTP Authentication in Microsoft Windows June 2006
346 Microsoft Corporation
351 EMail: karthikj@microsoft.com
355 Microsoft Corporation
360 EMail: lzhu@microsoft.com
364 Microsoft Corporation
369 EMail: jbrezak@microsoft.com
394 Jaganathan, et al. Informational [Page 7]
396 RFC 4559 HTTP Authentication in Microsoft Windows June 2006
399 Full Copyright Statement
401 Copyright (C) The Internet Society (2006).
403 This document is subject to the rights, licenses and restrictions
404 contained in BCP 78 and at www.rfc-editor.org/copyright.html, and
405 except as set forth therein, the authors retain all their rights.
407 This document and the information contained herein are provided on an
408 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
409 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
410 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
411 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
412 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
413 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
415 Intellectual Property
417 The IETF takes no position regarding the validity or scope of any
418 Intellectual Property Rights or other rights that might be claimed to
419 pertain to the implementation or use of the technology described in
420 this document or the extent to which any license under such rights
421 might or might not be available; nor does it represent that it has
422 made any independent effort to identify any such rights. Information
423 on the procedures with respect to rights in RFC documents can be
424 found in BCP 78 and BCP 79.
426 Copies of IPR disclosures made to the IETF Secretariat and any
427 assurances of licenses to be made available, or the result of an
428 attempt made to obtain a general license or permission for the use of
429 such proprietary rights by implementers or users of this
430 specification can be obtained from the IETF on-line IPR repository at
431 http://www.ietf.org/ipr.
433 The IETF invites any interested party to bring to its attention any
434 copyrights, patents or patent applications, or other proprietary
435 rights that may cover technology that may be required to implement
436 this standard. Please address the information to the IETF at
441 Funding for the RFC Editor function is provided by the IETF
442 Administrative Support Activity (IASA).
450 Jaganathan, et al. Informational [Page 8]