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