idnits 2.17.1 draft-ietf-kitten-sasl-oauth-04.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 : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to use 'NOT RECOMMENDED' as an RFC 2119 keyword, but does not include the phrase in its RFC 2119 key words list. -- The document date (August 20, 2012) is 4266 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) == Unused Reference: 'RFC2616' is defined on line 830, but no explicit reference was found in the text == Unused Reference: 'RFC2617' is defined on line 834, but no explicit reference was found in the text == Unused Reference: 'RFC3174' is defined on line 842, but no explicit reference was found in the text == Unused Reference: 'RFC5246' is defined on line 857, but no explicit reference was found in the text == Unused Reference: 'RFC5988' is defined on line 874, but no explicit reference was found in the text ** 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) ** Downref: Normative reference to an Informational RFC: RFC 3174 ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** 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) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) == Outdated reference: A later version (-05) exists of draft-ietf-oauth-v2-http-mac-01 -- Obsolete informational reference (is this intentional?): RFC 3501 (Obsoleted by RFC 9051) Summary: 8 errors (**), 0 flaws (~~), 9 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 KITTEN W. Mills 3 Internet-Draft Yahoo! Inc. 4 Intended status: Standards Track T. Showalter 5 Expires: February 21, 2013 6 H. Tschofenig 7 Nokia Siemens Networks 8 August 20, 2012 10 A SASL and GSS-API Mechanism for OAuth 11 draft-ietf-kitten-sasl-oauth-04 13 Abstract 15 OAuth enables a third-party application to obtain limited access to a 16 protected resource, either on behalf of a resource owner by 17 orchestrating an approval interaction, or by allowing the third-party 18 application to obtain access on its own behalf. 20 This document defines how an application client uses OAuth over the 21 Simple Authentication and Security Layer (SASL) or the Generic 22 Security Service Application Program Interface (GSS-API) to access a 23 protected resource at a resource serve. Thereby, it enables schemes 24 defined within the OAuth framework for non-HTTP-based application 25 protocols. 27 Clients typically store the user's long term credential. This does, 28 however, lead to significant security vulnerabilities, for example, 29 when such a credential leaks. A significant benefit of OAuth for 30 usage in those clients is that the password is replaced by a token. 31 Tokens typically provided limited access rights and can be managed 32 and revoked separately from the user's long-term credential 33 (password). 35 Status of this Memo 37 This Internet-Draft is submitted in full conformance with the 38 provisions of BCP 78 and BCP 79. 40 Internet-Drafts are working documents of the Internet Engineering 41 Task Force (IETF). Note that other groups may also distribute 42 working documents as Internet-Drafts. The list of current Internet- 43 Drafts is at http://datatracker.ietf.org/drafts/current/. 45 Internet-Drafts are draft documents valid for a maximum of six months 46 and may be updated, replaced, or obsoleted by other documents at any 47 time. It is inappropriate to use Internet-Drafts as reference 48 material or to cite them other than as "work in progress." 49 This Internet-Draft will expire on February 21, 2013. 51 Copyright Notice 53 Copyright (c) 2012 IETF Trust and the persons identified as the 54 document authors. All rights reserved. 56 This document is subject to BCP 78 and the IETF Trust's Legal 57 Provisions Relating to IETF Documents 58 (http://trustee.ietf.org/license-info) in effect on the date of 59 publication of this document. Please review these documents 60 carefully, as they describe your rights and restrictions with respect 61 to this document. Code Components extracted from this document must 62 include Simplified BSD License text as described in Section 4.e of 63 the Trust Legal Provisions and are provided without warranty as 64 described in the Simplified BSD License. 66 Table of Contents 68 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 69 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 8 70 3. OAuth SASL Mechanism Specification . . . . . . . . . . . . . . 9 71 3.1. Initial Client Response . . . . . . . . . . . . . . . . . 9 72 3.1.1. Reserved Key/Values in OAUTH . . . . . . . . . . . . . 10 73 3.1.2. Use of the gs2-header . . . . . . . . . . . . . . . . 11 74 3.2. Server's Response . . . . . . . . . . . . . . . . . . . . 11 75 3.2.1. Mapping to SASL Identities . . . . . . . . . . . . . . 11 76 3.2.2. Server response to failed authentication. . . . . . . 12 77 3.2.3. Completing an error message sequence. . . . . . . . . 12 78 3.3. Use of Signature Type Authorization . . . . . . . . . . . 13 79 3.4. Channel Binding . . . . . . . . . . . . . . . . . . . . . 14 80 4. GSS-API OAuth Mechanism Specification . . . . . . . . . . . . 15 81 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 82 5.1. Successful Bearer Token Exchange . . . . . . . . . . . . . 16 83 5.2. OAuth 1.0a Authorization with Channel Binding . . . . . . 17 84 5.3. Failed Exchange . . . . . . . . . . . . . . . . . . . . . 18 85 5.4. Failed Channel Binding . . . . . . . . . . . . . . . . . . 19 86 5.5. SMTP Example of a failed negotiation. . . . . . . . . . . 19 87 6. Security Considerations . . . . . . . . . . . . . . . . . . . 21 88 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 89 7.1. SASL Registration . . . . . . . . . . . . . . . . . . . . 22 90 7.2. GSS-API Registration . . . . . . . . . . . . . . . . . . . 22 91 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 23 92 8.1. Normative References . . . . . . . . . . . . . . . . . . . 23 93 8.2. Informative References . . . . . . . . . . . . . . . . . . 24 94 Appendix A. Acknowlegements . . . . . . . . . . . . . . . . . . . 25 95 Appendix B. Document History . . . . . . . . . . . . . . . . . . 26 96 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 28 98 1. Introduction 100 OAuth [I-D.ietf-oauth-v2] enables a third-party application to obtain 101 limited access to a protected resource, either on behalf of a 102 resource owner by orchestrating an approval interaction, or by 103 allowing the third-party application to obtain access on its own 104 behalf. The core OAuth specification [I-D.ietf-oauth-v2] does not 105 define the interaction between the client and the resource server 106 with the access to a protected resource using an Access Token. This 107 functionality is described in separate specifications, for example 108 [I-D.ietf-oauth-v2-bearer], [I-D.ietf-oauth-v2-http-mac], and OAuth 109 1.0a [RFC5849] where the focus is on an HTTP-based environment only. 111 Figure 1 shows the abstract message flow as shown in Figure 1 of 112 [I-D.ietf-oauth-v2]. 114 +--------+ +---------------+ 115 | |--(A)- Authorization Request ->| Resource | 116 | | | Owner | 117 | |<-(B)-- Authorization Grant ---| | 118 | | +---------------+ 119 | | 120 | | +---------------+ 121 | |--(C)-- Authorization Grant -->| Authorization | 122 | Client | | Server | 123 | |<-(D)----- Access Token -------| | 124 | | +---------------+ 125 | | 126 | | +---h------------+ 127 | |--(E)----- Access Token ------>| Resource | 128 | | | Server | 129 | |<-(F)--- Protected Resource ---| | 130 +--------+ +---------------+ 132 Figure 1: Abstract OAuth 2.0 Protocol Flow 134 This document takes advantage of the OAuth protocol and its 135 deployment base to provide a way to use SASL [RFC4422] as well as the 136 GSS-API [RFC2743] to gain access to resources when using non-HTTP- 137 based protocols, such as the Internet Message Access Protocol (IMAP) 138 [RFC3501] and SMTP [RFC5321], which is what this memo uses in the 139 examples. 141 The Simple Authentication and Security Layer (SASL) is a framework 142 for providing authentication and data security services in 143 connection-oriented protocols via replaceable mechanisms. It 144 provides a structured interface between protocols and mechanisms. 146 The resulting framework allows new protocols to reuse existing 147 mechanisms and allows old protocols to make use of new mechanisms. 148 The framework also provides a protocol for securing subsequent 149 protocol exchanges within a data security layer. 151 The Generic Security Service Application Program Interface (GSS-API) 152 [RFC2743] provides a framework for applications to support multiple 153 authentication mechanisms through a unified interface. 155 This document defines a SASL mechanism for OAuth, but it conforms to 156 the new bridge between SASL and the GSS-API called GS2 [RFC5801]. 157 This means that this document defines both a SASL mechanism and a 158 GSS-API mechanism. Implementers may be interested in either the 159 SASL, the GSS-API, or even both mechanisms. To faciliate these two 160 variants, the description has been split into two parts, one part 161 that provides normative references for those interested in the SASL 162 OAuth mechanism (see Section 3), and a second part for those 163 implementers that wish to implement the GSS-API portion (see 164 Section 4). 166 When OAuth is integrated into SASL and the GSS-API the high-level 167 steps are as follows: 169 (A) The client requests authorization from the resource owner. 170 The authorization request can be made directly to the resource 171 owner (as shown), or preferably indirectly via the authorization 172 server as an intermediary. 174 (B) The client receives an authorization grant which is a 175 credential representing the resource owner's authorization, 176 expressed using one of four grant types defined in this 177 specification or using an extension grant type. The authorization 178 grant type depends on the method used by the client to request 179 authorization and the types supported by the authorization server. 181 (C) The client requests an access token by authenticating with the 182 authorization server and presenting the authorization grant. 184 (D) The authorization server authenticates the client and 185 validates the authorization grant, and if valid issues an access 186 token. 188 (E) The client requests the protected resource from the resource 189 server and authenticates by presenting the access token. 191 (F) The resource server validates the access token, and if valid, 192 indicates a successful authentication. 194 Steps (E) and (F) are not defined in [I-D.ietf-oauth-v2] and are the 195 main functionality specified within this document. Consequently, the 196 message exchange shown in Figure 2 is the result of this 197 specification. The client will genrally need to determine the 198 authentication endpoints (and perhaps the service endpoints) before 199 the OAuth 2.0 protocol exchange messages in steps (A)-(D) are 200 executed. The discovery of the resource owner and authorization 201 server endpoints is outside the scope of this specification. The 202 client must discover those endpoints using a discovery mechanisms 203 such as Webfinger using host-meta [I-D.jones-appsawg-webfinger]. In 204 band discovery is not tenable if clients support the OAuth 2.0 205 password grant. Once credentials are obtained the client proceeds to 206 steps (E) and (F) defined in this specification. 208 The client need not implement more than one authorization scheme, and 209 there are no mandatory to implement schemes. The server MUST 210 advertise at least one scheme if the OAUTH mechanism is offered. 211 During discovery the client might not find any schemes that it 212 supports, an OAuth 2.0 enabled client MAY attempt to fetch a 213 credential for a scheme it supports from a discovered OAuth 2.0 214 authorization endpoint. If the client finds no schemes it supports 215 the client SHOULD provide feedback to the user that the requested 216 enpoint can not be supported. 218 ----+ 219 +--------+ +---------------+ | 220 | |--(A)-- Authorization Request --->| Resource | | 221 | | | Owner | |Plain 222 | |<-(B)------ Access Grant ---------| | |OAuth 223 | | +---------------+ |2.0 224 | | | 225 | | Client Credentials & +---------------+ | 226 | |--(C)------ Access Grant -------->| Authorization | | 227 | Client | | Server | | 228 | |<-(D)------ Access Token ---------| | | 229 | | (w/ Optional Refresh Token) +---------------+ | 230 | | ----+ 231 | | ----+ 232 | | +---------------+ | 233 | | | | |OAuth 234 | |--(E)------ Access Token -------->| Resource | |over 235 | | | Server | |SASL/ 236 | |<-(F)---- Protected Resource -----| | |GSS- 237 | | | | |API 238 +--------+ +---------------+ | 239 ----+ 241 Figure 2: OAuth SASL Architecture 243 2. Terminology 245 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 246 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 247 document are to be interpreted as described in [RFC2119]. 249 The reader is assumed to be familiar with the terms used in the OAuth 250 2.0 specification [I-D.ietf-oauth-v2]. 252 In examples, "C:" and "S:" indicate lines sent by the client and 253 server respectively. Line breaks have been inserted for readability. 255 Note that the IMAP SASL specification requires base64 encoding 256 message, not this memo. 258 3. OAuth SASL Mechanism Specification 260 SASL is used as a generalized authentication method in a variety of 261 application layer protocols. This document defines two SASL 262 mechanisms for usage with OAuth: "OAUTH" and "OAUTH-PLUS". The 263 "OAUTH" SASL mechanism enables OAuth authorization schemes for SASL, 264 "OAUTH-PLUS" adds channel binding [RFC5056] capability for additional 265 security guarantees. 267 This mechanism is client initiated and lock-step, the server always 268 replying to a client message. In the case where the client has and 269 correctly uses a valid token the flow is: 271 o Client sends a valid and correct initial client response. 273 o Server responds with a successful authentication. 275 In the case where authorization fails the server sends an error 276 result, then client MUST then send an additional message to the 277 server in order to allow the server to finish the exchange. Some 278 protocols and common SASL implementations do not support both sending 279 a SASL message and finalizing a SASL negotiation, the additional 280 client message in the error case deals with this problem. This 281 exchange is: 283 o Client sends an invalid initial client response. 285 o Server responds with an error message. 287 o Client sends an empty client reponse. 289 o Server fails the authentication. 291 3.1. Initial Client Response 293 Client responses are a key/value pair sequence. The initial client 294 response includes a gs2-header as defined in GSS-API [RFC5801], which 295 carries the authorization ID as a hint. These key/value pairs carry 296 the equivalent values from an HTTP context in order to be able to 297 complete an OAuth style HTTP authorization. The client MUST send an 298 authorization ID in the gs2-header. The server MAY use this as a 299 routing or database lookup hint. The server MUST NOT use this as 300 authoritative, the user name MUST be asserted by the OAuth 301 credential. The ABNF [RFC5234] syntax is: 303 kvsep = %x01 304 key = 1*ALPHA 305 value = *(VCHAR | SP | HTAB | CR | LF ) 306 kvpair = key "=" value kvsep 307 client_resp = 0*kvpair kvsep 308 ;; gs2-header = As defined in GSS-API 309 initial_client_resp = gs2-header kvsep client_resp 311 The following key/value pairs are defined in the client response: 313 auth (REQUIRED): The payload of the HTTP Authorization header for 314 an equivalent HTTP OAuth authroization. 316 host: Contains the host name to which the client connected. 318 port: Contains the port number represented as a decimal positive 319 integer string without leading zeros to which the client 320 connected. 322 qs: The HTTP query string. In OAUTH this is reserved, the client 323 SHOUD NOT send it, and has the default value of "". In OAUTH- 324 PLUS this carries a single key value pair "cbdata" for the 325 channel binding data payload formatted as an HTTP query string. 327 In authorization schemes that use signatures, the client MUST send 328 host and port number key/values, and the server MUST fail an 329 authorization request requiring signatures that does not have host 330 and port values. For authorization schemes that require a scheme as 331 part of the URI being signed "http" is always used. 333 3.1.1. Reserved Key/Values in OAUTH 335 In the OAUTH mechanism values for path, query string and post body 336 are assigned default values. OAuth authorization schemes MAY define 337 usage of these in the SASL context and extend this specification. 338 For OAuth schemes that use request signatures the default values MUST 339 be used unless explict values are provided in the client response. 340 The following key values are reserved for future use: 342 mthd (RESERVED): HTTP method for use in signatures, the default 343 value is "POST". 345 path (RESERVED): HTTP path data, the default value is "/". 347 post (RESERVED): HTTP post data, the default value is "". 349 3.1.2. Use of the gs2-header 351 The gs2-header is used as follows: 353 o The "gs2-nonstd-flag" MUST NOT be present. 355 o The "gs2-authzid" carries the authorization identity as specified 356 in [RFC5801]. 358 In the OAUTH mechanism the "gs2-cb-flag" MUST be set to "n" because 359 channel-binding [RFC5056] data is not expected. In the OAUTH-PLUS 360 mechanism the "gs2-cb-flag" MUST be set appropriately by the client. 362 3.2. Server's Response 364 The server validates the response per the specification for the 365 authorization scheme used. If the authorization scheme used includes 366 signing of the request parameters the client must provide a client 367 response that satisfies the data requirements for the scheme in use. 369 In the OAUTH-PLUS mechanism the server examines the channel binding 370 data, extracts the channel binding unique prefix, and extracts the 371 raw channel biding data based on the channel binding type used. It 372 then computes it's own copy of the channel binding payload and 373 compares that to the payload sent by the client in the cbdata key/ 374 value. Those two must be equal for channel binding to succeed. 376 The server responds to a successfully verified client message by 377 completing the SASL negotiation. The authorization scheme MUST carry 378 the user ID to be used as the authorization identity (identity to act 379 as). The server MUST use the ID obtained from the credential as the 380 user being authorized. 382 3.2.1. Mapping to SASL Identities 384 Some OAuth mechanisms can provide both an authorization identity and 385 an authentication identity. An example of this is OAuth 1.0a 386 [RFC5849] where the consumer key (oauth_consumer_key) identifies the 387 entity using the token which equates to the SASL authentication 388 identity, and is authenticated using the shared secret. The 389 authorization identity in the OAuth 1.0a case is carried in the token 390 (per the requirement above), which SHOULD be validated independently. 391 The server MAY use a consumer key, a value derived from it, or other 392 comparable identity in the OAuth authorization scheme as the SASL 393 authentication identity. If an appropriate authentication identity 394 is not available the server MUST use the authorization identity as 395 the authentication identity. 397 3.2.2. Server response to failed authentication. 399 For a failed authentication the server returns a JSON [RFC4627] 400 formatted error result, and fails the authentication. The error 401 result consists of the following values: 403 status (REQUIRED): The authorization error code. Valid error 404 codes are defined in the IANA [[need registry name]] registry 405 specified in the OAuth 2 core specification. 407 schemes (REQUIRED): A space separated list of the OAuth 408 authorization schemes supported by the server, i.e. "bearer" or 409 "bearer mac". 411 scope (OPTIONAL): An OAuth scope which is valid to access the 412 service. This may be empty which implies that unscoped tokens 413 are required, or a space separated list. Use of a space 414 separated list is NOT RECOMMENDED. 416 If the resource server provides a scope the client SHOULD always 417 request scoped tokens from the token endpoint. The client MAY use a 418 scope other than the one provided by the resource server. Scopes 419 other than those advertised by the resource server are be defined by 420 the resource owner and provided in service documentation or discovery 421 information (which is beyond the scope of this memo). If not present 422 then the client SHOULD presume an empty scope (unscoped token) is 423 needed. 425 If channel binding is in use and the channel binding fails the server 426 responds with a status code set to 412 to indicate that the channel 427 binding precondition failed. If the authentication scheme in use 428 does not include signing the server SHOULD revoke the presented 429 credential and the client SHOULD discard that credential. 431 3.2.3. Completing an error message sequence. 433 If the client gets an error message form the server it MUST send an 434 empty client response consisting of a single %x01 (control A) 435 character, which is a correctly formatted client response with no 436 key/value pairs. The server then completes the SASL negotiation with 437 a failure result. 439 3.3. Use of Signature Type Authorization 441 This mechanism supports authorization using signatures, which 442 requires that both client and server construct the string to be 443 signed. OAuth 2 is designed for authentication/authorization to 444 access specific URIs. SASL is designed for user authentication, and 445 has no facility for being more specific. In this mechanism we 446 require or define default values for the data elements from an HTTP 447 request which allow the signature base string to be constructed 448 properly. The default HTTP path is "/" and the default post body is 449 empty. These atoms are defined as extension points so that no 450 changes are needed if there is a revision of SASL which supports more 451 specific resource authorization, e.g. IMAP access to a specific 452 folder or FTP access limited to a specific directory. 454 Using the example in the OAuth 1.0a specification as a starting 455 point, on an IMAP server running on port 143 and given the OAuth 1.0a 456 style authorization request (with %x01 shown as ^A and line breaks 457 added for readability) below: 459 n,a=user@example.com,^A 460 host=example.com^A 461 port=143^A 462 auth=OAuth realm="Example", 463 oauth_consumer_key="9djdj82h48djs9d2", 464 oauth_token="kkk9d7dh3k39sjv7", 465 oauth_signature_method="HMAC-SHA1", 466 oauth_timestamp="137131201", 467 oauth_nonce="7d8f3e4a", 468 oauth_signature="Tm90IGEgcmVhbCBzaWduYXR1cmU%3D"^A^A 470 The signature base string would be constructed per the OAuth 1.0 471 specification [RFC5849] with the following things noted: 473 o The method value is defaulted to POST. 475 o The scheme defaults to be "http", and any port number other than 476 80 is included. 478 o The path defaults to "/". 480 o The query string defaults to "". 482 In this example the signature base string with line breaks added for 483 readability would be: 485 POST&http%3A%2F%2Fexample.com:143%2F&oauth_consumer_key%3D9djdj82h4 486 8djs9d2%26oauth_nonce%3D7d8f3e4a%26oauth_signature_method%3DHMAC-SH 487 A1%26oauth_timestamp%3D137131201%26oauth_token%3Dkkk9d7dh3k39sjv7 489 3.4. Channel Binding 491 The channel binding data is carried in the "qs" (query string) key 492 value pair formatted as a standard HTTP query parameter with the name 493 "cbdata". Channel binding requires that the channel binding data be 494 integrity protected end-to-end in order to protect against man-in- 495 the-middle attacks. All authorization schemes offered in an OAUTH- 496 PLUS mechanism MUST provide integrity protection. It should be noted 497 that while the Bearer token scheme specifies SSL for normal usage it 498 offers no integrity protection and is not suitable for use in OAUTH- 499 PLUS. 501 The channel binding data is computed by the client based on it's 502 choice of preferred channel binding type. As specified in [RFC5056], 503 the channel binding information MUST start with the channel binding 504 unique prefix, followed by a colon (ASCII 0x3A), followed by a base64 505 encoded channel binding payload. The channel binding payload is the 506 raw data from the channel binding type. For example, if the client 507 is using tls-unique for channel binding then the raw channel binding 508 data is the TLS finished message as specified in section 3.1 of 509 [RFC5929]. 511 4. GSS-API OAuth Mechanism Specification 513 Note: The normative references in this section are informational for 514 SASL implementers, but they are normative for GSS-API implementers. 516 The SASL OAuth mechanism is also a GSS-API mechanism and the messages 517 described in Section 3 are the same, but 519 1. the initial context token header is prefixed to the client's 520 first authentication message (context token), as described in 521 Section 3.1 of RFC 2743, 523 The GSS-API mechanism OID for OAuth is [[TBD: IANA]]. 525 OAuth security contexts always have the mutual_state flag 526 (GSS_C_MUTUAL_FLAG) set to TRUE. OAuth supports credential 527 delegation, therefore security contexts may have the deleg_state flag 528 (GSS_C_DELEG_FLAG) set to either TRUE or FALSE. 530 The mutual authentication property of this mechanism relies on 531 successfully comparing the TLS server identity with the negotiated 532 target name. Since the TLS channel is managed by the application 533 outside of the GSS-API mechanism, the mechanism itself is unable to 534 confirm the name while the application is able to perform this 535 comparison for the mechanism. For this reason, applications MUST 536 match the TLS server identity with the target name, as discussed in 537 [RFC6125]. 539 The OAuth mechanism does not support per-message tokens or 540 GSS_Pseudo_random. 542 OAuth supports a standard generic name syntax for acceptors, such as 543 GSS_C_NT_HOSTBASED_SERVICE (see [RFC2743], Section 4.1). These 544 service names MUST be associated with the "entityID" claimed by the 545 RP. OAuth supports only a single name type for initiators: 546 GSS_C_NT_USER_NAME. GSS_C_NT_USER_NAME is the default name type. 547 The query, display, and exported name syntaxes for OAuth principal 548 names are all the same. There is no OAuth-specific name syntax; 549 applications SHOULD use generic GSS-API name types, such as 550 GSS_C_NT_USER_NAME and GSS_C_NT_HOSTBASED_SERVICE (see [RFC2743], 551 Section 4). The exported name token does, of course, conform to 552 [RFC2743], Section 3.2, but the "NAME" part of the token should be 553 treated as a potential input string to the OAuth name normalization 554 rules. 556 5. Examples 558 These example illustrate exchanges between an IMAP client and an IMAP 559 server. 561 Note to implementers: Authorization scheme names are case 562 insensitive. One example uses "Bearer" but that could as easily be 563 "bearer", "BEARER", or "BeArEr". 565 5.1. Successful Bearer Token Exchange 567 This example shows a successful OAuth 2.0 bearer token exchange. 568 Note that line breaks are inserted for readability. 570 S: * IMAP4rev1 Server Ready 571 C: t0 CAPABILITY 572 S: * CAPABILITY IMAP4rev1 AUTH=OAUTH 573 S: t0 OK Completed 574 C: t1 AUTHENTICATE OAUTH bixhPXVzZXJAZXhhbXBsZS5jb20sAWhvc3Q9c2VydmVy 575 LmV4YW1wbGUuY29tAXBvcnQ9MTQzAWF1dGg9QmVhcmVyIHZGOWRmdDRxbVRjMk5 576 2YjNSbGNrQmhiSFJoZG1semRHRXVZMjl0Q2c9PQEB 577 S: t1 OK SASL authentication succeeded 579 As required by IMAP [RFC3501], the payloads are base64-encoded. The 580 decoded initial client response (with %x01 represented as ^A and long 581 lines wrapped for readability) is: 583 n,a=user@example.com,^Ahost=server.example.com^Aport=143^A 584 auth=Bearer vF9dft4qmTc2Nvb3RlckBhbHRhdmlzdGEuY29tCg==^A^A 586 The same credential used in an SMTP exchange is shown below. Note 587 that line breaks are inserted for readability, and that the SMTP 588 protocol terminates lines with CR and LF characters (ASCII values 589 0x0D and 0x0A), these are not displayed explicitly in the example. 591 [connection begins] 592 S: 220 mx.example.com ESMTP 12sm2095603fks.9 593 C: EHLO sender.example.com 594 S: 250-mx.example.com at your service,[172.31.135.47] 595 S: 250-SIZE 35651584 596 S: 250-8BITMIME 597 S: 250-AUTH LOGIN PLAIN OAUTH 598 S: 250-ENHANCEDSTATUSCODES 599 S: 250-PIPELINING 600 C: t1 AUTHENTICATE OAUTH bixhPXVzZXJAZXhhbXBsZS5jb20sAWhvc3Q9c2VydmVy 601 LmV4YW1wbGUuY29tAXBvcnQ9MTQzAWF1dGg9QmVhcmVyIHZGOWRmdDRxbVRjMk5 602 2YjNSbGNrQmhiSFJoZG1semRHRXVZMjl0Q2c9PQEB 603 S: 235 Authentication successful. 604 [connection continues...] 606 5.2. OAuth 1.0a Authorization with Channel Binding 608 This example shows channel binding in the context of an OAuth 1.0a 609 signed authorization request. Note that line breaks are inserted for 610 readability. 612 S: * CAPABILITY IMAP4rev1 AUTH=OAUTH SASL-IR IMAP4rev1 Server Ready 613 S: t0 OK Completed 614 C: t1 AUTHENTICATE OAUTH-PLUS eSxhPXVzZXJAZXhhbXBsZS5jb20sAWhvc3Q9c2Vydm 615 VyLmV4YW1wbGUuY29tAXBvcnQ9MTQzAWF1dGg9T0F1dGggcmVhbG09IkV4YW1wbGUi 616 LG9hdXRoX2NvbnN1bWVyX2tleT0iOWRqZGo4Mmg0OGRqczlkMiIsb2F1dGhfdG9rZW 617 49ImtrazlkN2RoM2szOXNqdjciLG9hdXRoX3NpZ25hdHVyZV9tZXRob2Q9IkhNQUMt 618 U0hBMSIsb2F1dGhfdGltZXN0YW1wPSIxMzcxMzEyMDEiLG9hdXRoX25vbmNlPSI3ZD 619 hmM2U0YSIsb2F1dGhfc2lnbmF0dXJlPSJTU2R0SUdFZ2JHbDBkR3hsSUhSbFlTQndi 620 M1F1IgFxcz1jYmRhdGE9dGxzLXVuaXF1ZTpTRzkzSUdKcFp5QnBjeUJoSUZSTVV5Qm 621 1hVzVoYkNCdFpYTnpZV2RsUHdvPQEB 622 S: t1 OK SASL authentication succeeded 624 As required by IMAP [RFC3501], the payloads are base64-encoded. The 625 decoded initial client response (with %x01 represented as ^A and 626 lines wrapped for readability) is: 628 y,a=user@example.com,^A 629 host=server.example.com^A 630 port=143^A 631 auth=OAuth realm="Example", 632 oauth_consumer_key="9djdj82h48djs9d2", 633 oauth_token="kkk9d7dh3k39sjv7", 634 oauth_signature_method="HMAC-SHA1", 635 oauth_timestamp="137131201", 636 oauth_nonce="7d8f3e4a", 637 oauth_signature="SSdtIGEgbGl0dGxlIHRlYSBwb3Qu"^A 638 qs=cbdata=tls-unique:SG93IGJpZyBpcyBhIFRMUyBmaW5hbCBtZXNzYWdlPwo=^A^A 640 In this example the signature base string with line breaks added for 641 readability would be: 643 POST&http%3A%2F%2Fserver.example.com:143%2F&cbdata=tls-unique:SG93I 644 GJpZyBpcyBhIFRMUyBmaW5hbCBtZXNzYWdlPwo=%26oauth_consumer_key%3D9djd 645 j82h48djs9d2%26oauth_nonce%3D7d8f3e4a%26oauth_signature_method%3DHM 646 AC-SHA1%26oauth_timestamp%3D137131201%26oauth_token%3Dkkk9d7dh3k39s 647 jv7 649 5.3. Failed Exchange 651 This example shows a failed exchange because of the empty 652 Authorization header, which is how a client can query for the needed 653 scope. Note that line breaks are inserted for readability. 655 S: * CAPABILITY IMAP4rev1 AUTH=OAUTH SASL-IR IMAP4rev1 Server Ready 656 S: t0 OK Completed 657 C: t1 AUTHENTICATE OAUTH bixhPXVzZXJAZXhhbXBsZS5jb20sAWhvc3Q9c2Vy 658 dmVyLmV4YW1wbGUuY29tAXBvcnQ9MTQzAWF1dGg9AQE= 659 S: + ewoic3RhdHVzIjoiNDAxIiwKInNjaGVtZXMiOiJiZWFyZXIiLAoic2NvcGUi 660 OiJleGFtcGxlX3Njb3BlIgp9 661 C: + AQ== 662 S: t1 NO SASL authentication failed 664 The decoded initial client response is: 666 n,a=user@example.com,^Ahost=server.example.com^Aport=143^Aauth=^A^A 668 The decoded server error response is: 670 { 671 "status":"401", 672 "schemes":"bearer", 673 "scope":"example_scope" 674 } 676 The client responds with the required empty response. 678 5.4. Failed Channel Binding 680 This example shows a channel binding failure in an empty request. 681 The channel binding information is empty. Note that line breaks are 682 inserted for readability. 684 S: * CAPABILITY IMAP4rev1 AUTH=OAUTH OAUTH-PLUS SASL-IR IMAP4rev1 Server 685 Ready 686 S: t0 OK Completed 687 C: t1 AUTHENTICATE OAUTH-PLUS eSxhPXVzZXJAZXhhbXBsZS5jb20sAWhvc3Q9c2Vydm 688 VyLmV4YW1wbGUuY29tAXBvcnQ9MTQzAWF1dGg9AWNiZGF0YT0BAQ== 689 S: + ewoic3RhdHVzIjoiNDEyIiwKInNjaGVtZXMiOiJiZWFyZXIgb2F1dGgiLAoi 690 c2NvcGUiOiJleGFtcGxlX3Njb3BlIgp9 691 C: + AQ== 692 S: t1 NO SASL authentication failed 694 The decoded initial client response is: 696 y,a=user@example.com,^A 697 host=server.example.com^Aport=143^A 698 auth=^Acbdata=^A^A 700 The decoded server response is: 702 { 703 "status":"412", 704 "schemes":"bearer oauth", 705 "scope":"example_scope" 706 } 708 The client responds with the required empty response. 710 5.5. SMTP Example of a failed negotiation. 712 This example shows an authorization failure in an SMTP exchange. 713 Note that line breaks are inserted for readability, and that the SMTP 714 protocol terminates lines with CR and LF characters (ASCII values 715 0x0D and 0x0A), these are not displayed explicitly in the example. 717 [connection begins] 718 S: 220 mx.example.com ESMTP 12sm2095603fks.9 719 C: EHLO sender.example.com 720 S: 250-mx.example.com at your service,[172.31.135.47] 721 S: 250-SIZE 35651584 722 S: 250-8BITMIME 723 S: 250-AUTH LOGIN PLAIN OAUTH 724 S: 250-ENHANCEDSTATUSCODES 725 S: 250-PIPELINING 726 C: AUTH OAUTH dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB2RjlkZn 727 Q0cW1UYzJOdmIzUmxja0JoZEhSaGRtbHpkR0V1WTI5dENnPT0BAQo= 728 S: 334 eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb3BlIjoia 729 HR0cHM6Ly9tYWlsLmdvb2dsZS5jb20vIn0K 730 C: AQ== 731 S: 535-5.7.1 Username and Password not accepted. Learn more at 732 S: 535 5.7.1 http://support.example.com/mail/oauth 733 [connection continues...] 735 The client responds with the required empty response. 737 6. Security Considerations 739 This mechanism does not provide a security layer, but does provide a 740 provision for channel binding. The OAuth 2 specification 741 [I-D.ietf-oauth-v2] allows for a variety of usages, and the security 742 properties of these profiles vary. The usage of bearer tokens, for 743 example, provide security features similar to cookies. Applications 744 using this mechanism SHOULD exercise the same level of care using 745 this mechanism as they would in using the SASL PLAIN mechanism. In 746 particular, TLS 1.2 or an equivalent secure channel MUST be 747 implemented and its usage is RECOMMENDED. 749 The channel binding in this mechanism has different properties based 750 on the authentication scheme used. The integrity guarantee for 751 channel binding depends on the quality of the guarantee in the the 752 authorization scheme. 754 It is possible that SASL will be authenticating a connection and the 755 life of that connection may outlast the life of the token used to 756 authenticate it. This is a common problem in application protocols 757 where connections are long-lived, and not a problem with this 758 mechanism per se. Servers MAY unilaterally disconnect clients in 759 accordance with the application protocol. 761 An OAuth credential is not equivalent to the password or primary 762 account credential. There are protocols like XMPP that allow actions 763 like change password. The server SHOULD ensure that actions taken in 764 the authenticated channel are appropriate to the strength of the 765 presented credential. 767 Tokens have a lifetime associated with them. Reducing the lifetime 768 of a token provides security benefits in the case that tokens leak. 769 In addition a previously obtained token MAY be revoked or rendered 770 invalid at any time. The client MAY request a new access token for 771 each connection to a resource server, but it SHOULD cache and re-use 772 access credentials that appear to be valid. 774 7. IANA Considerations 776 7.1. SASL Registration 778 The IANA is requested to register the following SASL profile: 780 SASL mechanism profile: OAUTH 782 Security Considerations: See this document 784 Published Specification: See this document 786 For further information: Contact the authors of this document. 788 Owner/Change controller: the IETF 790 Note: None 792 The IANA is requested to register the following SASL profile: 794 SASL mechanism profile: OAUTH-PLUS 796 Security Considerations: See this document 798 Published Specification: See this document 800 For further information: Contact the authors of this document. 802 Owner/Change controller: the IETF 804 Note: None 806 7.2. GSS-API Registration 808 IANA is further requested to assign an OID for this GSS mechanism in 809 the SMI numbers registry, with the prefix of 810 iso.org.dod.internet.security.mechanisms (1.3.6.1.5.5) and to 811 reference this specification in the registry. 813 8. References 815 8.1. Normative References 817 [I-D.ietf-oauth-v2] 818 Hardt, D., "The OAuth 2.0 Authorization Framework", 819 draft-ietf-oauth-v2-31 (work in progress), August 2012. 821 [I-D.ietf-oauth-v2-bearer] 822 Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 823 Framework: Bearer Token Usage", 824 draft-ietf-oauth-v2-bearer-23 (work in progress), 825 August 2012. 827 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 828 Requirement Levels", BCP 14, RFC 2119, March 1997. 830 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 831 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 832 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 834 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 835 Leach, P., Luotonen, A., and L. Stewart, "HTTP 836 Authentication: Basic and Digest Access Authentication", 837 RFC 2617, June 1999. 839 [RFC2743] Linn, J., "Generic Security Service Application Program 840 Interface Version 2, Update 1", RFC 2743, January 2000. 842 [RFC3174] Eastlake, D. and P. Jones, "US Secure Hash Algorithm 1 843 (SHA1)", RFC 3174, September 2001. 845 [RFC4422] Melnikov, A. and K. Zeilenga, "Simple Authentication and 846 Security Layer (SASL)", RFC 4422, June 2006. 848 [RFC4627] Crockford, D., "The application/json Media Type for 849 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 851 [RFC5056] Williams, N., "On the Use of Channel Bindings to Secure 852 Channels", RFC 5056, November 2007. 854 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 855 Specifications: ABNF", STD 68, RFC 5234, January 2008. 857 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 858 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 860 [RFC5321] Klensin, J., "Simple Mail Transfer Protocol", RFC 5321, 861 October 2008. 863 [RFC5801] Josefsson, S. and N. Williams, "Using Generic Security 864 Service Application Program Interface (GSS-API) Mechanisms 865 in Simple Authentication and Security Layer (SASL): The 866 GS2 Mechanism Family", RFC 5801, July 2010. 868 [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, 869 April 2010. 871 [RFC5929] Altman, J., Williams, N., and L. Zhu, "Channel Bindings 872 for TLS", RFC 5929, July 2010. 874 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 876 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 877 Verification of Domain-Based Application Service Identity 878 within Internet Public Key Infrastructure Using X.509 879 (PKIX) Certificates in the Context of Transport Layer 880 Security (TLS)", RFC 6125, March 2011. 882 8.2. Informative References 884 [I-D.ietf-oauth-v2-http-mac] 885 Hammer-Lahav, E., "HTTP Authentication: MAC Access 886 Authentication", draft-ietf-oauth-v2-http-mac-01 (work in 887 progress), February 2012. 889 [I-D.jones-appsawg-webfinger] 890 Jones, P., Salgueiro, G., and J. Smarr, "WebFinger", 891 draft-jones-appsawg-webfinger-06 (work in progress), 892 June 2012. 894 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 895 4rev1", RFC 3501, March 2003. 897 Appendix A. Acknowlegements 899 The authors would like to thank the members of the Kitten working 900 group, and in addition and specifically: Simon Josefson, Torsten 901 Lodderstadt, Ryan Troll, and Nico Williams. 903 Appendix B. Document History 905 [[ to be removed by RFC editor before publication as an RFC ]] 907 -04 909 o Changed user field to be carried in the gs2-header, and made gs2 910 header explicit in all cases. 912 o Converted MAC examples to OAuth 1.0a. Moved MAC to an informative 913 reference. 915 o Changed to sending an empty client response (single control-A) as 916 the second message of a failed sequence. 918 o Fixed channel binding prose to refer to the normative specs and 919 removed the hashing of large channel binding data, which brought 920 mroe problems than it solved. 922 o Added a SMTP examples for Bearer use case. 924 -03 926 o Added user field into examples and fixed egregious errors there as 927 well. 929 o Added text reminding developers that Authorization scheme names 930 are case insensitive. 932 -02 934 o Added the user data element back in. 936 o Minor editorial changes. 938 -01 940 o Ripping out discovery. Changed to refer to I-D.jones-appsawg- 941 webfinger instead of WF and SWD older drafts. 943 o Replacing HTTP as the message format and adjusted all examples. 945 -00 947 o Renamed draft into proper IETF naming format now that it's 948 adopted. 950 o Minor fixes. 952 Authors' Addresses 954 William Mills 955 Yahoo! Inc. 957 Phone: 958 Email: wmills@yahoo-inc.com 960 Tim Showalter 962 Phone: 963 Email: tjs@psaux.com 965 Hannes Tschofenig 966 Nokia Siemens Networks 967 Linnoitustie 6 968 Espoo 02600 969 Finland 971 Phone: +358 (50) 4871445 972 Email: Hannes.Tschofenig@gmx.net 973 URI: http://www.tschofenig.priv.at