idnits 2.17.1 draft-mills-kitten-sasl-oauth-02.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 (April 8, 2011) is 4738 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 (-05) exists of draft-hammer-oauth-v2-mac-token-02 == Outdated reference: A later version (-31) exists of draft-ietf-oauth-v2-12 == Outdated reference: A later version (-23) exists of draft-ietf-oauth-v2-bearer-02 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 5849 (Obsoleted by RFC 6749) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) == 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: 5 errors (**), 0 flaws (~~), 5 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: October 10, 2011 H. Tschofenig 6 Nokia Siemens Networks 7 April 8, 2011 9 A SASL Mechanism for OAuth 10 draft-mills-kitten-sasl-oauth-02.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 framework for delegated HTTP authentication and thereby provides a 18 method for clients to access a protected resource on behalf of a 19 resource owner. 21 This document defines the use of HTTP authentication over SASL, and 22 additionally defines authoriation and token issuing endpoint 23 discovery. Thereby, it enables schemes defined within the OAuth 24 framework for non-HTTP-based application protocols. A future version 25 of this document will describe the integration into the Generic 26 Security Services Application Program Interface (GSS-APIO). 28 Status of this Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at http://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on October 10, 2011. 45 Copyright Notice 47 Copyright (c) 2011 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (http://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 63 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 3. The OAuth SASL Mechanism . . . . . . . . . . . . . . . . . . . 6 65 3.1. Channel Binding . . . . . . . . . . . . . . . . . . . . . 6 66 3.2. Initial Client Response . . . . . . . . . . . . . . . . . 6 67 3.2.1. Query String in OAUTH-SSL . . . . . . . . . . . . . . 7 68 3.3. Server's Response . . . . . . . . . . . . . . . . . . . . 7 69 3.3.1. Mapping to SASL Identities . . . . . . . . . . . . . . 8 70 3.4. Discovery Information . . . . . . . . . . . . . . . . . . 8 71 3.5. Use of Signature Type Authorization . . . . . . . . . . . 9 72 4. Implementation Requirements . . . . . . . . . . . . . . . . . 11 73 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 74 5.1. Successful Bearer Token Exchange . . . . . . . . . . . . . 12 75 5.2. MAC Authentication with Channel Binding . . . . . . . . . 12 76 5.3. Failed Exchange . . . . . . . . . . . . . . . . . . . . . 13 77 5.4. Failed Channel Binmding . . . . . . . . . . . . . . . . . 14 78 6. Security Considerations . . . . . . . . . . . . . . . . . . . 15 79 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 80 7.1. SASL Registration . . . . . . . . . . . . . . . . . . . . 16 81 7.2. Link Type Registration . . . . . . . . . . . . . . . . . . 16 82 7.2.1. OAuth 2 Authentication Endpoint . . . . . . . . . . . 16 83 7.2.2. OAuth 2 Token Endpoint . . . . . . . . . . . . . . . . 17 84 7.2.3. OAuth 1.0a Request Initiation Endpoint . . . . . . . . 17 85 7.2.4. OAuth 1.0a Authorization Endpoint . . . . . . . . . . 17 86 7.2.5. OAuth 1.0a Token Endpoint . . . . . . . . . . . . . . 18 87 8. Appendix A -- Document History . . . . . . . . . . . . . . . . 19 88 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 20 89 9.1. Normative References . . . . . . . . . . . . . . . . . . . 20 90 9.2. Informative References . . . . . . . . . . . . . . . . . . 21 91 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 22 93 1. Introduction 95 OAuth [I-D.ietf-oauth-v2] offers a standard mechanism for delegating 96 authentication typically used for the purpose of control access to 97 resources. The core OAuth specification defines a framework for 98 authentication and token usage in an HTTP-based environment. The 99 HTTP authorization schemes and tokens in this model are defined 100 separately, some are deined within the OAuth 2 framework such as 101 OAuth 2.0 Protocol: Bearer Tokens [I-D.ietf-oauth-v2-bearer], and 102 some are free standing with OAuth 2 frameowrk bindings such as MAC 103 Authentication [I-D.hammer-oauth-v2-mac-token] tokens. This 104 mechanism takes advantage of the OAuth protocol and infrastructure to 105 provide a way to use SASL [RFC4422] for access to resources for non- 106 HTTP-based protocols such as IMAP [RFC3501], which is what this memo 107 uses in the examples. 109 The general authentication flow is that the application will first 110 obtain an access token from an OAuth token service for the resource. 111 Once the client has obtained an OAuth access token it then connects 112 and authenticated using this SASL mechanism. 114 Figure 1 shows the relationship between SASL and OAuth graphically. 115 Item (1) denotes the part of the OAuth exchange that remains 116 unchanged from [I-D.ietf-oauth-v2], i.e. where the client obtains and 117 refreshes Access Tokens. This document focuses on item (2) where the 118 Access Token is presented to the resource server over SASL. 120 ----+ 121 +--------+ +---------------+ | 122 | |--(C)-- Authorization Request --->| Resource | | 123 | | | Owner | |Plain 124 | |<-(D)------ Access Grant ---------| | |OAuth 125 | | +---------------+ |2.0 126 | | |(1) 127 | | Client Credentials & +---------------+ | 128 | |--(E)------ Access Grant -------->| Authorization | | 129 | Client | | Server | | 130 | |<-(F)------ Access Token ---------| | | 131 | | (w/ Optional Refresh Token) +---------------+ | 132 | | ----+ 133 | | 134 | | ----+ 135 | | (Optional discovery) +---------------+ | 136 | |--(A)------- User Name --------->| | | 137 | Client | | | | 138 | |<-(B)------ Authentication -------| | | 139 | | endpoint information | Resource | |OAuth 140 | | | Server | |over 141 | |--(G)------ Access Token -------->| | |SASL 142 | | | | | 143 | |<-(H)---- Protected Resource -----| | |(2) 144 +--------+ +---------------+ | 145 ----+ 147 Figure 1: Interworking Architecture 149 Note: The discovery procedure in OAuth is still work in progress. 150 Hence, the discovery components described in this document should 151 be considered incomplete and a tentative proposal. In general, 152 there is a tradeoff between a generic, externally available 153 defined discovery mechanisms (such as Webfinger using host-meta 154 [I-D.hammer-hostmeta]) and configuration information exchanged 155 inband between the protocol endpoints. 157 2. Terminology 159 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 160 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 161 document are to be interpreted as described in [RFC2119]. 163 The reader is assumed to be familiar with the terms used in the OAuth 164 2.0 specification. 166 In examples, "C:" and "S:" indicate lines sent by the client and 167 server respectively. Line breaks have been inserted for readability. 169 Note that the IMAP SASL specification requires base64 encoding 170 message, not this memo. 172 3. The OAuth SASL Mechanism 174 SASL is used as a generalized authentication method in a variety of 175 protocols. This document defines the "OAUTH" mechanism to allow HTTP 176 Authorization schemes in the OAuth framework to be used within the 177 SASL framework. In this model a client authenticates to an OAuth- 178 capable authorization server over HTTPS. This server then issues 179 tokens after successfully authenticating the resource owner. 180 Subsequently, the obtained token may be presented in an OAuth- 181 authenticated request to the resource server. This mechanism further 182 provides compatibility with OAuth 1.0a [RFC5849] and the "OAuth" 183 authentication scheme defined there. 185 3.1. Channel Binding 187 Channel binding [RFC5056] in this mechanism is defined in order to 188 allow satisfying the security requirements of the authorization 189 schemes used. This document defines the "OAUTH-SSL" mechanism to 190 provide TLS channel binding [RFC5929] to the OAUTH mechanim, and 191 specifically the "tls-unique" type of channel binding. 193 If the specification for the underlying authorization scheme requires 194 a security layer such as TLS [RFC5246] the server SHOULD only provide 195 that scheme in a mechanism with channel binding enabled. 197 3.2. Initial Client Response 199 The client response is formatted as an HTTP [RFC2616] request. The 200 HTTP request is limited in that the path MUST be "/". In the OAUTH 201 mechanim no query string is allowed. The following header lines are 202 defined in the client response: 204 User (OPTIONAL): Contains the user identifier being 205 authenticated, and is provided to allow correct discovery 206 information to be returned. 208 Host (REQUIRED): Contains the host name to which the client 209 connected. 211 Authorization (REQUIRED): An HTTP Authorization header.. 213 The user name is provided by the client to allow the discovery 214 information to be customised for the user, a given server could allow 215 multiple authenticators and it needs to return the correct one. For 216 instance, a large ISP could provide mail service for several domains 217 who manage their own user information. For instance, users at foo- 218 example.com could be authenticated by an OAuth service at 219 https://oauth.foo-example.com/, and users at bar-example.com could be 220 authenticated by https://oauth.bar-example.com, but both could be 221 served by a hypothetical IMAP server running at a third domain, 222 imap.example.net. 224 3.2.1. Query String in OAUTH-SSL 226 In the OAUTH-SSL mechanism the channel binding information is carried 227 in the query string. OAUTH-SSL defines following query parameter(s): 229 cbdata (REQUIRED): Contains the base64 encoded first TLS Finished 230 message sent. 232 3.3. Server's Response 234 The server validates the response per the specification for the 235 authorization scheme used. If the authorization scheme used includes 236 signing of the request parameters the client must provide a complete 237 HTTP style request that satisfies the data requirements for the 238 scheme in use. 240 In the OAUTH-SSL mechanism the server must also extract and base64 241 decode the first TLS Finished message sent from the client out ot the 242 query parameters of the tunneled HTTP request. It then compares that 243 to the server's own copy of that message. 245 The server responds to a successful OAuth authentication by 246 completing the SASL negotiation. The authentication scheme MUST 247 carry the user ID to be used as the authorization identity (identity 248 to act as). The server MUST use that ID as the user being 249 authorized, that is the user assertion we accept and not other 250 information such as from the URL or "User:" header. 252 The server responds to failed authentication by sending discovery 253 information in an HTTP style response with the HTTP status code set 254 to 401, and then failing the authentication. If channel binding is 255 in use and the channel binding fails the server responds with a 256 minimal HTTP response without discovery information and the HTTP 257 status code set to 412 to indicate that the channel binding 258 precondition failed. If the authentication scheme in use does not 259 include signing the server SHOULD revoke the presented credential and 260 the client SHOULD discard that credential. 262 3.3.1. Mapping to SASL Identities 264 Some OAuth mechanisms can provide both an authorization identity and 265 an authentication identity. An example of this is OAuth 1.0a 266 [RFC5849] where the consumer key (oauth_consumer_key) identifies the 267 entity using to token which equates to the SASL authentication 268 identity, and is authenticated using the shared secret. The 269 authorization identity in the OAuth 1.0a case is carried in the token 270 (per the requirement above), which SHOULD validated independently. 271 The server MAY use a consumer key or other comparable identity in the 272 OAuth authorization scheme as the SASL authentication identity. If 273 an appropriate authentication identity is not avaialble teh server 274 MUST use the identity asserted in the token. 276 3.4. Discovery Information 278 The server MUST send discovery information in response to a failed 279 authentication exchange or a request with an empty Authorization 280 header. If discovery information is returned it MUST include an 281 authentication endpoint appropriate for the user. If the "User" 282 header is present the discovery information MUST be for that user. 283 Discovery information is provided by the server to the client to 284 allow a client to discover the appropriate OAuth authentication and 285 token endpoints. The client then uses that information to obtain the 286 access token needed for OAuth authentication. The client SHOULD 287 cache and re-use the user specific discovery information for service 288 endpoints. 290 Discovery information makes use of both the WWW-Authenticate header 291 as defined in HTTP Authentication: Basic and Digest Access 292 Authentication [RFC2617] and Link headers as defined in [RFC5988]. 293 The following elements are defined for discovery information: 295 WWW-Authenticate A WWW-Authenticate header for each authentication 296 scheme supported by the server. Authentication scheme names are 297 case insensitive. The following [RFC2617] authentication 298 parameters are defined: 300 realm REQUIRED -- (as defined by RFC2617) 302 scope OPTIONAL -- A quoted string. This provides the client an 303 OAuth 2 scope known to be valid for the resource. 305 oauth2-authenticator An [RFC5988] Link header specifying the 306 [I-D.ietf-oauth-v2] authentication endpoint. This link has an 307 OPTIONAL link-extension "scheme", if included this link applies 308 ONLY to the specified scheme. 310 oauth2-token An [RFC5988] Link header specifying the 311 [I-D.ietf-oauth-v2] token endpoint. This link has an OPTIONAL 312 link-extension "scheme", if included this link applies ONLY to the 313 specified scheme. 315 oauth-initiate (Optional) An [RFC5988] Link header specifying the 316 Oauth 1.0a [RFC5849] initiation endpoint. The server MUST send 317 this if "OAuth" is included in the supported list of HTTP 318 authentication schemes for the server. 320 oauth-authorize (Optional) An [RFC5988] Link header specifying the 321 Oauth 1.0a [RFC5849] authentication endpoint. The server MUST 322 send this if "OAuth" is included in the supported list of HTTP 323 authentication schemes for the server. 325 oauth-token (Optional) An [RFC5988] Link header specifying the Oauth 326 1.0a [RFC5849] token endpoint. The server MUST send this if 327 "OAuth" is included in the supported list of HTTP authentication 328 schemes for the server. This link type has one link-extenstion 329 "grant-types" which is a space separated list of the the OAuth 2.0 330 grant types that can be used at the token endpoint to obtain a 331 token. 333 Usage of the URLs provided in the discovery information is defined in 334 the relevant specifications. If the server supports multiple 335 authenticators the discovery information returned for unknown users 336 MUST be consistent with the discovery information for known users to 337 prevent user enumeration. The OAuth 2.0 specification 338 [I-D.ietf-oauth-v2] supports multiple types of authentication schemes 339 and the server MUST specify at least one supported authentication 340 scheme in the discovery information. The server MAY support multiple 341 schemes and MAY support schemes not listed in the discovery 342 information. 344 If the resource server provides a scope the client SHOULD always 345 request scoped tokens from the token endpoint. The client MAY use a 346 scope other than the one provided by the resource server. Scopes 347 other than those advertised by the resource server must be defined by 348 the resource owner and provided in service documentation (which is 349 beyond the scope of this memo). 351 3.5. Use of Signature Type Authorization 353 This mechanism supports authorization using signatures, which 354 requires that both client and server construct the string to be 355 signed. OAuth 2 is designed for authentication/authorization to 356 access specific URIs. SASL is designed for user authentication, and 357 has no facility for being more specific. In this mechanism we 358 require an HTTP style format specifically to support signature type 359 authentication, but this is extremely limited. The HTTP style 360 request is limited to a path of "/". This mechanism is in the SASL 361 model, but is designed so that no changes are needed if there is a 362 revision of SASL which supports more specific resource authorization, 363 e.g. IMAP access to a specific folder or FTP access limited to a 364 specific directory. 366 Using the example in the MAC specification 367 [I-D.hammer-oauth-v2-mac-token] as a starting point, on an IMAP 368 server running on port 143 and given the MAC style authorization 369 request (with long lines wrapped for readability) below: 371 GET / HTTP/1.1 372 Host: server.example.com 373 User: user@example.com 374 Authorization: MAC token="h480djs93hd8",timestamp="137131200", 375 nonce="dj83hs9s",signature="YTVjyNSujYs1WsDurFnvFi4JK6o=" 377 The normalized request string would be constructed per the MAC 378 specifcation [I-D.hammer-oauth-v2-mac-token]. In this example the 379 normalized request string with the new line separator character is 380 represented by "\n" for display purposes only would be: 382 h480djs93hd8\n 383 137131200\n 384 dj83hs9s\n 385 \n 386 GET\n 387 server.example.com\n 388 143\n 389 /\n 390 \n 392 4. Implementation Requirements 394 Tokens typically have a restricted lifetime. In addition a 395 previously obtained token MAY be revoked or rendered invalid at any 396 time. The client MAY request a new access token for each connection 397 to a resource server, but it SHOULD cache and re-use access 398 credentials that appear to be valid. Credential lifetime and how 399 that is communicated to the client is defined in the authentication 400 scheme specifications. Clients MAY implement any of the OAuth 2 401 profiles since they are largely outside the scope of this 402 specification, and the mentioned profiles in this document are just 403 examples. 405 5. Examples 407 These example illustrate exchanges between an IMAP client and an IMAP 408 server. 410 5.1. Successful Bearer Token Exchange 412 This example shows a successful OAuth 2.0 bearer token exchange with 413 an initial client response. Note that line breaks are inserted for 414 readability. 416 S: * IMAP4rev1 Server Ready 417 C: t0 CAPABILITY 418 S: * CAPABILITY IMAP4rev1 AUTH=OAUTH 419 S: t0 OK Completed 420 C: t1 AUTHENTICATE OAUTH R0VUIC8gSFRUUC8xLjENCkhvc3Q6IGltYXAuZXhhbXBs 421 ZS5jb20NCkF1dGhvcml6YXRpb246IEJFQVJFUiAidkY5ZGZ0NHFtVGMyTnZiM1J 422 sY2tCaGJIUmhkbWx6ZEdFdVkyOXRDZz09Ig0KDQo= 423 S: + 424 S: t1 OK SASL authentication succeeded 426 As required by IMAP [RFC3501], the payloads are base64-encoded. The 427 decoded initial client response is: 429 GET / HTTP/1.1 430 Host: imap.example.com 431 Authorization: BEARER "vF9dft4qmTc2Nvb3RlckBhbHRhdmlzdGEuY29tCg==" 433 The line conaining just a "+" and a space is an empty response from 434 the server. This response contains discovery information, and in the 435 success case no discovery information is necessary so the response is 436 empty. Like other messages, and in accordance with the IMAP SASL 437 binding, the empty response is base64-encoded. 439 5.2. MAC Authentication with Channel Binding 441 This example shows a channel binding failure. The example sends the 442 same request as above, but in the context of an OAUTH-SSL exchange 443 the channel binding information is missing. Note that line breaks 444 are inserted for readability. 446 S: * CAPABILITY IMAP4rev1 AUTH=OAUTH SASL-IR IMAP4rev1 Server Ready 447 S: t0 OK Completed 448 C: t1 AUTHENTICATE MAC R0VUIC8/Y2JkYXRhPSJTRzkzSUdKcFp5QnBjeUJoSUZSTVV5Q 449 m1hVzVoYkNCdFpYTnpZV2RsUHdvPSIgSFRUUC8xLjENCkhvc3Q6IHNlcnZlci5leGFtcG 450 xlLmNvbQ0KVXNlcjogdXNlckBleGFtcGxlLmNvbQ0KQXV0aG9yaXphdGlvbjogTUFDIHR 451 va2VuPSJoNDgwZGpzOTNoZDgiLHRpbWVzdGFtcD0iMTM3MTMxMjAwIixub25jZT0iZGo4 452 M2hzOXMiLHNpZ25hdHVyZT0iV1c5MUlHMTFjM1FnWW1VZ1ltOXlaV1F1SUFvPSINCg0K 453 S: + 454 S: t1 OK SASL authentication succeeded 456 As required by IMAP [RFC3501], the payloads are base64-encoded. The 457 decoded initial client response is: 459 GET /?cbdata="SG93IGJpZyBpcyBhIFRMUyBmaW5hbCBtZXNzYWdlPwo=" HTTP/1.1 460 Host: server.example.com 461 User: user@example.com 462 Authorization: MAC token="h480djs93hd8",timestamp="137131200", 463 nonce="dj83hs9s",signature="WW91IG11c3QgYmUgYm9yZWQuIAo=" 465 The line conaining just a "+" and a space is an empty response from 466 the server. This response contains discovery information, and in the 467 success case no discovery information is necessary so the response is 468 empty. Like other messages, and in accordance with the IMAP SASL 469 binding, the empty response is base64-encoded. 471 5.3. Failed Exchange 473 This example shows a failed exchange because of the empty 474 Authorization header, which is how a client can query for discovery 475 information. Note that line breaks are inserted for readability. 477 S: * CAPABILITY IMAP4rev1 AUTH=OAUTH SASL-IR IMAP4rev1 Server Ready 478 S: t0 OK Completed 479 C: t1 AUTHENTICATE OAUTH R0VUIC8gSFRUUC8xLjENClVzZXI6IHNjb290ZXJAYW 480 x0YXZpc3RhLmNvbQ0KSG9zdDogaW1hcC55YWhvby5jb20NCkF1dGhlbnRpY2F0ZT 481 ogDQoNCg== 482 S: + SFRUUC8xLjEgNDAxIFVuYXV0aG9yaXplZA0KV1dXLUF1dGhlbnRpY2F0ZTogQk 483 VBUkVSIHJlYWxtPSJleGFtcGxlLmNvbSINCkxpbms6IDxodHRwczovL2xvZ2luLn 484 lhaG9vLmNvbS9vYXV0aD4gcmVsPSJvYXV0aDItYXV0aGVudGljYXRvciIgIA0KTG 485 luazogPGh0dHBzOi8vbG9naW4ueWFob28uY29tL29hdXRoPiByZWw9Im91YXRoMi 486 10b2tlbiINCg0K 487 S: t1 NO SASL authentication failed 489 The decoded initial client response is: 491 GET / HTTP/1.1 492 User: alice@example.com 493 Host: imap.example.com 494 Authorization: 496 The decoded server discovery response is: 498 HTTP/1.1 401 Unauthorized 499 WWW-Authenticate: BEARER realm="example.com" 500 Link: rel="oauth2-authenticator" 501 Link: rel="ouath2-token" 503 5.4. Failed Channel Binmding 505 This example shows a channel binding failure in a discovery request. 506 The channel binding information is empty. Note that line breaks are 507 inserted for readability. 509 S: * CAPABILITY IMAP4rev1 AUTH=OAUTH SASL-IR IMAP4rev1 Server Ready 510 S: t0 OK Completed 511 C: t1 AUTHENTICATE OAUTH R0VUIC8/Y2JkYXRhPSIiIEhUVFAvMS4xDQpVc2VyOi 512 BhbGljZUBleGFtcGxlLmNvbQ0KSG9zdDogaW1hcC5leGFtcGxlLmNvbQ0KQXV0aG 513 9yaXphdGlvbjoNCg0K 514 S: + SFRUUC8xLjEgNDEyIFByZWNvbmRpdGlvbiBGYWlsZWQNCg0KDQo= 515 S: t1 NO SASL authentication failed 517 The decoded initial client response is: 519 GET /?cbdata="" HTTP/1.1 520 User: alice@example.com 521 Host: imap.example.com 522 Authorization: 524 The decoded server response is: 526 HTTP/1.1 412 Precondition Failed 528 6. Security Considerations 530 This mechanism does not provide a security layer, but does provide a 531 provision for channel binding. The OAuth 2 specification 532 [I-D.ietf-oauth-v2] allows for a variety of usages, and the security 533 properties of these profiles vary. The usage of bearer tokens, for 534 example, provide security features similar to cookies. Applications 535 using this mechanism SHOULD exercise the same level of care using 536 this mechanism as they would in using the SASL PLAIN mechanism. In 537 particular, TLS 1.2 MUST be implemented and its usage is RECOMMENDED 538 unless tokens expire quickly. 540 Channel binding in this mechanim has different properties based on 541 the authentication scheme used. Bearer tokens have the same 542 properties as cookies, and the bearer token authentication scheme has 543 no signature or message integrity. Channel binding to TLS with a 544 bearer token provides only a binding to the TLS layer. 545 Authentication schemes like MAC tokens have a signature over the 546 channel binding information. These provide protection against a man 547 in the middle, and the MAC authorization header is bound to the 548 channel and only valid in that context. 550 A significant benefit of OAuth for usage in clients that usually 551 store passwords is that the password is not stored in the client, a 552 token is. This means that the password is not exposed, what we risk 553 is a token that can be more limited or can be easily revoked. 555 It is possible that SASL will be authenticating a connection and the 556 life of that connection may outlast the life of the token used to 557 authenticate it. This is a common problem in application protocols 558 where connections are long-lived, and not a problem with this 559 mechanism per se. Servers MAY unilaterally disconnect clients in 560 accordance with the application protocol. 562 An OAuth credential is not equivalent to the password or primary 563 account credential. There are protocols like XMPP that allow actions 564 like change password. The server SHOULD ensure that actions taken in 565 the authenticated channel are appropriate to the strength of the 566 presented credential. 568 It is possible for an application server running on Evil.example.com 569 to tell a client to request a token from Good.example.org. A client 570 following these instructions will pass a token from Good to Evil. 571 This is by design, since it is possible that Good and Evil are merely 572 names, not descriptive, and that this is an innocuous activity 573 between cooperating two servers in different domains. For instance, 574 a site might operate their authentication service in-house, but 575 outsource their mail systems to an external entity. 577 7. IANA Considerations 579 7.1. SASL Registration 581 The IANA is requested to register the following SASL profile: 583 SASL mechanism profile: OAUTH 585 Security Considerations: See this document 587 Published Specification: See this document 589 For further information: Contact the authors of this document. 591 Owner/Change controller: the IETF 593 Note: None 595 The IANA is requested to register the following SASL profile: 597 SASL mechanism profile: OAUTH-SSL 599 Security Considerations: See this document 601 Published Specification: See this document 603 For further information: Contact the authors of this document. 605 Owner/Change controller: the IETF 607 Note: None 609 7.2. Link Type Registration 611 Pursuant to [RFC5988] The following link type registrations [[will 612 be]] registered by mail to link-relations@ietf.org. 614 7.2.1. OAuth 2 Authentication Endpoint 616 o Relation Name: oauth2-authenticator 618 o Description: An OAuth 2.0 authentication endpoint. 620 o Reference: 622 o Notes: This link type indicates an OAuth 2.0 authentication 623 endpoint that can be used for user authentication/authorization 624 for the endpoint providing the link. 626 o Application Data: [optional] 628 7.2.2. OAuth 2 Token Endpoint 630 o Relation Name: oauth2-token 632 o Description: The OAuth token endpoint used to get tokens for 633 access. 635 o Reference: 637 o Notes: The OAuth 2.0 token enpoint to be used for obtaining tokens 638 to access the endpoint providing the link. 640 o Application Data: This link type has one link-extenstion "grant- 641 types" which is the OAuth 2.0 grant types that can be used at the 642 token endpoint to obtain a token. This is not an exclusive list, 643 it provides a hint to the application of what SHOULD be valid. A 644 token endpoint MAY support additional grant types not advertised 645 by a resource endpoint. 647 7.2.3. OAuth 1.0a Request Initiation Endpoint 649 o Relation Name: oauth-initiate 651 o Description: The OAuth 1.0a request initiation endpoint used to 652 get tokens for access. 654 o Reference: 656 o Notes: The OAuth 1.0a enpoint used to initiate the sequence, this 657 temporary request is what the user approves to grant access to the 658 resource. 660 o Application Data: 662 7.2.4. OAuth 1.0a Authorization Endpoint 664 o Relation Name: oauth-authorize 666 o Description: The OAuth 1.0a authorization endpoint used to approve 667 an access request. 669 o Reference: 671 o Notes: 673 o Application Data: 675 7.2.5. OAuth 1.0a Token Endpoint 677 o Relation Name: oauth-token 679 o Description: The OAuth 1.0a token endpoint used to get tokens for 680 access. 682 o Reference: 684 o Notes: 686 o Application Data: 688 8. Appendix A -- Document History 690 [[ to be removed by RFC editor before publication as an RFC ]] 692 -02 694 o Filling out Channel Binding 696 o Added text clarifying how to bind to the 2 kinds of SASL 697 identities. 699 -01 701 o Bringing this into line with rdraft 12 of the core spec, the 702 bearer token spec, and references the MAC token spec 704 o Changing discovery over to using the Link header construct from 705 RFC5988. 707 o Added the seeds of channel binding. 709 -00 711 o Initial revision 713 9. References 715 9.1. Normative References 717 [I-D.hammer-oauth-v2-mac-token] 718 Hammer-Lahav, E., "HTTP Authentication: MAC 719 Authentication", draft-hammer-oauth-v2-mac-token-02 (work 720 in progress), January 2011. 722 [I-D.ietf-oauth-v2] 723 Hammer-Lahav, E., Recordon, D., and D. Hardt, "The OAuth 724 2.0 Authorization Protocol", draft-ietf-oauth-v2-12 (work 725 in progress), January 2011. 727 [I-D.ietf-oauth-v2-bearer] 728 Jones, M., Hardt, D., and D. Recordon, "The OAuth 2.0 729 Protocol: Bearer Tokens", draft-ietf-oauth-v2-bearer-02 730 (work in progress), January 2011. 732 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 733 Requirement Levels", BCP 14, RFC 2119, March 1997. 735 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 736 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 737 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 739 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 740 Leach, P., Luotonen, A., and L. Stewart, "HTTP 741 Authentication: Basic and Digest Access Authentication", 742 RFC 2617, June 1999. 744 [RFC4422] Melnikov, A. and K. Zeilenga, "Simple Authentication and 745 Security Layer (SASL)", RFC 4422, June 2006. 747 [RFC5056] Williams, N., "On the Use of Channel Bindings to Secure 748 Channels", RFC 5056, November 2007. 750 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 751 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 753 [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, 754 April 2010. 756 [RFC5929] Altman, J., Williams, N., and L. Zhu, "Channel Bindings 757 for TLS", RFC 5929, July 2010. 759 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 761 9.2. Informative References 763 [I-D.hammer-hostmeta] 764 Hammer-Lahav, E., "Web Host Metadata", 765 draft-hammer-hostmeta-13 (work in progress), June 2010. 767 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 768 4rev1", RFC 3501, March 2003. 770 Authors' Addresses 772 William Mills 773 Yahoo! Inc. 775 Phone: 776 Email: wmills@yahoo-inc.com 778 Tim Showalter 779 Yahoo! Inc. 781 Phone: 782 Email: timshow@yahoo-inc.com 784 Hannes Tschofenig 785 Nokia Siemens Networks 786 Linnoitustie 6 787 Espoo 02600 788 Finland 790 Phone: +358 (50) 4871445 791 Email: Hannes.Tschofenig@gmx.net 792 URI: http://www.tschofenig.priv.at