| 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-03
This document proposes a “RESTful” pattern of authentication for HTTP/1.0, 1.1, and 2.0. The goal is to make it easy to add authentication mechanisms to HTTP and to make it easy to implement them even without much help from the HTTP stack (though it is best to integrate authentication into the stack, of course).
Among other benefits of RESTauth: it is orthogonal to “HTTP routers” and proxies, it results in session Uniform Resource Identifiers (URIs) that can be DELETEd to logout, naturally supports multi-legged authentication schemes, and it can be universally implemented on the server side with the Common Gateway Interface (CGI) and FastCGI.
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 [RFC2616] [XXX add reference to HTTP/2.0 as well] 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:
Server-initiated authentication is also possible, whereby the server sends a challenge in 401 errors in headers. If the server gives the client a choice of mechanisms (multiple WWW-Authenticate header values) and the client picks one where the server sent a challenge, then the client consumes that message and POSTs subsequent ones to the indicated URI.
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].
To the extent that existing Application Programming Interfaces (APIs) assume specific styles of HTTP authentication message flows, if we want those APIs to support RESTauth backwards-compatibly, then those APIs may impose constraints on RESTauth.
For example, the Android Account Manager API assumes a single round trip for authentication. But the Android Account Manager could perform all but the last round trip on behalf of the application, then let the application perform the last round trip. In order for that to work we need the authentication message exchange to be orthogonal to TCP/TLS connections – that is, we need it to be possible to use multiple TCP/TLS connections for completing a single authentication exchange.
A typical constraining characteristic might be that an API assumes the use of GET with tokens encoded into the URI, or that the API makes no room for the use of headers in authentication message exchanges.
One way to work around such constraints may be to provide various options in this framework. Another might be to use OAuth 1.0 [RFC5849] or 2.0 [I-D.ietf-oauth-v2] as a bridge: the API would use this framework under the covers then obtain OAuth credentials from the server that the application can then use in any way that the API's form allows for.
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.
Strong binding to TLS is provided via channel binding [RFC5056]. When a RESTauth mechanism provides strong authentication of the service to the user, the combination of RESTauth and channel binding results in strong authentication of the server to the user even though TLS is used for session transport protection.
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
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. If the mechanism used has its own method for indicating the use of channel binding, then this header MAY be ommitted. 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 SHOULD be present in RESTauth authentication HTTP requests, but may be ommitted when the selected mechanism provides its own session binding facility that is distinct from RESTauth's (this helps adapt OAuth to RESTauth with minimal or no changes).
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 4.1.2.
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. DIGEST-MD5 works this way, for example, sending a challenge nonce to be fed into the digest function (along with other client-side inputs).
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. There are two reasons for making this optional:
A challenge may consist of a nonce, some encrypted or MACed nonce, a time-stamp, certificates and digital signatures, etcetera. The server may include a login URI in challenge-laden WWW-Authenticate headers where the login URI encodes secure state regarding the challenge (e.g., the challenge encrypted in a symmetric key known only to the server).
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.
Note that referencing multiple session URIs is permitted, but this may not be meaningful for the application, thus the server MAY reject this (TODO: specify a status code for this?).
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 signaling).
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.
RESTauth is “out-of-band” in the sense that the authentication messages are exchanged independently of the application's requests for normal resources. Of course, RESTauth exchanges may well (and often will) happen in the same TCP/TLS connection as normal application requests, so RESTauth is not really out-of-band. We use “out-of-band” and “in-band” very loosely in this section.
There exist several “in-band” HTTP authentication alternatives where the authentication message exchanges happen in the context of application resources. Here the HTTP verb and resource are application-specific and have nothing to do with authentication, and the authentication messages are exchanged via HTTP request and response headers with the server responding with a 401 status code until authentication is complete.
The extant “Basic” and “DIGEST-MD5” [RFC2617] HTTP authentication methods, as well as HTTP/Negotiate [RFC4559] are “in-band” HTTP authentication methods.
In so far as an in-band authentication method results in a cookie or session URI/ID the distinction between in-band and out-of-band is almost trivial, as described above: authentication messages in headers vs. bodies, and HTTP verb and URL. However, if in-line authentication methods are strongly tied to the TCP/TLS connections over which they were utilized then that is a big disadvantage over RESTauth: each connection requires re-authenticating, and support for HTTP routing schemes is not clear.
HTTP/Negotiate is more troublesome because historically it has required re-authentication per-HTTP request(!).
Even if the only difference between in-band and out-of-band is a trivial one, using the REST pattern means that authentication can be implemented using with no help from the HTTP stack (even though it's desirable to have it implemented within/by the HTTP stack), whereas there may not be a way to implement in-band authentication without help from the HTTP stack for some stacks.
Here we describe (informatively, for the time being) how to use or adapt a variety of authentication mechanisms, from SSHv2, IKEv2, SASL, GSS-API, and other frameworks, so as to quickly gain a set of usable mechanisms, both, specification- and implementation-wise. This section is also intended to show that adding RESTauth mechanisms is easy.
OAuth 1.0 RFC5849 and OAuth 2.0 [I-D.ietf-oauth-v2] are commonly deployed. Being able to use OAuth via RESTauth would be useful. We attempt to make RESTauth such that at least for OAuth 1.0 there is a standard way to use OAuth such that it conforms to RESTauth.
For OAuth 1.0 [RFC5849] the “form-encoded body” form (see section 3.5.2 of [RFC5849]) of OAuth 1.0 conforms to RESTauth without further changes.
[It looks like OAuth 2.0 [I-D.ietf-oauth-v2] also uses POST to send tokens to the server, and it looks like it too effectively conforms to RESTauth.]
SSHv2 “userauth” mechanisms [RFC4252] typically involve a digital signature (or similar) of an SSHv2 session ID. There is no such thing as an SSHv2 session ID in HTTP. A session URI cannot serve as a stand-in for an SSHv2 session ID because a) the session URI is an outcome of authentication in RESTauth, b) to prevent cut-n-paste and replay attacks the client and the server both must contribute to the entropy of the session ID that is signed by the client.
In order to adapt SSHv2 userauth methods properly (i.e., securely), we have replace the SSHv2 session ID in the to-be-signed data with a hash of the channel binding and nonces contributed by the client and the server. As an optimization the server nonce can be sent as a challenge (this saves a round trip).
For hash agility reasons the hash function name is part of the SSHv2 RESTauth mechanism name. To avoid “multi-level negotiation” the SSHv2 userauth method name is also part of the RESTauth mechanism name.
The RESTauth mechanism name form for SSHv2 userauth methods, then, is: ssh-<SSHv2-userauth-method-name>-<hash-function-name>.
The following RESTauth mechanisms are defined here:
The client and the server must each contribute 128-bit nonces.
The ssh-publickey-SHA-256 and ssh-hostbased-SHA-256 mechanisms use the following instead of a traditional SSHv2 session ID:
Here the <channel_binding> is as per-[RFC5056]: the channel binding type name, followed by the channel binding data (e.g., 'tls-server-end-point' followed by the server EE certificate as sent in the server's TLS Certificate message).
Note that use of channel binding when using SSHv2 mechanisms is REQUIRED so as to defeat cut-n-paste attacks by weakly-authenticated servers.
Simple Authentication and Security Layers (SASL) [RFC4422] is a simple, pluggable framework for authentication mechanisms.
To use a SASL mechanism in RESTauth just prefix “SA-” to the SASL mechanism name and use that as the RESTauth mechanism name. If the SASL mechanism is server-initiated then the server's challenge is sent in the server's WWW-Authenticate header value as described above. All other SASL authentication messages are exchanged as described above (i.e., via POSTs, first to the login URI, then to the session URI, with response messages as the new representation of the session resource).
The HTTP status code functions as the application's outcome of authentication message. If SASL succeeds but authorization fails then the server should respond with a 401 status code to the POST of the final SASL authentication message from the client.
The server's WWW-Authenticate header values function as the mechanism listing operation. SASL security considerations [RFC4422] [RFC5801] apply (particularly regarding the negotiation of channel binding support).
The Salted Challenge Response Authentication Mechanism (SCRAM) [RFC5802] is a DIGEST-like mechanism for SASL. Nothing special is needed to use SCRAM versus any other SASL mechanism, except for a round trip optimized form of SCRAM, if we decide to pursue that (see Section 7.4.2).
The following figure shows what SCRAM in RESTauth looks like. Note that the resource representations are taken verbatim from [RFC5802].
C->S: GET /some-resources HTTP/1.1
Host: A.example
S->C: HTTP/1.1 401 Unauthorized
WWW-Authenticate: RA-SA-SCRAM-SHA-1 \
http://A.example/rest-sa-scram \
s=session-ID,MIC r=no
WWW-ChannelBinding-Types: tls-server-end-point
C->S: POST /rest-sa-scram HTTP/1.1
Host: A.example
WWW-ChannelBinding-Type: tls-server-end-point
WWW-SessionBinding-Type: session-ID
Content-Type: application/octet-stream
Content-Length: nnn
n,,n=user,r=fyko+d2lbbFgONRv9qkxdawL
S->C: HTTP/1.1 201
Location http://A.example/restauth-9d0af5f680d4ff46
Content-Type: application/octet-stream
Content-Length: nnn
r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j,
s=QSXCR+Q6sek8bf92,i=4096
C->S: POST /restauth-9d0af5f680d4ff46 HTTP/1.1
Host: A.example
Content-Type: application/octet-stream
Content-Length: nnn
c=biws,r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j,
p=v0X8v3Bz2T0CJGbJQyF0X+HI4Ts=
S->C: HTTP/1.1 200
Content-Type: application/octet-stream
Content-Length: nnn
v=rmF9pqV8S7suAoZWja4dJRkFsKQ=
Figure 2: RESTauth w/ SCRAM
The following figure shows what a round trip optimized RESTauth w/ SCRAM exchange might look like.
C->S: GET /some-resources HTTP/1.1
Host: A.example
S->C: HTTP/1.1 401 Unauthorized
WWW-Authenticate: RA-SA-SCRAM-SHA-1 \
http://A.example/rest-sa-scram \
s=session-ID,MIC r=no \
r=fyko+d2l...JY1ZVvWVs7j,i=4096
WWW-ChannelBinding-Types: tls-server-end-point
C->S: POST /rest-sa-scram HTTP/1.1
Host: A.example
WWW-ChannelBinding-Type: tls-server-end-point
WWW-SessionBinding-Type: session-ID
Content-Type: application/octet-stream
Content-Length: nnn
n,,n=user,r=fyko+d2lbbFgONRv9qkxdawL,
c=biws,r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j,
p=v0X8v3Bz2T0CJGbJQyF0X+HI4Ts=
S->C: HTTP/1.1 200
Content-Type: application/octet-stream
Content-Length: nnn
v=rmF9pqV8S7suAoZWja4dJRkFsKQ=
Figure 3: RESTauth w/ round trip optimized SCRAM
The Generic Security Services Application Programming Interface (GSS-API) [RFC2743] is another pluggable mechanism framework. Any GSS-API mechanism that supports channel binding [RFC5056] can be used as SASL mechanisms via the “SASL/GS2” bridge [RFC5801]. This includes the Kerberos V5 GSS-API mechanism [RFC4121].
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. |
| [RFC2616] | Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. |
| [RFC2617] | Franks, J., Hallam-Baker, P.M., Hostetler, J.L., Lawrence, S.D., Leach, P.J., Luotonen, A. and L. Stewart, "HTTP Authentication: Basic and Digest Access Authentication", RFC 2617, June 1999. |
| [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. |