Skip to main content

Shepherd writeup

1. Summary

The document shepherd is Benjamin Kaduk.  The responsible Area Director
is Stephen Farrell.

This document specifies the OAuth protocol exchange between client
and resource server over SASL.  The core OAuth protocol specifies
only interactions between the client and the resource owner, and the
client and the authorization server, leaving interactions between
the client and resource server to be specified as part of the
specification of a token format, such as HTTP bearer tokens.  The
existing specified OAuth token types only consider interactions
between client and resource server which occur over HTTP; this
document provides a scheme by which the interactions specified
for HTTP can instead be performed over SASL.  In particular the
OAUTHBEARER and OAUTH10A SASL profiles are created, which correspond
to wrapped versions of the HTTP bearer token and OAuth 1.0a token
formats.  The wrapping scheme is sufficiently general that it
should be reusable for future token formats defined for HTTP.  The
ability to perform the OAuth exchange between client and resource
server over SASL allows OAuth to be used to authorize access
for non-HTTP protocols, such as IMAP and SMTP, as shown in the examples.

The SASL messages are specified to include a GS2 header to facilitate
potential future extension to a GSS-API mechanism, but no GSS-API
mechanism is specified at this time.  (The GS2 header also conveys
some information which is needed even for a pure SASL mechanism and
thus does not need to be duplicated explicitly in this specification.)

This document presents SASL mechanisms, and as such its intended
status is Proposed Standard.

2. Review and Consensus

The review process for this document was very long and complicated;
the document went through many substantive changes during the
process, which included four working group last call periods
(on versions -08, -12, -15, and -18) over the nearly five years since
the original submission.  The protocol went back and forth on a few
issues during its review and development, so in order to understand
the level of consensus for the current text, some discussion of its
history is needed.

At the time of the initial proposal, there was some resistance
to adding a new SASL mechanism that provided neither channel binding
nor a security layer, with the argument that there was not much
utility in such a mechanism.  This kicked off a long discussion
about channel bindings and what they mean in three-party protocols
such as OpenID and OAuth, but really, they can only apply to the
single connection between the two parties in a given exchange;
here, that is the two parties using SASL, the client and the
resource server.

The initial call for WG adoption presented an option that approval be
conditional on inclusion of a channel binding option.  At the time,
it was believed that channel binding was feasible with OAuth
based on HMAC signatures, but a CB requirement for adoption was
not made.  CB was added for mechanisms with a shared
secret and signed messages in draft-mills-kitten-sasl-oauth-02, but
the document was not adopted until later, after the WG was
rechartered in 2011 to explicitly include SASL/OAuth work.
Channel binding was later split off into a separate -PLUS variant
of the mechanisms for which it was believed possible, to simplify

During some of the early discussions it seems that many people were
assuming that the SASL mechanism would be incorporating the GS2 bridge
so as to also be a GSS-API mechanism, since that's just what was done
for all new SASL mechanisms at that time.  This assumption ended up
causing a great deal of trouble and frustration later on in the
document's progression.

It was recognized at an early stage that the usability of this
mechanism for a generic client (i.e., a desktop mail client that
can work against gmail and yahoo and everything else, as opposed
to just a gmail client) would require some means to discover the
necessary OAuth endpoints, but agreement over how much text
to include in this document (as opposed to a separate document) was
not achieved until after the third WGLC period.  That resurgence of
discovery discussion was particularly contentious: Two individuals
(one of whom is a coauthor of the document!) requested some
controversial changes regarding dynamic registration of the
corresponding author in off-list correspondence, and the corresponding
author disagreed with the proposed changes.  One of the two
individuals did bring their arguments to the list, but the other never
did so.  In the subsequent discussion, agreement was reached on the
text in section 3.2.2.  In particular, the agreed-upon text is in the
description of the openid-configuration element and the final
paragraph of section 3.2.2.

