| Network Working Group | N. Williams |
| Internet-Draft | Cryptonector |
| Intended status: Informational | August 2012 |
| Expires: January 31, 2013 |
RESTful Authentication Pattern for the HyperText Transport Protocol (HTTP)
draft-williams-http-rest-auth-00
This document proposes a “RESTful” pattern of authentication for HTTP/1.0, 1.1, and 2.0. The existing 401 status code and WWW-Authenticate header are used to indicate that authentication is required and for negotiation purposes. The client POSTs an initial authentication message to an indicated login URI, and reply messages are returned as new representations of a session resource named by a session URI.
This approach has a number of benefits: it can be implemented with or without help from the HTTP stack, it can be universally implemented on the server side using the Common Information Gateway (CGI) and FastCGI, it results in a session Uniform Resource Identifier (URI) that can be DELETEd to logout, it is completely orthogonal to any HTTP “routers” and proxies, and it naturally (i.e., without changing HTTP) handles multi-legged authentication mechanisms.
Among other features supported are: channel binding, an optional round trip optimization for challenge/response mechanisms, somecryptographic protection options for clients that don't use Transport Layer Security (TLS), stronger authentication of servers/services to users (where authentication mechanisms provide that) and more.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http:/⁠/⁠datatracker.ietf.org/⁠drafts/⁠current/⁠.
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."
This Internet-Draft will expire on January 31, 2013.
Copyright (c) 2012 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http:/⁠/⁠trustee.ietf.org/⁠license-⁠info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
We propose a pattern for HTTP authentication mechanisms that, by being “RESTful”, obtains a number of benefits:
There are probably other benefits not listed above.
The rough outline of the protocol is quite simple: initial authentication messages are POSTed to an agreed-upon or indicated resource, which then results in a new resource being created with the authentication reply message as the new resource's representation. Thereafter any additional authentication message exchanges needed (for multi-legged mechanisms) are POSTed to the new resource without a new resource being created. The resource created by the POSTing of the initial authentication mechanism identifies the resulting session, and its URI is known as the session URI. Session URIs can be used to multiplex multiple sessions over the same TCP/TLS connections, implement logout, and share sessions across multiple related servers.
Server-initiated authentication is also possible, whereby the server sends a challenge (not much else can be sent of value in an initial authentication message from the server besides a challenge, negotiation parameters, and, perhaps, a digital signature) in 401 errors in headers. If the server gives the client has a choice of mechanisms and the client picks one where the server sent the initial authentication message, then the client consumes that message and POSTs subsequent ones to the agreed URI.
This document replaces [I-D.williams-rest-gss].
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 [RFC2119].
The are very few normative protocol elements here besides the outline given in Section 1. The normative protocol elements are:
As can be seen in the ABNF in the preceding section, the server can offer some negotiable parameters. These are:
Each WWW-Authenticate header value offers a single mechanism and negotiable parameters for it. The WWW-ChannelBinding-Types header allows the server to offer channel binding types.
The ABNF for RESTauth WWW-Authenticate header values is as follows:
challenge = ( "RA-" mechname SP restauth-challenge )
mechname = TBD
restauth-challenge = ( login-uri SP session-types SP
replay-prot SP *1(mech-challenge) )
login-uri = absoluteURI
session-types = "s=" session-type /
(session-type ":" session-types)
session-type = "cookie" / "session-ID" / "MAC"
replay-prot = "r=" ("yes" / "no")
; TODO: add production for
; mech-challenge as a base64 string
; TODO: add MAC algorithm offers for alg agility
Figure 1: WWW-Authenticate ABNF
Figure 1
For a DIGEST-like mechanism it might look like “WWW-Authenticate: RA-Digest-SHA-256 tls-server-end-point session-ID no HE4SgWGrd/3+O7t16HqusA==”. For example, the mechname for the Kerberos V5 GSS-API mechanism might be “gss-krb5”, and a WWW-Authenticate header value for it might look like “WWW-Authenticate: RA-gss-krb5 http://foo.example/restauth-login tls-server-end-point session-ID no”.
Note that mechanisms that may be used include: GSS mechanisms, SASL mechanisms, ad-hoc mechanisms, and so on.
A new header is added by which servers MUST indicate which channel binding [RFC5056] types -if any- they support for RESTauth authentication; if the server does not support channel binding then this header MUST be absent. The header is named WWW-ChannelBinding-Types. Its values are channel binding types from the channel binding type registry [RFC5929].
A new header is added by which clients MUST indicate what channel binding type they used when POSTing RESTauth authentication messages, if any; if the client did not use channel binding then this header MUST be absent. The header is named WWW-ChannelBinding-Type. Its value is a channel binding type from the channel binding type registry [RFC5929].
A new header is added by which clients MUST indicate what session binding type they choose when POSTing RESTauth authentication messages. The header is named WWW-SessionBinding-Type. Its value is a session binding type as shown in Figure 1. This header MUST be present in RESTauth authentication HTTP requests.
A new header is added by which clients MUST indicate whether they desire replay protection when POSTing RESTauth authentication messages. The header is named WWW-SessionBinding-Type. Its value is “yes” or “no” (defaults to “no” if absent) as shown in Figure 1.
Replay protection is to be used only when TLS [RFC5246] is not, and only if a session binding type of “MAC” is also requested.
RESTauth can be initiated by a client that knows a priori that it needs to or wants to use RESTauth. Servers can also tell clients that access to certain resources require authentication, possibly including RESTauth mechanisms. When the server tells the client that it must authenticate the server may also give the client an initial authentication message for one or more mechanisms.
When the client knows a priori that it must authenticate then the client MUST know the RESTauth login URI a priori as well, as well as negotiable parameters, all of which the client might know from either an application protocol specification, or from caching this information from earlier RESTauth exchanges.
The server MUST use a 401 HTTP status code and WWW-Authenticate headers to inform the client of the need to authenticate in order to access a given resource. For RESTauth mechanisms the WWW-Authenticate header values MUST conform to the ABNF given in Section 3.1.1.
To proceed the client chooses a suitable authentication mechanism (for which, presumably, it has credentials for a desired client identity), possibly a channel binding type, possibly a session type, and whether to use replay protection.
Some mechanisms may optimize the protocol flow by allowing the server to include challenges in the 401 response's WWW-Authenticate header values. RESTauth allows this, but this feature is OPTIONAL: it must always be possible for a client to initiate RESTauth without first obtaining a challenge in a WWW-Authenticate header value, in which case the client must incur an extra protocol leg by obtaining the challenge (if it is at all necessary) in the server's reply to the client's first authentication message. The reason that this optimization is optional is to allow the implementation of RESTauth mechanisms with frameworks that only support client-initiated authentication.
A challenge may consist of a nonce, some encrypted or MACed nonce, a timestamp, and even seemingly unrelated contents such as certificates and digital signatures. The server MAY include a login URI in challenge-laden WWW-Authenticate headers where the login URI encodes secure state regarding the challenge.
A notion of session binding type is added for binding HTTP requests to specific RESTauth login sessions. Three types are provided:
A new HTTP header is added called WWW-Session-URI whose values consist of session URIs. At least one session URI MUST be included. Each session URI is an absoluteURI. Session URIs MUST NOT have unescaped commas (',') embedded in them. Servers MAY fail to implement support for multiple session URIs being referenced by a single request, in which case they MUST answer with error code <TBD>. Servers MUST validate the session URI before processing the request; if the session URI is invalid the server MUST respond with a 401 (or TBD?) status code.
It is common to deploy HTTP services with load-balanced servers behind a load balancer and TLS concentrator. Other techniques may also result in a multiplicity of servers acting on behalf of a single service. The load balancers may even behave like routers and route HTTP requests to the same server for all requests in a single connection, or even route HTTP requests according to the verb and resource. It helps to be able to have a notion of authenticated sessions that can be referenced by all servers responding to a given service name.
The server end of a RESTauth authentication message exchange may be terminated by one server, by many servers sharing session state (via the resources named by session URIs), or by a server-side HTTP router. Once a RESTauth session is established we assume that all servers responding to the same service name will be able to access the session resource, validate session URIs, and obtain keys for computing and validating session binding MACs. Alternatively, the router may take responsibility for session binding and signal authorization information from the established session to the HTTP servers behind the router (however, we do not here specify any methods for such signalling).
By using REST for the authentication message exchange we allow this disconnection between “session” and “connection”, which therefore facilitates “routing” of HTTP requests and even off-loading of authentication and/or session binding to HTTP “routers”.
This approach should be flexible enough for all existing architectures for deploying HTTP services.
TBD (header registrations, ...)
This entire document deals with security considerations. [Add more, like about channel binding, same-origin-like constraints on the login and session absolute URIs', ...]
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. |
| [RFC5246] | Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, August 2008. |
| [RFC5056] | Williams, N., "On the Use of Channel Bindings to Secure Channels", RFC 5056, November 2007. |
| [RFC5929] | Altman, J., Williams, N. and L. Zhu, "Channel Bindings for TLS", RFC 5929, July 2010. |
| [I-D.williams-rest-gss] | Williams, N, "RESTful Hypertext Transfer Protocol Application-Layer Authentication Using Generic Security Services", Internet-Draft draft-williams-rest-gss-00, June 2011. |