A SASL Mechanism for OAuth
draft-mills-kitten-sasl-oauth-00.txt

Abstract

Simple Authentication and Security Layer (SASL) is a framework for providing authentication and data security services in connection-oriented protocols via replaceable mechanisms. OAuth is a protocol for delegated authentication and thereby provides a method for clients to access a protected resource on behalf of a resource owner.

This document defines the use of OAuth over SASL. Thereby, it enables OAuth usage for non-HTTP-based application protocols. A future version of this document will describe the integration into the Generic Security Services Application Program Interface (GSS-APIO).

Status of this Memo

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 27, 2011.

Copyright Notice

Copyright (c) 2010 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.

Table of Contents

1.  Introduction
2.  Terminology
3.  The OAuth SASL Mechanism
    3.1.  Initial Client Response
    3.2.  Server's Response
    3.3.  Discovery Information
    3.4.  Use of Signature Type Authorization
    3.5.  Formal Syntax of Messages
4.  Implementation Requirements
5.  Examples
    5.1.  Successful Bearer Token Exchange
    5.2.  Failed Exchange
6.  Security Considerations
7.  IANA Considerations
8.  References
    8.1.  Normative References
    8.2.  Informative References
§  Authors' Addresses

1.  Introduction

[I‑D.ietf‑oauth‑v2] (Hammer-Lahav, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Protocol,” July 2010.) offers a standard mechanism for delegating authentication typically used for the purpose of control access to resources. The core OAuth specification defines a number of profiles but focuses on an HTTP-based environment. This mechanism takes advantage of the OAuth protocol and infrastructure to provide a way to use SASL [RFC4422] (Melnikov, A. and K. Zeilenga, “Simple Authentication and Security Layer (SASL),” June 2006.) for access to resources for non-HTTP-based protocols. One example for such a protocol is the Internet Message Access Protocol (IMAP) [RFC3501] (Crispin, M., “INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1,” March 2003.), which is what we use in our examples.

The general authentication flow is that the application will first obtain an OAuth access token from an OAuth service for the resource. Once the client has obtained an OAuth access token it then connects and authenticated using this SASL mechanism.

Figure 1 (Interworking Architecture) shows the relationship between SASL and OAuth graphically. Item (1) denotes the part of the OAuth exchange that remains unchanged from [I‑D.ietf‑oauth‑v2] (Hammer-Lahav, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Protocol,” July 2010.), i.e. where the client obtains and refreshes Access Tokens. This document focuses on item (2) where the Access Token is presented to the resource server over SASL.

                                                              ----+
   +--------+                                  +---------------+  |
   |        |--(C)-- Authorization Request --->|   Resource    |  |
   |        |                                  |     Owner     |  |Plain
   |        |<-(D)------ Access Grant ---------|               |  |OAuth
   |        |                                  +---------------+  |2.0
   |        |                                                     |(1)
   |        |         Client Credentials &     +---------------+  |
   |        |--(E)------ Access Grant -------->| Authorization |  |
   | Client |                                  |     Server    |  |
   |        |<-(F)------ Access Token ---------|               |  |
   |        |      (w/ Optional Refresh Token) +---------------+  |
   |        |                                                 ----+
   |        |
   |        |                                                 ----+
   |        |        (Optional discovery)      +---------------+  |
   |        |--(A)------- User Name  --------->|               |  |
   | Client |                                  |               |  |
   |        |<-(B)------ Authentication -------|               |  |
   |        |          endpoint information    |    Resource   |  |OAuth

   |        |                                  |     Server    |  |over
   |        |--(G)------ Access Token -------->|               |  |SASL
   |        |                                  |               |  |
   |        |<-(H)---- Protected Resource -----|               |  |(2)
   +--------+                                  +---------------+  |
                                                              ----+

Note: The discovery procedure in OAuth is still work in progress. Hence, the discovery components described in this document should be considered incomplete and a tentative proposal. In general, there is a tradeoff between a generic, externally available defined discovery mechanisms (such as Webfinger using host-meta [I‑D.hammer‑hostmeta] (Hammer-Lahav, E., “Web Host Metadata,” June 2010.)) and configuration information exchanged inband between the protocol endpoints.

2.  Terminology

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 [RFC2119] (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.).

The reader is assumed to be familiar with the terms used in the OAuth 2.0 specification.

In examples, "C:" and "S:" indicate lines sent by the client and server respectively. Line breaks have been inserted for readability.

3.  The OAuth SASL Mechanism

SASL is used as a generalized authentication method in a variety of protocols. This document defines a mechanism to allow OAuth to be used within the SASL framework. In this model a client authenticates to an OAuth-capable authorization server over HTTP. This server then issues tokens after successfully authenticating the resource owner. Subsequently, the obtained token may be presented in an OAuth-authenticated request to the resource server.

3.1.  Initial Client Response

The client response is formatted in the style of an HTTP request, a GET line is included for the purposes of extensibility. The following key-value header lines are defined in the client response:

