doc/standardisation/rfc4559.txt

   1
   2
   3
   4
   5
   6
   7 Network Working Group                                      K. Jaganathan
   8 Request for Comments: 4559                                        L. Zhu
   9 Category: Informational                                        J. Brezak
  10                                                    Microsoft Corporation
  11                                                                June 2006
  12
  13
  14            SPNEGO-based Kerberos and NTLM HTTP Authentication
  15                           in Microsoft Windows
  16
  17
  18 Status of This Memo
  19
  20    This memo provides information for the Internet community.  It does
  21    not specify an Internet standard of any kind.  Distribution of this
  22    memo is unlimited.
  23
  24 Copyright Notice
  25
  26    Copyright (C) The Internet Society (2006).
  27
  28 Abstract
  29
  30    This document describes how the Microsoft Internet Explorer (MSIE)
  31    and Internet Information Services (IIS) incorporated in Microsoft
  32    Windows 2000 use Kerberos for security enhancements of web
  33    transactions.  The Hypertext Transport Protocol (HTTP) auth-scheme of
  34    "negotiate" is defined here; when the negotiation results in the
  35    selection of Kerberos, the security services of authentication and,
  36    optionally, impersonation (the IIS server assumes the windows
  37    identity of the principal that has been authenticated) are performed.
  38    This document explains how HTTP authentication utilizes the Simple
  39    and Protected GSS-API Negotiation mechanism.  Details of Simple And
  40    Protected Negotiate (SPNEGO) implementation are not provided in this
  41    document.
  42
  43 Table of Contents
  44
  45    1. Introduction ....................................................2
  46    2. Conventions Used in This Document ...............................2
  47    3. Access Authentication ...........................................2
  48       3.1. Reliance on the HTTP/1.1 Specification .....................2
  49    4. HTTP Negotiate Authentication Scheme ............................2
  50       4.1. The WWW-Authenticate Response Header .......................2
  51    5. Negotiate Operation Example .....................................4
  52    6. Security Considerations .........................................5
  53    7. Normative References ............................................6
  54
  55
  56
  57
  58 Jaganathan, et al.           Informational                      [Page 1]
  59 \f
  60 RFC 4559        HTTP Authentication in Microsoft Windows       June 2006
  61
  62
  63 1.  Introduction
  64
  65    Microsoft has provided support for Kerberos authentication in
  66    Microsoft Internet Explorer (MSIE) and Internet Information Services
  67    (IIS), in addition to other mechanisms.  This provides the benefits
  68    of the Kerberos v5 protocol for Web applications.
  69
  70    Support for Kerberos authentication is based on other previously
  71    defined mechanisms, such as SPNEGO Simple And Protected Negotiate
  72    (SPNEGO) [RFC4178] and the Generic Security Services Application
  73    Program Interface(GSSAPI).
  74
  75 2.  Conventions Used in This Document
  76
  77    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
  78    "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to
  79    be interpreted as described in [RFC2119].
  80
  81 3.  Access Authentication
  82
  83 3.1.  Reliance on the HTTP/1.1 Specification
  84
  85    This specification is a companion to the HTTP/1.1 specification
  86    [RFC2616], and it builds on the authentication mechanisms defined in
  87    [RFC2617].  It uses the augmented BNF section of that document (2.1),
  88    and it relies on both the non-terminals defined in that document and
  89    other aspects of the HTTP/1.1 specification.
  90
  91 4.  HTTP Negotiate Authentication Scheme
  92
  93    Use of Kerberos is wrapped in an HTTP auth-scheme of "Negotiate".
  94    The auth-params exchanged use data formats defined for use with the
  95    GSS-API [RFC2743].  In particular, they follow the formats set for
  96    the SPNEGO [RFC4178] and Kerberos [RFC4121] mechanisms for GSSAPI.
  97    The "Negotiate" auth-scheme calls for the use of SPNEGO GSSAPI tokens
  98    that the specific mechanism type specifies.
  99
 100    The current implementation of this protocol is limited to the use of
 101    SPNEGO with the Kerberos and Microsoft(NT Lan Manager) NTLM
 102    protocols.
 103
 104 4.1.  The WWW-Authenticate Response Header
 105
 106    If the server receives a request for an access-protected object, and
 107    if an acceptable Authorization header has not been sent, the server
 108    responds with a "401 Unauthorized" status code, and a "WWW-
 109    Authenticate:" header as per the framework described in [RFC2616].
 110    The initial WWW-Authenticate header will not carry any gssapi-data.
 111
 112
 113
 114 Jaganathan, et al.           Informational                      [Page 2]
 115 \f
 116 RFC 4559        HTTP Authentication in Microsoft Windows       June 2006
 117
 118
 119    The negotiate scheme will operate as follows:
 120
 121            challenge       = "Negotiate" auth-data
 122            auth-data       = 1#( [gssapi-data] )
 123
 124    The meanings of the values of the directives used above are as
 125    follows:
 126
 127    gssapi-data
 128
 129    If the gss_accept_security_context returns a token for the client,
 130    this directive contains the base64 encoding of an
 131    initialContextToken, as defined in [RFC2743].  This is not present in
 132    the initial response from the server.
 133
 134    A status code 200 status response can also carry a "WWW-Authenticate"
 135    response header containing the final leg of an authentication.  In
 136    this case, the gssapi-data will be present.  Before using the
 137    contents of the response, the gssapi-data should be processed by
 138    gss_init_security_context to determine the state of the security
 139    context.  If this function indicates success, the response can be
 140    used by the application.  Otherwise, an appropriate action, based on
 141    the authentication status, should be taken.
 142
 143    For example, the authentication could have failed on the final leg if
 144    mutual authentication was requested and the server was not able to
 145    prove its identity.  In this case, the returned results are suspect.
 146    It is not always possible to mutually authenticate the server before
 147    the HTTP operation.  POST methods are in this category.
 148
 149    When the Kerberos Version 5 GSSAPI mechanism [RFC4121] is being used,
 150    the HTTP server will be using a principal name of the form of
 151    "HTTP/hostname".
 152
 153 4.2.  The Authorization Request Header
 154
 155    Upon receipt of the response containing a "WWW-Authenticate" header
 156    from the server, the client is expected to retry the HTTP request,
 157    passing a HTTP "Authorization" header line.  This is defined
 158    according to the framework described in [RFC2616] and is utilized as
 159    follows:
 160
 161            credentials             = "Negotiate" auth-data2
 162            auth-data2              = 1#( gssapi-data )
 163
 164    gssapi-data
 165
 166
 167
 168
 169
 170 Jaganathan, et al.           Informational                      [Page 3]
 171 \f
 172 RFC 4559        HTTP Authentication in Microsoft Windows       June 2006
 173
 174
 175    This directive contains the base64 encoding of an
 176    InitialContextToken, as defined in [RFC2743].
 177
 178    Any returned code other than a success 2xx code represents an
 179    authentication error.  If a 401 containing a "WWW-Authenticate"
 180    header with "Negotiate" and gssapi-data is returned from the server,
 181    it is a continuation of the authentication request.
 182
 183    A client may initiate a connection to the server with an
 184    "Authorization" header containing the initial token for the server.
 185    This form will bypass the initial 401 error from the server when the
 186    client knows that the server will accept the Negotiate HTTP
 187    authentication type.
 188
 189 5.  Negotiate Operation Example
 190
 191    The client requests an access-protected document from server via a
 192    GET method request.  The URI of the document is
 193    "http://www.nowhere.org/dir/index.html".
 194
 195            C: GET dir/index.html
 196
 197    The first time the client requests the document, no Authorization
 198    header is sent, so the server responds with
 199
 200            S: HTTP/1.1 401 Unauthorized
 201            S: WWW-Authenticate: Negotiate
 202
 203    The client will obtain the user credentials using the SPNEGO GSSAPI
 204    mechanism type to identify generate a GSSAPI message to be sent to
 205    the server with a new request, including the following Authorization
 206    header:
 207
 208            C: GET dir/index.html
 209            C: Authorization: Negotiate a87421000492aa874209af8bc028
 210
 211    The server will decode the gssapi-data and pass this to the SPNEGO
 212    GSSAPI mechanism in the gss_accept_security_context function.  If the
 213    context is not complete, the server will respond with a 401 status
 214    code with a WWW-Authenticate header containing the gssapi-data.
 215
 216            S: HTTP/1.1 401 Unauthorized
 217            S: WWW-Authenticate: Negotiate 749efa7b23409c20b92356
 218
 219    The client will decode the gssapi-data, pass this into
 220    Gss_Init_security_context, and return the new gssapi-data to the
 221    server.
 222
 223
 224
 225
 226 Jaganathan, et al.           Informational                      [Page 4]
 227 \f
 228 RFC 4559        HTTP Authentication in Microsoft Windows       June 2006
 229
 230
 231            C: GET dir/index.html
 232            C: Authorization: Negotiate 89a8742aa8729a8b028
 233
 234    This cycle can continue until the security context is complete.  When
 235    the return value from the gss_accept_security_context function
 236    indicates that the security context is complete, it may supply final
 237    authentication data to be returned to the client.  If the server has
 238    more gssapi data to send to the client to complete the context, it is
 239    to be carried in a WWW-Authenticate header with the final response
 240    containing the HTTP body.
 241
 242            S: HTTP/1.1 200 Success
 243            S: WWW-Authenticate: Negotiate ade0234568a4209af8bc0280289eca
 244
 245    The client will decode the gssapi-data and supply it to
 246    gss_init_security_context using the context for this server.  If the
 247    status is successful from the final gss_init_security_context, the
 248    response can be used by the application.
 249
 250 6.  Security Considerations
 251
 252    The SPNEGO HTTP authentication facility is only used to provide
 253    authentication of a user to a server.  It provides no facilities for
 254    protecting the HTTP headers or data including the Authorization and
 255    WWW-Authenticate headers that are used to implement this mechanism.
 256
 257    Alternate mechanisms such as TLS can be used to provide
 258    confidentiality.  Hashes of the TLS certificates can be used as
 259    channel bindings to secure the channel.  In this case clients would
 260    need to enforce that the channel binding information is valid.  Note
 261    that Kerb-TLS [RFC2712] could be used to provide both authentication
 262    and confidentiality, but this requires a change to the TLS provider.
 263
 264    This mechanism is not used for HTTP authentication to HTTP proxies.
 265
 266    If an HTTP proxy is used between the client and server, it must take
 267    care to not share authenticated connections between different
 268    authenticated clients to the same server.  If this is not honored,
 269    then the server can easily lose track of security context
 270    associations.  A proxy that correctly honors client to server
 271    authentication integrity will supply the "Proxy-support:  Session-
 272    Based-Authentication" HTTP header to the client in HTTP responses
 273    from the proxy.  The client MUST NOT utilize the SPNEGO HTTP
 274    authentication mechanism through a proxy unless the proxy supplies
 275    this header with the "401 Unauthorized" response from the server.
 276
 277
 278
 279
 280
 281
 282 Jaganathan, et al.           Informational                      [Page 5]
 283 \f
 284 RFC 4559        HTTP Authentication in Microsoft Windows       June 2006
 285
 286
 287    When using the SPNEGO HTTP authentication facility with client-
 288    supplied data such as PUT and POST, the authentication should be
 289    complete between the client and server before sending the user data.
 290    The return status from the gss_init_security_context will indicate
 291    that the security context is complete.  At this point, the data can
 292    be sent to the server.
 293
 294 7.  Normative References
 295
 296    [RFC2743]  Linn, J., "Generic Security Service Application Program
 297               Interface Version 2", 2, Update 1", 2743, January 2000.
 298
 299    [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
 300               Requirement Levels", BCP 14, RFC 2119, March 1997.
 301
 302    [RFC4178] Zhu, L., Leach, P., Jaganathan, K., and W. Ingersoll, "The
 303               Simple and Protected GSS-API Generic Security Service
 304               Application Program Interface (GSS-API) Negotiation
 305               Mechanism", 4178, October 2005.
 306
 307    [RFC2616]  Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
 308               Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
 309               Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
 310
 311    [RFC2617]  Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S.,
 312               Leach, P., Luotonen, A., and L. Stewart, "HTTP
 313               Authentication: Basic and Digest Access Authentication",
 314               RFC 2617, June 1999.
 315
 316    [RFC2712]  Medvinsky, A. and M. Hur, "Addition of Kerberos Cipher
 317               Suites to Transport Layer Security (TLS)", RFC 2712,
 318               October 1999.
 319
 320    [RFC4121]  Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos
 321               Version 5 Generic Security Service Application Program
 322               Interface (GSS-API) Mechanism: Version 2", RFC 4121, July
 323               2005.
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338 Jaganathan, et al.           Informational                      [Page 6]
 339 \f
 340 RFC 4559        HTTP Authentication in Microsoft Windows       June 2006
 341
 342
 343 Authors' Addresses
 344
 345    Karthik Jaganathan
 346    Microsoft Corporation
 347    One Microsoft Way
 348    Redmond, WA  98052
 349    US
 350
 351    EMail: karthikj@microsoft.com
 352
 353
 354    Larry Zhu
 355    Microsoft Corporation
 356    One Microsoft Way
 357    Redmond, WA  98052
 358    US
 359
 360    EMail: lzhu@microsoft.com
 361
 362
 363    John Brezak
 364    Microsoft Corporation
 365    One Microsoft Way
 366    Redmond, WA  98052
 367    US
 368
 369    EMail: jbrezak@microsoft.com
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394 Jaganathan, et al.           Informational                      [Page 7]
 395 \f
 396 RFC 4559        HTTP Authentication in Microsoft Windows       June 2006
 397
 398
 399 Full Copyright Statement
 400
 401    Copyright (C) The Internet Society (2006).
 402
 403    This document is subject to the rights, licenses and restrictions
 404    contained in BCP 78 and at www.rfc-editor.org/copyright.html, and
 405    except as set forth therein, the authors retain all their rights.
 406
 407    This document and the information contained herein are provided on an
 408    "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
 409    OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
 410    ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
 411    INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
 412    INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
 413    WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
 414
 415 Intellectual Property
 416
 417    The IETF takes no position regarding the validity or scope of any
 418    Intellectual Property Rights or other rights that might be claimed to
 419    pertain to the implementation or use of the technology described in
 420    this document or the extent to which any license under such rights
 421    might or might not be available; nor does it represent that it has
 422    made any independent effort to identify any such rights.  Information
 423    on the procedures with respect to rights in RFC documents can be
 424    found in BCP 78 and BCP 79.
 425
 426    Copies of IPR disclosures made to the IETF Secretariat and any
 427    assurances of licenses to be made available, or the result of an
 428    attempt made to obtain a general license or permission for the use of
 429    such proprietary rights by implementers or users of this
 430    specification can be obtained from the IETF on-line IPR repository at
 431    http://www.ietf.org/ipr.
 432
 433    The IETF invites any interested party to bring to its attention any
 434    copyrights, patents or patent applications, or other proprietary
 435    rights that may cover technology that may be required to implement
 436    this standard.  Please address the information to the IETF at
 437    ietf-ipr@ietf.org.
 438
 439 Acknowledgement
 440
 441    Funding for the RFC Editor function is provided by the IETF
 442    Administrative Support Activity (IASA).
 443
 444
 445
 446
 447
 448
 449
 450 Jaganathan, et al.           Informational                      [Page 8]
 451 \f