heimdal/doc/standardisation/draft-brezak-spnego-http-01.txt

Kerberos working group                                         J.Brezak 
Internet Draft                                                Microsoft 
Document: draft-brezak-spnego-http-01.txt                                      
Category: Informational                                                 
                                                         September 2001 
 
 
           HTTP Authentication: SPNEGO Access Authentication 
 
 
Status of this Memo 
 
   This document is an Internet-Draft and is in full conformance with 
   all provisions of Section 10 of RFC2026 [1]. Internet-Drafts are 
   working documents of the Internet Engineering Task Force (IETF), its 
   areas, and its working groups. Note that other groups may also 
   distribute working documents as Internet-Drafts. Internet-Drafts are 
   draft documents valid for a maximum of six months and may be 
   updated, replaced, or obsoleted by other documents at any time. It 
   is inappropriate to use Internet- Drafts as reference material or to 
   cite them other than as "work in progress." 
     
   The list of current Internet-Drafts can be accessed at 
   http://www.ietf.org/ietf/1id-abstracts.txt  
    
   The list of Internet-Draft Shadow Directories can be accessed at 
   http://www.ietf.org/shadow.html. 
    
1. Abstract 
    
   This document describes how Microsoft's Internet Explorer 5.0 and 
   Internet Information Services 5.0 use Kerberos for security 
   enhancements of web transactions. The HTTP auth-scheme of 
   "negotiate" is defined here; when the negotiation results in the 
   selection of Kerberos, the security services of authentication and 
   optionally impersonation are performed. 
    
    
2. Conventions used in this document 
    
   In examples, "C:" and "S:" indicate lines sent by the client and 
   server respectively. 
    
   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 
   "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in 
   this document are to be interpreted as described in RFC-2119 [3]. 
    
    
3. Access Authentication 
    
3.1 Reliance on the HTTP/1.1 Specification 
 
   This specification is a companion to the HTTP/1.1 specification [4] 
   and builds on the authentication mechanisms defined in [5]. It uses 
  
Brezak                 Category - Informational                      1 








                     SPNEGO Access Authentication       September 2001 

   the augmented BNF section 2.1 of that document, and relies on both 
   the non-terminals defined in that document and other aspects of the 
   HTTP/1.1 specification. 
    
    
4. HTTP Negotiate Authentication Scheme 
    
   Use of Kerberos is wrapped in an HTTP auth-scheme of "Negotiate".  
   The auth-params exchanged use data formats defined for use with the 
   GSS-API [6].  In particular, they follow the formats set for the 
   SPNEGO [7] and Kerberos [8] "mechanisms" for GSSAPI.  The 
   "Negotiate" auth-scheme calls for the use of SPNEGO GSSAPI tokens 
   which the specific mechanism type specifies. 
    
4.1 The WWW-Authenticate Response Header 
    
   If the server receives a request for an access-protected object, and 
   an acceptable Authorization header is not sent, the server responds 
   with a "401 Unauthorized" status code, and a WWW-Authenticate header 
   as per the framework described in [4]. The negotiate scheme will 
   operate as follows: 
    
    
        challenge       = "Negotiate" auth-data 
        auth-data       = 1#( [gssapi-data] ) 
         
   The meanings of the values of the directives used above are as 
   follows: 
    
   gssapi-data 
        If the gss_accept_security_context return a token for the 
        client, this directive contains is the base64 encoding of an 
        InitialContextToken as defined in [6]. 
  
   A status code 200 response can also carry a WWW-Authenticate 
   response header containing the final leg of a authentication. Before 
   using the contents of the response, the gssapi-data should be 
   processed by gss_init_security_context to determine the state of the 
   security context. If this function indicates success, the response 
   can be used by the application. Otherwise an appropriate action 
   based on the authentication status should be. 
    
   For example the authentication could have failed on the final leg if 
   mutual authentication was requested and the server was not able to 
   prove its identity. In this case, the returned results are suspect. 
   It is not always possible to mutually authenticate the server before 
   the HTTP operation. POST methods are in this category. 
    
   When the Kerberos Version 5 GSSAPI mechanism [RFC-1964] is being 
   used, the HTTP server will be using a principal name of the form of 
   "http/<hostname>". 
    
4.2 The Authorization Request Header 
 
  
Brezak                 Category - Informational                      2 








                     SPNEGO Access Authentication       September 2001 

   The client is expected to retry the request, passing an 
   Authorization header line, which is defined according to the 
   framework described in [4] utilized as follow: 
    
        credentials             = "Negotiate" auth-data2 
        auth-data2              = 1#( gssapi-data ) 
                                 
   gssapi-data 
        This directive contains is the base64 encoding of an 
        InitialContextToken as defined in [6]. 
    
   If a directive or its value is improper, or required directives are 
   missing, the propose response is 400 Bad Request. If a 401 
   Unauthorized status code is returned, the contents of the WWW-
   Authenticate response header is used to continue the authentication 
   as long as the opaque value is the same. 
    
5. Negotiate Operation Example 
    
   The user is logged onto realm A.COM as user@A.COM. The web server is 
   in realm B using the principal http/server@B.COM. Realm B.COM trusts 
   Realm A.COM  
    
   The client requests an access-protected document from server via a 
   GET method request. The URI of the document is 
   "http://www.nowhere.org/dir/index.html". 
    
   The first time the client requests the document, no Authorization 
   header is sent, so the server responds with: 
    
        HTTP/1.1 401 Unauthorized 
        WWW-Authenticate: Negotiate 
         
   The client will obtain the user credentials using the SPNEGO GSSAPI 
   mechanism type to identify generate a GSSAPI message to be sent to 
   the server with a new request, including the following Authorization 
   header: 
    
        Authorization: Negotiate 
        2a87421000492ade0234568ac0289eca874209af8bc028 
         
   The server will decode the gssapi-data and pass this to the SPNEGO 
   GSSAPI mechanism in the gss_accept_security_context function. The 
   return value from the gss_accept_security_context function can 
   indicate the security context is complete and supply final 
   authentication data to be returned to the client. If the server has 
   more gssapi data to send to the client to complete the context it is 
   to be carried in WWW-Authenticate header with the final response. 
   The response will be sent to the client, including the following 
   header: 
    
        HTTP/1.1 200 Success 
        WWW-Authenticate: Negotiate ade0234568ac874209af8bc0280289eca 
         
  
Brezak                 Category - Informational