third_party/heimdal/doc/standardisation/draft-brezak-spnego-http-02.txt

   1
   2
   3 Kerberos working group                                         J.Brezak
   4 Internet Draft                                                Microsoft
   5 Document: draft-brezak-spnego-http-02.txt
   6 Category: Informational
   7                                                           November 2001
   8
   9
  10            HTTP Authentication: SPNEGO Access Authentication
  11
  12
  13 Status 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
  31 1. 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
  45 2. 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
  55 3. Access Authentication
  56
  57
  58 Brezak                 Category - Informational                      1
  59
  60
  61
  62
  63
  64
  65
  66
  67                   HTTP SPNEGO Access Authentication     November 2001
  68
  69 3.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
  78 4. 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
  90 4.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
 124 Brezak                 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
 143 4.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
 168 5. 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
 190 Brezak                 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
 234 7. 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
 256 Brezak                 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
 275 8. 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
 304 10. 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
 322 Brezak                 Category - Informational                      5
 323
 324
 325
 326
 327
 328
 329
 330
 331                   HTTP SPNEGO Access Authentication     November 2001
 332
 333
 334 Full 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
 388 Brezak                 Category - Informational                      6
 389
 390
 391
 392
 393
 394
 395