idnits 2.17.1 draft-mills-kitten-sasl-oauth-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 26, 2010) is 4994 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-31) exists of draft-ietf-oauth-v2-10 == Outdated reference: A later version (-17) exists of draft-hammer-hostmeta-13 -- Obsolete informational reference (is this intentional?): RFC 3501 (Obsoleted by RFC 9051) Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 KITTEN W. Mills 3 Internet-Draft T. Showalter 4 Intended status: Standards Track Yahoo Inc. 5 Expires: January 27, 2011 H. Tschofenig 6 Nokia Siemens Networks 7 July 26, 2010 9 A SASL Mechanism for OAuth 10 draft-mills-kitten-sasl-oauth-00.txt 12 Abstract 14 Simple Authentication and Security Layer (SASL) is a framework for 15 providing authentication and data security services in connection- 16 oriented protocols via replaceable mechanisms. OAuth is a protocol 17 for delegated authentication and thereby provides a method for 18 clients to access a protected resource on behalf of a resource owner. 20 This document defines the use of OAuth over SASL. Thereby, it 21 enables OAuth usage for non-HTTP-based application protocols. A 22 future version of this document will describe the integration into 23 the Generic Security Services Application Program Interface (GSS- 24 APIO). 26 Status of this Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on January 27, 2011. 43 Copyright Notice 45 Copyright (c) 2010 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 62 3. The OAuth SASL Mechanism . . . . . . . . . . . . . . . . . . . 6 63 3.1. Initial Client Response . . . . . . . . . . . . . . . . . 6 64 3.2. Server's Response . . . . . . . . . . . . . . . . . . . . 6 65 3.3. Discovery Information . . . . . . . . . . . . . . . . . . 7 66 3.4. Use of Signature Type Authorization . . . . . . . . . . . 7 67 3.5. Formal Syntax of Messages . . . . . . . . . . . . . . . . 8 68 4. Implementation Requirements . . . . . . . . . . . . . . . . . 9 69 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 70 5.1. Successful Bearer Token Exchange . . . . . . . . . . . . . 10 71 5.2. Failed Exchange . . . . . . . . . . . . . . . . . . . . . 10 72 6. Security Considerations . . . . . . . . . . . . . . . . . . . 12 73 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 74 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 14 75 8.1. Normative References . . . . . . . . . . . . . . . . . . . 14 76 8.2. Informative References . . . . . . . . . . . . . . . . . . 14 77 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 15 79 1. Introduction 81 [I-D.ietf-oauth-v2] offers a standard mechanism for delegating 82 authentication typically used for the purpose of control access to 83 resources. The core OAuth specification defines a number of profiles 84 but focuses on an HTTP-based environment. This mechanism takes 85 advantage of the OAuth protocol and infrastructure to provide a way 86 to use SASL [RFC4422] for access to resources for non-HTTP-based 87 protocols. One example for such a protocol is the Internet Message 88 Access Protocol (IMAP) [RFC3501], which is what we use in our 89 examples. 91 The general authentication flow is that the application will first 92 obtain an OAuth access token from an OAuth service for the resource. 93 Once the client has obtained an OAuth access token it then connects 94 and authenticated using this SASL mechanism. 96 Figure 1 shows the relationship between SASL and OAuth graphically. 97 Item (1) denotes the part of the OAuth exchange that remains 98 unchanged from [I-D.ietf-oauth-v2], i.e. where the client obtains and 99 refreshes Access Tokens. This document focuses on item (2) where the 100 Access Token is presented to the resource server over SASL. 102 ----+ 103 +--------+ +---------------+ | 104 | |--(C)-- Authorization Request --->| Resource | | 105 | | | Owner | |Plain 106 | |<-(D)------ Access Grant ---------| | |OAuth 107 | | +---------------+ |2.0 108 | | |(1) 109 | | Client Credentials & +---------------+ | 110 | |--(E)------ Access Grant -------->| Authorization | | 111 | Client | | Server | | 112 | |<-(F)------ Access Token ---------| | | 113 | | (w/ Optional Refresh Token) +---------------+ | 114 | | ----+ 115 | | 116 | | ----+ 117 | | (Optional discovery) +---------------+ | 118 | |--(A)------- User Name --------->| | | 119 | Client | | | | 120 | |<-(B)------ Authentication -------| | | 121 | | endpoint information | Resource | |OAuth 123 | | | Server | |over 124 | |--(G)------ Access Token -------->| | |SASL 125 | | | | | 126 | |<-(H)---- Protected Resource -----| | |(2) 127 +--------+ +---------------+ | 128 ----+ 130 Figure 1: Interworking Architecture 132 Note: The discovery procedure in OAuth is still work in progress. 133 Hence, the discovery components described in this document should 134 be considered incomplete and a tentative proposal. In general, 135 there is a tradeoff between a generic, externally available 136 defined discovery mechanisms (such as Webfinger using host-meta 137 [I-D.hammer-hostmeta]) and configuration information exchanged 138 inband between the protocol endpoints. 140 2. Terminology 142 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 143 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 144 document are to be interpreted as described in RFC 2119 [RFC2119]. 146 The reader is assumed to be familiar with the terms used in the OAuth 147 2.0 specification. 149 In examples, "C:" and "S:" indicate lines sent by the client and 150 server respectively. Line breaks have been inserted for readability. 152 3. The OAuth SASL Mechanism 154 SASL is used as a generalized authentication method in a variety of 155 protocols. This document defines a mechanism to allow OAuth to be 156 used within the SASL framework. In this model a client authenticates 157 to an OAuth-capable authorization server over HTTP. This server then 158 issues tokens after successfully authenticating the resource owner. 159 Subsequently, the obtained token may be presented in an OAuth- 160 authenticated request to the resource server. 162 3.1. Initial Client Response 164 The client response is formatted in the style of an HTTP request, a 165 GET line is included for the purposes of extensibility. The 166 following key-value header lines are defined in the client response: 168 User (OPTIONAL): Contains the user identifier being authenticated, 169 and is provided to allow correct discovery information to be 170 returned. 172 Host (REQUIRED): Contains the host name to which the client 173 connected. 175 Authorization (REQUIRED): Contains the authenticator as specified in 176 OAuth. 178 The user name is provided before discovery information because a 179 given server could allow multiple authenticators. For instance, a 180 large ISP could provide mail service for several domains who manage 181 their own user information. For instance, users at foo-example.com 182 could be authenticated by an OAuth service at 183 https://oauth.foo-example.com/, and users at bar-example.com could be 184 authenticated by https://oauth.bar-example.com, but both could be 185 served by a hypothetical IMAP server running at a third domain, 186 imap.example.net. 188 3.2. Server's Response 190 The server validates the response as per the OAuth specification. If 191 the protected resource requires a signed request (using one of the 192 available signature method), the URL for the resource being 193 authenticated is reconstructed per the OAuth specification from the 194 HTTP style request passed by the client. 196 The server responds to a successful OAuth authentication by 197 completing the SASL negotiation. The OAuth token MUST carry the user 198 id to be authenticated and the server MUST use the user in the OAuth 199 credential as the user being authenticated, the assertion we accept 200 is that of the OAuth token and not other information such as from the 201 URL or "User:" header. 203 The server responds to failed authentication by sending discovery 204 information and then failing the authentication. 206 3.3. Discovery Information 208 The server MUST send discovery information in response to a failed 209 OAuth authentication exchange or a request with an empty Authenticate 210 header. If discovery information is returned the server MUST return 211 discovery information containing an authentication endpoint 212 appropriate for the user. If the "User" header is present the 213 discovery information MUST be for that user. In the absence of the 214 "User" header the server SHOULD send discovery information for the 215 user from the OAuth token. Discovery information is provided by the 216 server to the client to allow a client to discover the appropriate 217 OAuth authenticator service. The client then uses that information 218 to obtain the refresh token and the access token needed for OAuth 219 authentication. The client SHOULD cache and re-use the user specific 220 discovery information for service endpoints. The following key-value 221 pairs are defined for discovery information: 223 WWW-Authenticate: As specified in [I-D.ietf-oauth-v2]. 225 Usage of the URL provided in the discovery information is defined in 226 the OAuth specification. If the server supports multiple 227 authenticators the discovery information returned for unknown users 228 MUST be consistent with the discovery information for known users to 229 prevent user enumeration. The OAuth 2.0 specification 230 [I-D.ietf-oauth-v2] has multiple types of authentication flows and 231 the server MUST specify the supported authorization flows in the 232 discovery information. The server MUST support at least one 233 authorziation flow, and MAY support multiple flows. 235 3.4. Use of Signature Type Authorization 237 OAuth supports authorization using signatures, which requires that 238 both client and server construct the string to be signed. OAuth is 239 designed for authentication/authorization to use a resource. SASL is 240 designed for user authentication, and has no facility for being more 241 specific. In this mechanism we require an HTTP style format 242 specifically to support signature type authentication, but this is 243 extremely limited. The HTTP style request is limited to a path of 244 "/", because this mechanism is authenticating the user to the server. 245 This mechanism is in the SASL model, but is designed so that no 246 changes are needed if there is a revision of SASL which supports more 247 specific resource authorization, e.g. IMAP access to a specific 248 folder or FTP access limited to a specific directory. 250 So for example, given that OAuth has a port number component for the 251 signature, on an IMAP server running on port 143 and given the the 252 OAuth style authorization request (with long lines wrapped for 253 readability) below: 255 GET / HTTP/1.1 256 Host: server.example.com 257 Authorization: Token token="vF9dft4qmT", nonce="s8djwd", 258 timestamp="137131200", algorithm="hmac-sha256", 259 signature="wOJIO9A2W5mFwDgiDvZbTSMK/PY=" 261 The normalized request string would be constructed per 262 [I-D.ietf-oauth-v2]. In this example the normalized request string 263 would be: 265 137131200,s8djwd,hmac-sha256,GET,server.example.com:143, 266 http://example.com/ 268 3.5. Formal Syntax of Messages 270 ;; CRLF, ... defined in RFC 5234 272 client_response = header user* host authorization 274 header = "GET / HTTP/1.1" CRLF 276 user = 'User:' SPACE field-value CRLF 278 host = 'Host:' SPACE field-value CRLF 280 authorization = 'Authorization:' SPACE field-value CRLF 282 field-name = *(%x20-%x39 / %x3b-%xff) ;; no ":", ascii printable 284 field-value = *(%x01-%x09 / %x0b / %x0c / %x0e-%xff) CRLF 285 ;; no CR or LF 287 server_discovery_info = [ "WWW-Authenticate:" SPACE 288 field_value extended* CRLF ] 290 extended = field-name ":" SPACE field-value 292 4. Implementation Requirements 294 Tokens typically have a restricted lifetime. In addition, the policy 295 of a client MAY revoke a previously obtained token at any time. The 296 client MAY request a new access token for each connection to a 297 resource server be made. In use cases like IMAP where clients 298 frequently make multiple connections at the same time the client it 299 is RECOMMENDED to re-use the same access token, if permitted by the 300 resource server. Clients MAY implement any of the OAuth profiles 301 since they are largely outside the scope of this specification, and 302 the mentioned profiles in this document are just examples. 304 5. Examples 306 These example illustrate exchanges between an IMAP client and an IMAP 307 server. 309 5.1. Successful Bearer Token Exchange 311 This example shows a successful OAuth 2.0 bearer token exchange with 312 an initial client response. Note that line breaks are inserted for 313 readability. 315 S: * IMAP4rev1 Server Ready 316 C: t0 CAPABILITY 317 S: * CAPABILITY IMAP4rev1 AUTH=OAUTH 318 S: t0 OK Completed 319 C: t1 AUTHENTICATE OAUTH R0VUIC8gSFRUUC8xLjENClVzZXI6IHNjb290ZXJAYWx0 320 YXZpc3RhLmNvbQ0KSG9zdDogaW1hcC55YWhvby5jb20NCkF1dGhvcml6YXRpb24 321 6IFRva2VuIHRva2VuPSJ2RjlkZnQ0cW1UYzJOdmIzUmxja0JoYkhSaGRtbHpkR0 322 V1WTI5dENnPT0iDQoNCg== 323 S: + 324 S: t1 OK SASL authentication succeeded 326 As required by IMAP [RFC3501], the payloads are base64-encoded. The 327 initial client response is: 329 GET / HTTP/1.1 330 Host: imap.example.com 331 Authorization: Token 332 token="vF9dft4qmTc2Nvb3RlckBhbHRhdmlzdGEuY29tCg==" 334 The "blank" line here is an empty response from the server. This 335 response contains discovery information, in the success case no 336 discovery information is necessary to the response is empty. Like 337 other messages, and in accordance with the IMAP SASL binding, the 338 empty response is base64-encoded. 340 5.2. Failed Exchange 342 This example shows a failed exchange because of the empty 343 Authorization header, which is how a client can query for discovery 344 information. Note that line breaks are inserted for readability. 346 S: * IMAP4rev1 Server Ready 347 C: t0 CAPABILITY  348 S: * CAPABILITY IMAP4rev1 AUTH=OAUTH SASL-IR 349 S: t0 OK Completed 350 C: t1 AUTHENTICATE OAUTH R0VUIC8gSFRUUC8xLjENClVzZXI6IHNjb290ZXJAYW 351 x0YXZpc3RhLmNvbQ0KSG9zdDogaW1hcC55YWhvby5jb20NCkF1dGhlbnRpY2F0ZT 352 ogDQoNCg== 353 S: + V1dXLUF1dGhlbnRpY2F0ZTogcmVhbG09ImltYXAueWFob28uY29tIiwgYXV0aH 354 otdXJpPSJodHRwczovL2xvZ2luLnlhaG9vLmNvbS9vYXV0aCIsIHRva2VuLXVyaT 355 0iaHR0cHM6Ly9sb2dpbi55YWhvby5jb20vb2F1dGgiLCBhbGdvcml0aG09ImhtYW 356 Mtc2hhMjU2Ig0KDQo= 357 S: t1 NO SASL authentication failed 359 The initial client response is: 361 GET / HTTP/1.1 362 User: alice@example.com 363 Host: imap.example.com 364 Authorization: 366 The server discovery response is: 368 WWW-Authenticate: Token realm="mail", 369 authz-uri="https://login.example.com/oauth", 370 token-uri="https://login.example.com/oauth", 371 algorithm="hmac-sha256" 373 6. Security Considerations 375 This mechanism does not provide a security layer. The OAuth 376 specification [I-D.ietf-oauth-v2] allows for a variety of usages, and 377 the security properties of these profiles varies. The usage of 378 bearer tokens, for example, provide security features similar to 379 cookies. Applications using this mechanism SHOULD exercise the same 380 level of care using this mechanism as they would in using the SASL 381 PLAIN mechanism. In particular, TLS 1.2 MUST be implemented and its 382 usage is RECOMMENDED unless tokens expire quickly. 384 A significant benefit of OAuth for usage in IMAP, POP, SMTP, or other 385 clients that usually store passwords, is that the password is not 386 stored in the client, a token is. This means that the password is 387 not exposed, what we risk is a token that can be more limited or can 388 be easily revoked. 390 It is possible that SASL will be authenticating a connection, indeed 391 our examples are IMAP, and the life of that connection my outlast the 392 life of the token used to authenticate it. This is a common problem 393 in application protocols where connections are long-lived, and not a 394 problem with this mechanism per se. 396 It is possible for an application server running on Evil.example.com 397 to tell a client to request a token from Good.example.org. A client 398 following these instructions will pass a token from Good to Evil. 399 This is by design, since it is possible that Good and Evil are merely 400 names, not descriptive, and that this is an innocuous activity 401 between cooperating two servers in different domains. For instance, 402 a site might operate their authentication service in-house, but 403 outsource their mail systems to an external entity. 405 7. IANA Considerations 407 The IANA is requested to register the following SASL profile: 409 SASL mechanism profile: OAUTH 411 Security Considerations: See this document 413 Published Specification: See this document 415 For further information: Contact the authors of this document. 417 Owner/Change controller: the IETF 419 Note: None 421 8. References 423 8.1. Normative References 425 [I-D.ietf-oauth-v2] 426 Hammer-Lahav, E., Recordon, D., and D. Hardt, "The OAuth 427 2.0 Protocol", draft-ietf-oauth-v2-10 (work in progress), 428 July 2010. 430 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 431 Requirement Levels", BCP 14, RFC 2119, March 1997. 433 [RFC4422] Melnikov, A. and K. Zeilenga, "Simple Authentication and 434 Security Layer (SASL)", RFC 4422, June 2006. 436 8.2. Informative References 438 [I-D.hammer-hostmeta] 439 Hammer-Lahav, E., "Web Host Metadata", 440 draft-hammer-hostmeta-13 (work in progress), June 2010. 442 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 443 4rev1", RFC 3501, March 2003. 445 Authors' Addresses 447 William Mills 448 Yahoo Inc. 450 Phone: 451 Email: wmills@yahoo-inc.com 453 Tim Showalter 454 Yahoo Inc. 456 Phone: 457 Email: timshow@yahoo-inc.com 459 Hannes Tschofenig 460 Nokia Siemens Networks 461 Linnoitustie 6 462 Espoo 02600 463 Finland 465 Phone: +358 (50) 4871445 466 Email: Hannes.Tschofenig@gmx.net 467 URI: http://www.tschofenig.priv.at