User (OPTIONAL):

Contains the user identifier being authenticated, and is provided to allow correct discovery information to be returned.

Host (REQUIRED):

Contains the host name to which the client connected.

Authorization (REQUIRED):

Contains the authenticator as specified in OAuth.

The user name is provided before discovery information because a given server could allow multiple authenticators. For instance, a large ISP could provide mail service for several domains who manage their own user information. For instance, users at foo-example.com could be authenticated by an OAuth service at https://oauth.foo-example.com/, and users at bar-example.com could be authenticated by https://oauth.bar-example.com, but both could be served by a hypothetical IMAP server running at a third domain, imap.example.net.

3.2.  Server's Response

The server validates the response as per the OAuth specification. If the protected resource requires a signed request (using one of the available signature method), the URL for the resource being authenticated is reconstructed per the OAuth specification from the HTTP style request passed by the client.

The server responds to a successful OAuth authentication by completing the SASL negotiation. The OAuth token MUST carry the user id to be authenticated and the server MUST use the user in the OAuth credential as the user being authenticated, the assertion we accept is that of the OAuth token and not other information such as from the URL or "User:" header.

The server responds to failed authentication by sending discovery information and then failing the authentication.

3.3.  Discovery Information

The server MUST send discovery information in response to a failed OAuth authentication exchange or a request with an empty Authenticate header. If discovery information is returned the server MUST return discovery information containing an authentication endpoint appropriate for the user. If the "User" header is present the discovery information MUST be for that user. In the absence of the "User" header the server SHOULD send discovery information for the user from the OAuth token. Discovery information is provided by the server to the client to allow a client to discover the appropriate OAuth authenticator service. The client then uses that information to obtain the refresh token and the access token needed for OAuth authentication. The client SHOULD cache and re-use the user specific discovery information for service endpoints. The following key-value pairs are defined for discovery information:

WWW-Authenticate:

As specified in [I‑D.ietf‑oauth‑v2] (Hammer-Lahav, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Protocol,” July 2010.).

Usage of the URL provided in the discovery information is defined in the OAuth specification. If the server supports multiple authenticators the discovery information returned for unknown users MUST be consistent with the discovery information for known users to prevent user enumeration. The OAuth 2.0 specification [I‑D.ietf‑oauth‑v2] (Hammer-Lahav, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Protocol,” July 2010.) has multiple types of authentication flows and the server MUST specify the supported authorization flows in the discovery information. The server MUST support at least one authorziation flow, and MAY support multiple flows.

3.4.  Use of Signature Type Authorization

OAuth supports authorization using signatures, which requires that both client and server construct the string to be signed. OAuth is designed for authentication/authorization to use a resource. SASL is designed for user authentication, and has no facility for being more specific. In this mechanism we require an HTTP style format specifically to support signature type authentication, but this is extremely limited. The HTTP style request is limited to a path of "/", because this mechanism is authenticating the user to the server. This mechanism is in the SASL model, but is designed so that no changes are needed if there is a revision of SASL which supports more specific resource authorization, e.g. IMAP access to a specific folder or FTP access limited to a specific directory.

So for example, given that OAuth has a port number component for the signature, on an IMAP server running on port 143 and given the the OAuth style authorization request (with long lines wrapped for readability) below:

GET / HTTP/1.1
Host: server.example.com
Authorization: Token token="vF9dft4qmT", nonce="s8djwd",
               timestamp="137131200", algorithm="hmac-sha256",
               signature="wOJIO9A2W5mFwDgiDvZbTSMK/PY="

The normalized request string would be constructed per [I‑D.ietf‑oauth‑v2] (Hammer-Lahav, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Protocol,” July 2010.). In this example the normalized request string would be:

137131200,s8djwd,hmac-sha256,GET,server.example.com:143,
http://example.com/

3.5.  Formal Syntax of Messages

    ;; CRLF, ... defined in RFC 5234

    client_response = header user* host authorization

    header = "GET / HTTP/1.1" CRLF

    user = 'User:' SPACE field-value CRLF

    host = 'Host:' SPACE field-value CRLF

    authorization = 'Authorization:' SPACE field-value CRLF

    field-name = *(%x20-%x39 / %x3b-%xff) ;; no ":", ascii printable

    field-value = *(%x01-%x09 / %x0b / %x0c / %x0e-%xff) CRLF
                  ;; no CR or LF

    server_discovery_info = [ "WWW-Authenticate:" SPACE
                              field_value extended* CRLF ]

    extended = field-name ":"  SPACE field-value

4.  Implementation Requirements

Tokens typically have a restricted lifetime. In addition, the policy of a client MAY revoke a previously obtained token at any time. The client MAY request a new access token for each connection to a resource server be made. In use cases like IMAP where clients frequently make multiple connections at the same time the client it is RECOMMENDED to re-use the same access token, if permitted by the resource server. Clients MAY implement any of the OAuth profiles since they are largely outside the scope of this specification, and the mentioned profiles in this document are just examples.