One of the motivations for this work is the existing XOAUTH2 mechanism
in use by Google.  (Google plans to update their deployment to the
final spec once it is published.)  In that deployment, a routing hint
is needed for the initial endpoint to know which mail server to route
the request to.  XOAUTH2 uses a user=xxx key/value pair to supply this
routing hint; this key was first added in the -02.  There were at
least three separate discussions of whether this "routing hint" is in
fact just the SASL authorization identity and whether it needed its
own key/value pair or could be transmitted as the authorization
identity in the GS2 header.  The discussion also covered whether the
authentication identity was what was wanted, magnifying the confusion.
This issue was basically resolved during the discussion after the
second WGLC: the routing hint is an authorization identity, and per
the SASL semantics, it is optional, and is carried in the GS2 header
when present.  Nonetheless, there is some impedance mismatch between
SASL, which ~always expects the mechanism to emit at least an
authentication id and frequently an authorization id as well, and
OAuth, which is at its core an authorization protocol and not an
authentication scheme.  This mismatch is acknowledged with the text
"It is worth noting that application protocols are allowed to require
an authzid [in the GS2 header], as are specific server

The addition of channel binding to the mechanism allowed the
introduction of the GS2 bridge making it a GSS-API mechanism as
well.  However, there were some nagging issues about the channel
bindings: most notably, that Oauth 1.0 has three underlying
mechanisms, including PLAINTEXT which offers no real secure
signature, and an RSA scheme that was underspecified.  Only the
HMAC-SHA1 form survived as feasible (and it is still the only
OAuth 1.0 scheme permitted by the current version of the document),
but much later on, even that CB scheme was found to not actually
provide the security properties needed from channel binding,
and was also removed.  (Bearer tokens cannot provide integrity
protection for channel bindings, period.)

In addition to the discussion around channel binding and its
(non)feasibility, the addition of the GS2 bridge to the spec brought
into scope all the requirements of a GSS mechanism, including export
name formats (and naming in general for both parties!).  This, in
turn, rekindled the authorization identity vs. routing hint debate,
and whether there were more names needed by the SASL mechanism than
could be accomodated by the GSS-API.

The GSS-API requirements led to a slow-moving train wreck, which
affected not only this spec but also some which had already been
published.  At it's core, the issue is that the GS2 specification
requires both channel binding and mutual authentication to be provided
by the mechanism.  Since the OAuth mechanism cannot provide
channel binding, it is therefore unusable with the RFC 5801 GS2
bridge.  The really bad part is that this mechanism and others were
claiming to provide mutual authentication without actually doing so.
Attempting to enforce a requirement on the application using this
mechanism that it use TLS to secure the channel and also verify the
server certificate is both a layering violation and also not the
mechanism performing mutual authentication.  As it was noted during
the second WGLC, if the mechanism claims to have provided mutual
authentication, the application uses that output as an indicator that
it does not need to perform the TLS server certificate verification!

A couple of consensus calls were made in 2013, on allowing for GS2
mechanisms that do not provide mutual authentication (a change to the
GS2 spec), which did not get much discussion, and for removing GS2
support entirely from the OAuth mechanism, which did get support.  The
implementation of that removed the GS2 header as well, which was
needed to convey the authorization identity, rekindling the
authorization identity debate yet again.  The debate is resolved by
always including the GS2 header, and using the authorization identity
there, so that a future extension could specify a compatible GSS-API
mechanisms that does not require any changes to this specification.
Along with the removal of GS2, channel binding and the corresponding
-PLUS mechanism variants were removed.  Work on the GS2 update was
paused for some time, but the document has recently obtained an editor
who will help push it forward.

The third WGLC found some minor issues regarding the details of the
protocol for the server response to failed authentication, and using
'status' values from the correct registry, but also brought the
dynamic registration issue back to the forefront, as mentioned

The fourth WGLC achieved consensus with support from both kitten and
the oauth working groups.  It did result in a few clarifications to
the document, fixing the ABNF and examples, noting the generic SASL
cancellation token functionality, and reiterating the TLS requirements
for using this mechanism, but these changes were not controversial.

3. Intellectual Property

Each author has confirmed conformance with the IPR declaration

There are no IPR declarations against this document.

4. Other Points

idnits reports an obsolete normative reference to RFC 5849, but
that is the OAuth 1.0 spec, and needs to be explicitly referenced
as distinct from OAuth 2.0, for the OAUTH10A mechanism.