GSSAPI authentication for HTTP

The GSS mechanism is an authentication mechanism for based on a multi-roundrip handshake using base64-encoded GSS-API tokens encoded in the WWW-Authenticate Response Header and the Authorization Request Header. An important difference from is that multiple roundtrips are supported which means that the server can be authenticated to the client (aka mutual authentication).

Both the Authorization and the WWW-Authenticate headers use the same syntax throughout the handshake (cf below for details on the protocol flow) specified by this Augmented BNF following and :

challenge = auth-scheme 1*SP 1#auth-param auth-scheme = "GSS" auth-param = auth-param-type "=" auth-param-value auth-param-value = ( token | quoted-string ) auth-param-type = ( "auth-data" | "context-identifier" ) auth-data-value = 1*(UPALPHA|DIGIT) ;base64-encoded context-identifier-value = 1*(UPALPHA|DIGIT) ;base64-encoded The auth-param types defined by this specification (auth-data and context-identifier) both have auth-param-value which contain base64 encoded data. Note that both the auth-data and context-identifier auth-param may be absent. The semantics of these parameters will be explained below. Each auth-param-type MUST NOT occur more than once in a single challenge. [NOTE: It may be interesting to allow existing implementations of NEGOTIATE to treat the fast reauth feature as an optional extension. In this case it will be necessary to change to way the authentication token is represented.]

The GSS name of the server is "HTTP@<hostname>[:port]" where the :port part is absent if the port == 80 or if the port == 443. This mechanism SHOULD be used together with an HTTP transport providing session protection and encryption such as or . Session protection is a requirement for fast reauthentication described below. Like the mechanism described in this specification is based on mapping the GSS-API protocol to HTTP requests and responses where the GSS-API tokens are sent in the Authorization and WWW-Authentication headers. Unlike the entire handshake need not take place using a single TCP connection or a single HTTP/1.1 session. Instead opaque identifiers in the GSS challenge option field are optionally used together with channel bindings to provide a way to share a security context over several HTTP connections. This mechanism also serves as a way to let the client do a fast reauthentication to the server.

Normally the server initiates an authentication handshake when the client attempts to access a protected resource. The exception is when the client knows that it is accessing a protected resource and that the server supports the GSS mechanism, for instance when fast re-authentication is attempted by the client (cf below). In both cases the GSS-API negotiation is initiated by the client - i.e if the server initiates the authentication it is only to inform the client that authentication is required. The client SHOULD request mutual authentication from the GSS-API layer. Note that the first request by the client to a protected resource will also serve to let the client and server establish channel bindings using the 'tls-server-end-point' CB type which means that this first request is not in general "wasted" even in the case when the client has no prior knowledge about the server or is attempting fast re-authentication. If the client tries to access a protected resource the server may return a code 401 response with an WWW-Authenticate header containing a list of authentication challenges allowing the client to choose among different authentication mechanisms supported by the server. If the server supports the "GSS" mechanism the server returns a challenge with only the auth-scheme part ("GSS") and no parameters along with any other challenges for mechanisms supported by the server. This first request also allows the client and server to establish channel-bindings.

In each case below when GSS-API tokens resulting from calls into the GSS-API layer are sent from the server to the client or vice-versa, the token is encoded using base64 and sent as the "auth-data" parameter value of the Authorization and WWW-Authenticate headers respectively. A client initiates the authentication phase by sending the token resulting from the first call to gss_init_security_context to the server. Upon receipt of token (i.e a request with an accompanying Authenticate header with non-empty "auth-data" parameter value), the server MUST return the token resulting from a call to gss_accept_security_context in a code 401 response, unless the call to gss_accept_security_context fails in which case a code 403 response is returned. If the underlying transport provides session protection (eg HTTPS) and if channel-bindings are in place (cf below) then the server MAY include a unique identifier of the security context beeing negotiated (or having been negotiated in the case of the last transaction) in the "context-identifier" parameter value. The server MUST uniquely associate this identifier with the client and the security context. Upon receipt of a code 401 response from the server when the WWW-Authenticate header contains a non-empty "auth-data" parameter value, the client MUST return the token resulting from a call to gss_initiate_security_context to the server in a new request to the same resource. If the call fails the client MUST close the connection. If a "context-identifier" parameter value is present in the response from the server the client MUST include this in the ensuing request as the "context-identifier" parameter value. If the "context-identifier" parameter value is not present in the response from the server the client MUST use the same HTTP/1.1 connection for the entier handshake. If the client breaks the HTTP/1.1 connection the server MUST invalidate the security context unless a context identifier was sent to the client and returned to the server. A client may close the connection both as the result of using the context-identifier to spread the authentication over several underlying connections or as the result of a failed call to gss_initiate_security_context. This might at first seem like a problem but the GSS-API layer combined with proper handling of the context identifier will ensure that handling of these cases are disambiguated at the server. The client and server continues the handshake until either an error occurs (in which case a 403 is returned to the client or the client closes the connection depending on where the error happens) or the GSS-API layer has successfully completed the negotiation in which case the server sends a normal response to the client. If the last call to gss_accept_sec_context on the server resulted in a non-empty token the server MUST include this in a WWW-Authenticate header in the response to the client regardless of the return code which is beeing sent to the client. If the underlying transport provides session protection (eg HTTPS) and if channel-bindings are in place (cf below) then the server MAY include a "context-identifier" parameter value uniquely identifying the established security context. The server MAY decide to limit the validity of the established context and MAY choose not to consider references to the context after a certain amount of time (cf below). If the client receives a normal response with an non-empty "auth-data" parameter value the client MUST call gss_initiate_sec_context with this token as input to complete the authentication handshake. If the final response contains a "context-identifier" parameter value the client may cache it and use it to provide fast re-authentication by including it in a Authorization header with "GSS" mechanism and empty "auth-data" parameter value.

Authorization failures can occur even if the client is successfully authenticated to the server. In this case the server will send a 403 response to the client even though the GSS-API handshake has succeeded. It is important to let the client and server finish the authentication handshake even if the client is not authorized to access the resource. Therefore the client MUST call gss_initiate_sec_context with any GSS-API token returned to the client, even if the token was sent along with a 403 response. During authorization the server MAY use the GSS-API name associated with the established security context for authorization decisions and SHOULD provide a string representation of the GSS-API name as the REMOTE_USER meta-variable and "GSS" as the AUTH_TYPE meta-variable if the Commong Gateway Interface is provided by the server.

Upon receipt of a request containing an Authorization header with the "GSS" mechanism, an empty auth-data and the context-identifier parameter value, the server MUST verify that the identifier references a valid security context. If the security context is missing or invalid the server MUST return a 401 response prompting the client to re-negotiate the security context. If the identifier references a valid security context the server MUST process the request as if the client had just completed the full authentication handshake. When this process is completed the client is authenticated to the server and possibly (depending on the way the GSS-API layer was called and which GSS-mechanism was used) the server is authenticated to the client. The use of fast regegotiation is optional and clients and servers MUST NOT assume that this feature is supported.