5.  Examples

These example illustrate exchanges between an IMAP client and an IMAP server.

5.1.  Successful Bearer Token Exchange

This example shows a successful OAuth 2.0 bearer token exchange with an initial client response. Note that line breaks are inserted for readability.

S: * IMAP4rev1 Server Ready
C: t0 CAPABILITY
S: * CAPABILITY IMAP4rev1 AUTH=OAUTH
S: t0 OK Completed
C: t1 AUTHENTICATE OAUTH R0VUIC8gSFRUUC8xLjENClVzZXI6IHNjb290ZXJAYWx0
      YXZpc3RhLmNvbQ0KSG9zdDogaW1hcC55YWhvby5jb20NCkF1dGhvcml6YXRpb24
      6IFRva2VuIHRva2VuPSJ2RjlkZnQ0cW1UYzJOdmIzUmxja0JoYkhSaGRtbHpkR0
      V1WTI5dENnPT0iDQoNCg==
S: +
S: t1 OK SASL authentication succeeded

As required by IMAP [RFC3501] (Crispin, M., “INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1,” March 2003.), the payloads are base64-encoded. The initial client response is:

GET / HTTP/1.1
Host: imap.example.com
Authorization: Token
token="vF9dft4qmTc2Nvb3RlckBhbHRhdmlzdGEuY29tCg=="

The "blank" line here is an empty response from the server. This response contains discovery information, in the success case no discovery information is necessary to the response is empty. Like other messages, and in accordance with the IMAP SASL binding, the empty response is base64-encoded.

5.2.  Failed Exchange

This example shows a failed exchange because of the empty Authorization header, which is how a client can query for discovery information. Note that line breaks are inserted for readability.

S: * IMAP4rev1 Server Ready
C: t0 CAPABILITY 
S: * CAPABILITY IMAP4rev1 AUTH=OAUTH SASL-IR
S: t0 OK Completed
C: t1 AUTHENTICATE OAUTH R0VUIC8gSFRUUC8xLjENClVzZXI6IHNjb290ZXJAYW
   x0YXZpc3RhLmNvbQ0KSG9zdDogaW1hcC55YWhvby5jb20NCkF1dGhlbnRpY2F0ZT
   ogDQoNCg==
S: + V1dXLUF1dGhlbnRpY2F0ZTogcmVhbG09ImltYXAueWFob28uY29tIiwgYXV0aH
   otdXJpPSJodHRwczovL2xvZ2luLnlhaG9vLmNvbS9vYXV0aCIsIHRva2VuLXVyaT
   0iaHR0cHM6Ly9sb2dpbi55YWhvby5jb20vb2F1dGgiLCBhbGdvcml0aG09ImhtYW
   Mtc2hhMjU2Ig0KDQo=
S: t1 NO SASL authentication failed

The initial client response is:

GET / HTTP/1.1
User: alice@example.com
Host: imap.example.com
Authorization:

The server discovery response is:

WWW-Authenticate: Token realm="mail",
       authz-uri="https://login.example.com/oauth",
       token-uri="https://login.example.com/oauth",
       algorithm="hmac-sha256"

6.  Security Considerations

This mechanism does not provide a security layer. The OAuth specification [I‑D.ietf‑oauth‑v2] (Hammer-Lahav, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Protocol,” July 2010.) allows for a variety of usages, and the security properties of these profiles varies. The usage of bearer tokens, for example, provide security features similar to cookies. Applications using this mechanism SHOULD exercise the same level of care using this mechanism as they would in using the SASL PLAIN mechanism. In particular, TLS 1.2 MUST be implemented and its usage is RECOMMENDED unless tokens expire quickly.

A significant benefit of OAuth for usage in IMAP, POP, SMTP, or other clients that usually store passwords, is that the password is not stored in the client, a token is. This means that the password is not exposed, what we risk is a token that can be more limited or can be easily revoked.

It is possible that SASL will be authenticating a connection, indeed our examples are IMAP, and the life of that connection my outlast the life of the token used to authenticate it. This is a common problem in application protocols where connections are long-lived, and not a problem with this mechanism per se.

It is possible for an application server running on Evil.example.com to tell a client to request a token from Good.example.org. A client following these instructions will pass a token from Good to Evil. This is by design, since it is possible that Good and Evil are merely names, not descriptive, and that this is an innocuous activity between cooperating two servers in different domains. For instance, a site might operate their authentication service in-house, but outsource their mail systems to an external entity.

7.  IANA Considerations

The IANA is requested to register the following SASL profile:

SASL mechanism profile: OAUTH

Security Considerations: See this document

Published Specification: See this document

For further information: Contact the authors of this document.

Owner/Change controller: the IETF

Note: None

8.  References

8.1. Normative References

8.2. Informative References

Authors' Addresses