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