From: http://www.ietf.org/internet-drafts/draft-mills-kitten-sasl-oauth-00.txt Title: A SASL Mechanism for OAuth Reference: IETF Network Working Group, Internet Draft 'draft-mills-kitten-sasl-oauth-00.txt' Date: July 26, 2010 Data Tracker: https://datatracker.ietf.org/doc/draft-mills-kitten-sasl-oauth/ Tracker Listing: http://ietfreport.isoc.org/idref/draft-mills-kitten-sasl-oauth/ HTML: http://tools.ietf.org/id/draft-mills-kitten-sasl-oauth-00.html Tools: http://tools.ietf.org/html/http://tools.ietf.org/id/draft-mills-kitten-sasl-oauth-00 (HTML) Announced: http://www.ietf.org/mail-archive/web/i-d-announce/current/msg32423.html IETF Common Authentication Technology Next Generation (KITTEN) Working Group Charter https://datatracker.ietf.org/wg/kitten/charter/ KITTEN Working Group Status Pages http://tools.ietf.org/wg/kitten/ Documents from KITTEN Working Group Members https://datatracker.ietf.org/wg/kitten/ KITTEN Working Group Discussion Archive http://www.ietf.org/mail-archive/web/kitten/ Working Group Recharter 2010-07 http://xml.coverpages.org/newsletter/news2010-07-22.html#cite5 http://www.ietf.org/mail-archive/web/kitten/current/msg01893.html ============================================================================== KITTEN W. Mills Internet-Draft T. Showalter Intended status: Standards Track Yahoo Inc. Expires: January 27, 2011 H. Tschofenig Nokia Siemens Networks July 26, 2010 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 Mills, et al. Expires January 27, 2011 [Page 1] Internet-Draft A SASL Mechanism for OAuth July 2010 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 . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 3. The OAuth SASL Mechanism . . . . . . . . . . . . . . . . . . . 6 3.1. Initial Client Response . . . . . . . . . . . . . . . . . 6 3.2. Server's Response . . . . . . . . . . . . . . . . . . . . 6 3.3. Discovery Information . . . . . . . . . . . . . . . . . . 7 3.4. Use of Signature Type Authorization . . . . . . . . . . . 7 3.5. Formal Syntax of Messages . . . . . . . . . . . . . . . . 8 4. Implementation Requirements . . . . . . . . . . . . . . . . . 9 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 5.1. Successful Bearer Token Exchange . . . . . . . . . . . . . 10 5.2. Failed Exchange . . . . . . . . . . . . . . . . . . . . . 10 6. Security Considerations . . . . . . . . . . . . . . . . . . . 12 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 14 8.1. Normative References . . . . . . . . . . . . . . . . . . . 14 8.2. Informative References . . . . . . . . . . . . . . . . . . 14 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 15 Mills, et al. Expires January 27, 2011 [Page 2] Internet-Draft A SASL Mechanism for OAuth July 2010 1. Introduction [I-D.ietf-oauth-v2] 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] for access to resources for non-HTTP-based protocols. One example for such a protocol is the Internet Message Access Protocol (IMAP) [RFC3501], 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 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], 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. Mills, et al. Expires January 27, 2011 [Page 3] Internet-Draft A SASL Mechanism for OAuth July 2010 ----+ +--------+ +---------------+ | | |--(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) +--------+ +---------------+ | ----+ Figure 1: Interworking Architecture 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]) and configuration information exchanged inband between the protocol endpoints. Mills, et al. Expires January 27, 2011 [Page 4] Internet-Draft A SASL Mechanism for OAuth July 2010 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]. 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. Mills, et al. Expires January 27, 2011 [Page 5] Internet-Draft A SASL Mechanism for OAuth July 2010 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 Mills, et al. Expires January 27, 2011 [Page 6] Internet-Draft A SASL Mechanism for OAuth July 2010 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]. 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] 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 Mills, et al. Expires January 27, 2011 [Page 7] Internet-Draft A SASL Mechanism for OAuth July 2010 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]. 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 Mills, et al. Expires January 27, 2011 [Page 8] Internet-Draft A SASL Mechanism for OAuth July 2010 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. Mills, et al. Expires January 27, 2011 [Page 9] Internet-Draft A SASL Mechanism for OAuth July 2010 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], 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. Mills, et al. Expires January 27, 2011 [Page 10] Internet-Draft A SASL Mechanism for OAuth July 2010 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" Mills, et al. Expires January 27, 2011 [Page 11] Internet-Draft A SASL Mechanism for OAuth July 2010 6. Security Considerations This mechanism does not provide a security layer. The OAuth specification [I-D.ietf-oauth-v2] 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. Mills, et al. Expires January 27, 2011 [Page 12] Internet-Draft A SASL Mechanism for OAuth July 2010 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 Mills, et al. Expires January 27, 2011 [Page 13] Internet-Draft A SASL Mechanism for OAuth July 2010 8. References 8.1. Normative References [I-D.ietf-oauth-v2] Hammer-Lahav, E., Recordon, D., and D. Hardt, "The OAuth 2.0 Protocol", draft-ietf-oauth-v2-10 (work in progress), July 2010. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC4422] Melnikov, A. and K. Zeilenga, "Simple Authentication and Security Layer (SASL)", RFC 4422, June 2006. 8.2. Informative References [I-D.hammer-hostmeta] Hammer-Lahav, E., "Web Host Metadata", draft-hammer-hostmeta-13 (work in progress), June 2010. [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1", RFC 3501, March 2003. Mills, et al. Expires January 27, 2011 [Page 14] Internet-Draft A SASL Mechanism for OAuth July 2010 Authors' Addresses William Mills Yahoo Inc. Phone: Email: wmills@yahoo-inc.com Tim Showalter Yahoo Inc. Phone: Email: timshow@yahoo-inc.com Hannes Tschofenig Nokia Siemens Networks Linnoitustie 6 Espoo 02600 Finland Phone: +358 (50) 4871445 Email: Hannes.Tschofenig@gmx.net URI: http://www.tschofenig.priv.at Mills, et al. Expires January 27, 2011 [Page 15]