doc/standardisation/draft-brezak-kerberos-http-00.txt

   1
   2                                                                J.Brezak
   3 Internet Draft                                                Microsoft
   4 Document: draft-brezak-kerberos-http-00.txt
   5 Category: 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
  13 Status 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
  32 1. 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
  47 2. 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
  57 Brezak                 Category - Informational                      1 \f
  58                  HTTP Kerberos Access Authentication    November 2003
  59
  60 3. 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
  68 3. Access Authentication
  69
  70 3.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
  79 4. 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
  92 4.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
 115 Brezak                 Category - Informational                      2 \f
 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
 137 4.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
 162 5. 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
 173 Brezak                 Category - Informational                      3 \f
 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
 220 7. 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
 231 Brezak                 Category - Informational                      4 \f
 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
 253 8. References
 254
 255
 256
 257 10. 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
 289 Brezak                 Category - Informational                      5 \f
 290                  HTTP Kerberos Access Authentication    November 2003
 291
 292
 293 Full 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
 347 Brezak                 Category - Informational                      6 \f