| blob | 9f75bbbf442728dfdfadb9d6c5b45ba0336f59b9 |
4 Kerberos working group J.Brezak
5 Internet Draft Microsoft
6 Document: draft-brezak-spnego-http-04.txt
7 Category: Informational
8 October 2002
11 HTTP Authentication: SPNEGO Access Authentication
12 As implemented in Microsoft Windows 2000
15 Status of this Memo
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."
27 The list of current Internet-Drafts can be accessed at
28 http://www.ietf.org/ietf/1id-abstracts.txt
30 The list of Internet-Draft Shadow Directories can be accessed at
31 http://www.ietf.org/shadow.html.
33 1. Abstract
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.
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.
48 2. Conventions used in this document
50 In examples, "C:" and "S:" indicate lines sent by the client and
51 server respectively.
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].
59 Brezak Category - Informational 1 \f
60 HTTP SPNEGO Access Authentication October 2002
62 3. Access Authentication
64 3.1 Reliance on the HTTP/1.1 Specification
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.
73 4. HTTP Negotiate Authentication Scheme
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.
82 The current implementation of this protocol is limited to the use of
83 SPNEGO with the Kerberos and Microsoft NTLM protocols.
85 4.1 The WWW-Authenticate Response Header
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.
93 The negotiate scheme will operate as follows:
95 challenge = "Negotiate" auth-data
96 auth-data = 1#( [gssapi-data] )
98 The meanings of the values of the directives used above are as
99 follows:
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.
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.
117 Brezak Category - Informational 2 \f
118 HTTP SPNEGO Access Authentication October 2002
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.
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>".
130 4.2 The Authorization Request Header
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:
137 credentials = "Negotiate" auth-data2
138 auth-data2 = 1#( gssapi-data )
140 gssapi-data
141 This directive contains is the base64 encoding of an
142 InitialContextToken as defined in [6].
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.
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.
155 5. Negotiate Operation Example
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".
161 C: GET dir/index.html
163 The first time the client requests the document, no Authorization
164 header is sent, so the server responds with:
166 S: HTTP/1.1 401 Unauthorized
167 S: WWW-Authenticate: Negotiate
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:
175 Brezak Category - Informational 3 \f
176 HTTP SPNEGO Access Authentication October 2002
178 C: GET dir/index.html
179 C: Authorization: Negotiate a87421000492aa874209af8bc028
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.
186 S: HTTP/1.1 401 Unauthorized
187 S: WWW-Authenticate: Negotiate 749efa7b23409c20b92356
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.
193 C: GET dir/index.html
194 C: Authorization: Negotiate 89a8742aa8729a8b028
196 This cycle can continue until the security context is complete.
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.
205 S: HTTP/1.1 200 Success
206 S: WWW-Authenticate: Negotiate ade0234568a4209af8bc0280289eca
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.
213 7. Security Considerations
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.
220 This mechanism is not used for HTTP authentication to HTTP proxies.
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.
233 Brezak Category - Informational 4 \f
234 HTTP SPNEGO Access Authentication October 2002
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.
245 8. References
248 1 Bradner, S., "The Internet Standards Process -- Revision 3", BCP
249 9, RFC 2026, October 1996.
251 3 Bradner, S., "Key words for use in RFCs to Indicate Requirement
252 Levels", BCP 14, RFC 2119, March 1997
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.
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.
262 6 Linn, J., "Generic Security Service Application Program Interface,
263 Version 2", RFC 2078, January 1997.
265 7 Baize, E., Pinkas, D., "The Simple and Protected GSS-API
266 Negotiation Mechanism", RFC 2478, December 1998.
268 8 Linn, J., "The Kerberos Version 5 GSS-API Mechanism", RFC 1964,
269 June 1996.
274 10. Author's Addresses
276 John Brezak
277 Microsoft
278 One Microsoft Way
279 Redmond, Washington
280 Email: jbrezak@microsoft.com
291 Brezak Category - Informational 5 \f
292 HTTP SPNEGO Access Authentication October 2002
295 Full Copyright Statement
297 Copyright (C) The Internet Society (2001). All Rights Reserved.
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.
313 The limited permissions granted above are perpetual and will not be
314 revoked by the Internet Society or its successors or assigns.
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."
349 Brezak Category - Informational 6 \f