1 2 3Kerberos working group J.Brezak 4Internet Draft Microsoft 5Document: draft-brezak-spnego-http-02.txt 6Category: Informational 7 November 2001 8 9 10 HTTP Authentication: SPNEGO Access Authentication 11 12 13Status of this Memo 14 15 This document is an Internet-Draft and is in full conformance with 16 all provisions of Section 10 of RFC2026 [1]. Internet-Drafts are 17 working documents of the Internet Engineering Task Force (IETF), its 18 areas, and its working groups. Note that other groups may also 19 distribute working documents as Internet-Drafts. Internet-Drafts are 20 draft documents valid for a maximum of six months and may be 21 updated, replaced, or obsoleted by other documents at any time. It 22 is inappropriate to use Internet- Drafts as reference material or to 23 cite them other than as "work in progress." 24 25 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/ietf/1id-abstracts.txt 27 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html. 30 311. Abstract 32 33 This document describes how Microsoft's Internet Explorer (MSIE) and 34 Internet Information Services (IIS) incorporated in Windows 2000 use 35 Kerberos for security enhancements of web transactions. The HTTP 36 auth-scheme of "negotiate" is defined here; when the negotiation 37 results in the selection of Kerberos, the security services of 38 authentication and optionally impersonation are performed. 39 40 This document explains how HTTP authentication utilizes the SPNEGO 41 [7] GSSAPI mechanism. Details of SPNEGO implementation are not 42 provided in this document. 43 44 452. Conventions used in this document 46 47 In examples, "C:" and "S:" indicate lines sent by the client and 48 server respectively. 49 50 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 51 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in 52 this document are to be interpreted as described in RFC-2119 [3]. 53 54 553. Access Authentication 56 57 58Brezak Category - Informational 1 59 60 61 62 63 64 65 66 67 HTTP SPNEGO Access Authentication November 2001 68 693.1 Reliance on the HTTP/1.1 Specification 70 71 This specification is a companion to the HTTP/1.1 specification [4] 72 and builds on the authentication mechanisms defined in [5]. It uses 73 the augmented BNF section 2.1 of that document, and relies on both 74 the non-terminals defined in that document and other aspects of the 75 HTTP/1.1 specification. 76 77 784. HTTP Negotiate Authentication Scheme 79 80 Use of Kerberos is wrapped in an HTTP auth-scheme of "Negotiate". 81 The auth-params exchanged use data formats defined for use with the 82 GSS-API [6]. In particular, they follow the formats set for the 83 SPNEGO [7] and Kerberos [8] mechanisms for GSSAPI. The "Negotiate" 84 auth-scheme calls for the use of SPNEGO GSSAPI tokens which the 85 specific mechanism type specifies. 86 87 The current implementation of this protocol is limited to the use of 88 SPNEGO with the Kerberos and Microsoft NTLM protocols. 89 904.1 The WWW-Authenticate Response Header 91 92 If the server receives a request for an access-protected object, and 93 an acceptable Authorization header has not been sent, the server 94 responds with a "401 Unauthorized" status code, and a "WWW- 95 Authenticate:" header as per the framework described in [4]. The 96 initial WWW-Authenticate header will not carry any gssapi-data. 97 98 The negotiate scheme will operate as follows: 99 100 challenge = "Negotiate" auth-data 101 auth-data = 1#( [gssapi-data] ) 102 103 The meanings of the values of the directives used above are as 104 follows: 105 106 gssapi-data 107 If the gss_accept_security_context return a token for the 108 client, this directive contains the base64 encoding of an 109 InitialContextToken as defined in [6]. This is not present in 110 the initial response from the server. 111 112 A status code 200 status response can also carry a "WWW- 113 Authenticate" response header containing the final leg of an 114 authentication. In this case, the gssapi-data will be present. 115 Before using the contents of the response, the gssapi-data should be 116 processed by gss_init_security_context to determine the state of the 117 security context. If this function indicates success, the response 118 can be used by the application. Otherwise an appropriate action 119 based on the authentication status should be. 120 121 For example the authentication could have failed on the final leg if 122 mutual authentication was requested and the server was not able to 123 124Brezak Category - Informational 2 125 126 127 128 129 130 131 132 133 HTTP SPNEGO Access Authentication November 2001 134 135 prove its identity. In this case, the returned results are suspect. 136 It is not always possible to mutually authenticate the server before 137 the HTTP operation. POST methods are in this category. 138 139 When the Kerberos Version 5 GSSAPI mechanism [RFC-1964] is being 140 used, the HTTP server will be using a principal name of the form of 141 "http/<hostname>". 142 1434.2 The Authorization Request Header 144 145 Upon receipt of the response containing a "WWW-Authenticate" header 146 from the server, the client is expected to retry the HTTP request, 147 passing a HTTP "Authorization" header line. This is defined 148 according to the framework described in [4] utilized as follows: 149 150 credentials = "Negotiate" auth-data2 151 auth-data2 = 1#( gssapi-data ) 152 153 gssapi-data 154 This directive contains is the base64 encoding of an 155 InitialContextToken as defined in [6]. 156 157 Any returned code other than a success 2xx code represents an 158 authentication error. If a 401 containing a "WWW-Authenticate" 159 header with "Negotiate" and gssapi-data is returned from the server, 160 it is a continuation of the authentication request. 161 162 A client may initiate a connection to the server with an 163 "Authorization" header containing the initial token for the server. 164 This form will bypass the initial 401 error from the server when the 165 client knows that the server will accept the Negotiate HTTP 166 authentication type. 167 1685. Negotiate Operation Example 169 170 The client requests an access-protected document from server via a 171 GET method request. The URI of the document is 172 "http://www.nowhere.org/dir/index.html". 173 174 C: GET dir/index.html 175 176 The first time the client requests the document, no Authorization 177 header is sent, so the server responds with: 178 179 S: HTTP/1.1 401 Unauthorized 180 S: WWW-Authenticate: Negotiate 181 182 The client will obtain the user credentials using the SPNEGO GSSAPI 183 mechanism type to identify generate a GSSAPI message to be sent to 184 the server with a new request, including the following Authorization 185 header: 186 187 C: GET dir/index.html 188 C: Authorization: Negotiate a87421000492aa874209af8bc028 189 190Brezak Category - Informational 3 191 192 193 194 195 196 197 198 199 HTTP SPNEGO Access Authentication November 2001 200 201 202 The server will decode the gssapi-data and pass this to the SPNEGO 203 GSSAPI mechanism in the gss_accept_security_context function. If the 204 context is not complete, the server will respond with a 401 status 205 code with a WWW-Authenticate header containing the gssapi-data. 206 207 S: HTTP/1.1 401 Unauthorized 208 S: WWW-Authenticate: Negotiate 749efa7b23409c20b92356 209 210 The client will decode the gssapi-data and pass this into 211 gss_init_security_context and return the new gssapi-data to the 212 server. 213 214 C: GET dir/index.html 215 C: Authorization: Negotiate 89a8742aa8729a8b028 216 217 This cycle can continue until the security context is complete. 218 219 When the return value from the gss_accept_security_context function 220 indicates that the security context is complete, it may supply final 221 authentication data to be returned to the client. If the server has 222 more gssapi data to send to the client to complete the context it is 223 to be carried in WWW-Authenticate header with the final response 224 containing the HTTP body. 225 226 S: HTTP/1.1 200 Success 227 S: WWW-Authenticate: Negotiate ade0234568a4209af8bc0280289eca 228 229 The client will decode the gssapi-data and supply it to 230 gss_init_security_context using the context for this server. If the 231 status is successful from the final gss_init_security_context, the 232 response can be used by the application. 233 2347. Security Considerations 235 236 The SPNEGO HTTP authentication facility is only used to provide 237 authentication of a user to server. It provides no facilities for 238 protecting the HTTP headers or data including the Authorization and 239 WWW-Authenticate headers that are used to implement this mechanism. 240 241 This mechanism is not used for HTTP authentication to HTTP proxies. 242 243 If an HTTP proxy is used between the client and server, it must take 244 care to not share authenticated connections between different 245 authenticated clients to the same server. If this is not honored, 246 then the server can easily lose track of security context 247 associations. A proxy that correctly honors client to server 248 authentication integrity will supply the "Proxy-support: Session- 249 Based-Authentication" HTTP header to the client in HTTP responses 250 from the proxy. The client MUST NOT utilize the SPNEGO HTTP 251 authentication mechanism through a proxy unless the proxy supplies 252 this header with the "401 Unauthorized" response from the server. 253 254 255 256Brezak Category - Informational 4 257 258 259 260 261 262 263 264 265 HTTP SPNEGO Access Authentication November 2001 266 267 When using the SPNEGO HTTP authentication facility with client 268 supplied data such as PUT and POST, the authentication should be 269 complete between the client and server before sending the user data. 270 The return status from the gss_init_security_context will indicate 271 with the security context is complete. At this point the data can be 272 sent to the server. 273 274 2758. References 276 277 278 1 Bradner, S., "The Internet Standards Process -- Revision 3", BCP 279 9, RFC 2026, October 1996. 280 281 3 Bradner, S., "Key words for use in RFCs to Indicate Requirement 282 Levels", BCP 14, RFC 2119, March 1997 283 284 4 Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., 285 Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol -- 286 HTTP/1.1", RFC 2616, June 1999. 287 288 5 Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, 289 P., Luotonen, A., Stewart, L., "HTTP Authentication: Basic and 290 Digest Access Authentication", RFC 2617, June 1999. 291 292 6 Linn, J., "Generic Security Service Application Program Interface, 293 Version 2", RFC 2078, January 1997. 294 295 7 Baize, E., Pinkas, D., "The Simple and Protected GSS-API 296 Negotiation Mechanism", RFC 2478, December 1998. 297 298 8 Linn, J., "The Kerberos Version 5 GSS-API Mechanism", RFC 1964, 299 June 1996. 300 301 302 303 30410. Author's Addresses 305 306 John Brezak 307 Microsoft 308 One Microsoft Way 309 Redmond, Washington 310 Email: jbrezak@microsoft.com 311 312 313 314 315 316 317 318 319 320 321 322Brezak Category - Informational 5 323 324 325 326 327 328 329 330 331 HTTP SPNEGO Access Authentication November 2001 332 333 334Full Copyright Statement 335 336 Copyright (C) The Internet Society (2001). All Rights Reserved. 337 338 This document and translations of it may be copied and furnished to 339 others, and derivative works that comment on or otherwise explain it 340 or assist in its implementation may be prepared, copied, published 341 and distributed, in whole or in part, without restriction of any 342 kind, provided that the above copyright notice and this paragraph 343 are included on all such copies and derivative works. However, this 344 document itself may not be modified in any way, such as by removing 345 the copyright notice or references to the Internet Society or other 346 Internet organizations, except as needed for the purpose of 347 developing Internet standards in which case the procedures for 348 copyrights defined in the Internet Standards process must be 349 followed, or as required to translate it into languages other than 350 English. 351 352 The limited permissions granted above are perpetual and will not be 353 revoked by the Internet Society or its successors or assigns. 354 355 This document and the information contained herein is provided on an 356 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 357 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 358 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 359 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 360 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE." 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388Brezak Category - Informational 6 389 390 391 392 393 394 395 396