1 2 3 4 5 6 7Network Working Group K. Jaganathan 8Request for Comments: 4559 L. Zhu 9Category: Informational J. Brezak 10 Microsoft Corporation 11 June 2006 12 13 14 SPNEGO-based Kerberos and NTLM HTTP Authentication 15 in Microsoft Windows 16 17 18Status of This Memo 19 20 This memo provides information for the Internet community. It does 21 not specify an Internet standard of any kind. Distribution of this 22 memo is unlimited. 23 24Copyright Notice 25 26 Copyright (C) The Internet Society (2006). 27 28Abstract 29 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 41 document. 42 43Table of Contents 44 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 54 55 56 57 58Jaganathan, et al. Informational [Page 1] 59 60RFC 4559 HTTP Authentication in Microsoft Windows June 2006 61 62 631. Introduction 64 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. 69 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). 74 752. Conventions Used in This Document 76 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]. 80 813. Access Authentication 82 833.1. Reliance on the HTTP/1.1 Specification 84 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. 90 914. HTTP Negotiate Authentication Scheme 92 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. 99 100 The current implementation of this protocol is limited to the use of 101 SPNEGO with the Kerberos and Microsoft(NT Lan Manager) NTLM 102 protocols. 103 1044.1. The WWW-Authenticate Response Header 105 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. 111 112 113 114Jaganathan, et al. Informational [Page 2] 115 116RFC 4559 HTTP Authentication in Microsoft Windows June 2006 117 118 119 The negotiate scheme will operate as follows: 120 121 challenge = "Negotiate" auth-data 122 auth-data = 1#( [gssapi-data] ) 123 124 The meanings of the values of the directives used above are as 125 follows: 126 127 gssapi-data 128 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. 133 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. 142 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. 148 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 151 "HTTP/hostname". 152 1534.2. The Authorization Request Header 154 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 159 follows: 160 161 credentials = "Negotiate" auth-data2 162 auth-data2 = 1#( gssapi-data ) 163 164 gssapi-data 165 166 167 168 169 170Jaganathan, et al. Informational [Page 3] 171 172RFC 4559 HTTP Authentication in Microsoft Windows June 2006 173 174 175 This directive contains the base64 encoding of an 176 InitialContextToken, as defined in [RFC2743]. 177 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. 182 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 187 authentication type. 188 1895. Negotiate Operation Example 190 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". 194 195 C: GET dir/index.html 196 197 The first time the client requests the document, no Authorization 198 header is sent, so the server responds with 199 200 S: HTTP/1.1 401 Unauthorized 201 S: WWW-Authenticate: Negotiate 202 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 206 header: 207 208 C: GET dir/index.html 209 C: Authorization: Negotiate a87421000492aa874209af8bc028 210 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. 215 216 S: HTTP/1.1 401 Unauthorized 217 S: WWW-Authenticate: Negotiate 749efa7b23409c20b92356 218 219 The client will decode the gssapi-data, pass this into 220 Gss_Init_security_context, and return the new gssapi-data to the 221 server. 222 223 224 225 226Jaganathan, et al. Informational [Page 4] 227 228RFC 4559 HTTP Authentication in Microsoft Windows June 2006 229 230 231 C: GET dir/index.html 232 C: Authorization: Negotiate 89a8742aa8729a8b028 233 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. 241 242 S: HTTP/1.1 200 Success 243 S: WWW-Authenticate: Negotiate ade0234568a4209af8bc0280289eca 244 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. 249 2506. Security Considerations 251 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. 256 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. 263 264 This mechanism is not used for HTTP authentication to HTTP proxies. 265 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. 276 277 278 279 280 281 282Jaganathan, et al. Informational [Page 5] 283 284RFC 4559 HTTP Authentication in Microsoft Windows June 2006 285 286 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. 293 2947. Normative References 295 296 [RFC2743] Linn, J., "Generic Security Service Application Program 297 Interface Version 2", 2, Update 1", 2743, January 2000. 298 299 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 300 Requirement Levels", BCP 14, RFC 2119, March 1997. 301 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. 306 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. 310 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", 314 RFC 2617, June 1999. 315 316 [RFC2712] Medvinsky, A. and M. Hur, "Addition of Kerberos Cipher 317 Suites to Transport Layer Security (TLS)", RFC 2712, 318 October 1999. 319 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 323 2005. 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338Jaganathan, et al. Informational [Page 6] 339 340RFC 4559 HTTP Authentication in Microsoft Windows June 2006 341 342 343Authors' Addresses 344 345 Karthik Jaganathan 346 Microsoft Corporation 347 One Microsoft Way 348 Redmond, WA 98052 349 US 350 351 EMail: karthikj@microsoft.com 352 353 354 Larry Zhu 355 Microsoft Corporation 356 One Microsoft Way 357 Redmond, WA 98052 358 US 359 360 EMail: lzhu@microsoft.com 361 362 363 John Brezak 364 Microsoft Corporation 365 One Microsoft Way 366 Redmond, WA 98052 367 US 368 369 EMail: jbrezak@microsoft.com 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394Jaganathan, et al. Informational [Page 7] 395 396RFC 4559 HTTP Authentication in Microsoft Windows June 2006 397 398 399Full Copyright Statement 400 401 Copyright (C) The Internet Society (2006). 402 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. 406 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. 414 415Intellectual Property 416 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. 425 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. 432 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 437 ietf-ipr@ietf.org. 438 439Acknowledgement 440 441 Funding for the RFC Editor function is provided by the IETF 442 Administrative Support Activity (IASA). 443 444 445 446 447 448 449 450Jaganathan, et al. Informational [Page 8] 451 452