idnits 2.17.1
draft-ideskog-assisted-token-05.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 (9 March 2021) is 1141 days in the past. Is this
intentional?
Checking references for intended status: Informational
----------------------------------------------------------------------------
-- Obsolete informational reference (is this intentional?): RFC 5849
(Obsoleted by RFC 6749)
Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 2 comments (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 Independent Submission J. Ideskog
3 Internet-Draft T. Spencer
4 Intended status: Informational Curity AB
5 Expires: 10 September 2021 9 March 2021
7 OAuth 2.0 Assisted Token
8 draft-ideskog-assisted-token-05
10 Abstract
12 This document extends the OAuth 2.0 framework to include an
13 additional authorization flow for single page applications called the
14 assisted token flow. It enables OAuth clients written in scripting
15 languages, like JavaScript, to request user authorization using a
16 simplified method compared to other flows. Communication does not
17 rely on redirection of the user agent, but instead leverages HTML's
18 iframe element, child windows, and the postMessage interface. This
19 communication is done using an additional endpoint, the assisted
20 token endpoint.
22 Note
24 To contribute to this draft, please feel free to create a pull
25 request from the original source available at
26 https://github.com/curityio/rfc (https://github.com/curityio/rfc/) or
27 email the authors.
29 This note is to be removed before publishing as an RFC.
31 Status of This Memo
33 This Internet-Draft is submitted in full conformance with the
34 provisions of BCP 78 and BCP 79.
36 Internet-Drafts are working documents of the Internet Engineering
37 Task Force (IETF). Note that other groups may also distribute
38 working documents as Internet-Drafts. The list of current Internet-
39 Drafts is at https://datatracker.ietf.org/drafts/current/.
41 Internet-Drafts are draft documents valid for a maximum of six months
42 and may be updated, replaced, or obsoleted by other documents at any
43 time. It is inappropriate to use Internet-Drafts as reference
44 material or to cite them other than as "work in progress."
46 This Internet-Draft will expire on 10 September 2021.
48 Copyright Notice
50 Copyright (c) 2021 IETF Trust and the persons identified as the
51 document authors. All rights reserved.
53 This document is subject to BCP 78 and the IETF Trust's Legal
54 Provisions Relating to IETF Documents (https://trustee.ietf.org/
55 license-info) in effect on the date of publication of this document.
56 Please review these documents carefully, as they describe your rights
57 and restrictions with respect to this document.
59 Table of Contents
61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
62 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
63 3. Assisted Token Endpoint . . . . . . . . . . . . . . . . . . . 6
64 3.1. Access Token Scope . . . . . . . . . . . . . . . . . . . 7
65 3.2. Cross-Origin Support . . . . . . . . . . . . . . . . . . 7
66 4. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 7
67 4.1. Assisted Token Request . . . . . . . . . . . . . . . . . 7
68 4.2. Assisted Token Response . . . . . . . . . . . . . . . . . 8
69 4.3. Error Response . . . . . . . . . . . . . . . . . . . . . 9
70 5. Client Metadata . . . . . . . . . . . . . . . . . . . . . . . 11
71 6. Authorization Server Metadata . . . . . . . . . . . . . . . . 11
72 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
73 7.1. OAuth URI Registration . . . . . . . . . . . . . . . . . 12
74 7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 12
75 7.2. OAuth Parameters . . . . . . . . . . . . . . . . . . . . 12
76 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 12
77 7.3. OAuth 2.0 Authorization Server Metadata . . . . . . . . . 13
78 7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 13
79 8. Security Considerations . . . . . . . . . . . . . . . . . . . 13
80 8.1. Framing . . . . . . . . . . . . . . . . . . . . . . . . . 13
81 8.2. WebAuthn . . . . . . . . . . . . . . . . . . . . . . . . 15
82 8.3. Handle Tokens . . . . . . . . . . . . . . . . . . . . . . 15
83 8.4. Warning Against Untrusted Scripts . . . . . . . . . . . . 15
84 8.5. Origin of Event and Authorization Server . . . . . . . . 16
85 8.6. Token Storage . . . . . . . . . . . . . . . . . . . . . . 16
86 9. Privacy Considerations . . . . . . . . . . . . . . . . . . . 17
87 10. Normative References . . . . . . . . . . . . . . . . . . . . 17
88 11. Informative References . . . . . . . . . . . . . . . . . . . 18
89 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 19
90 Appendix B. Document History . . . . . . . . . . . . . . . . . . 19
91 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 20
93 1. Introduction
95 The OAuth 2.0 protocol flow for Single-page Applications (SPA)
96 defined in this memo, often referred to as the assisted token flow,
97 provides clients written in scripting languages, like JavaScript,
98 with a simplified integration (compared to the implicit or
99 authorization code flow) and ensures that end users are not
100 redirected away from the current page in order to obtain
101 authorization from the resource owner. The communication between the
102 client and the authorization server takes place within an HTML iframe
103 element or child window that is only displayed when interactive user
104 interaction is required; this is the case when authentication and/or
105 authorization are necessary. To communicate the result from this
106 iframe or child window to the client application, HTML's postMessage
107 interface is used instead of the redirection endpoint defined in
108 Section 3.1.2 of [RFC6749]. This difference is important for many
109 SPAs which take time to reload and may not be able to recreate the
110 same state prior to the user being redirected to the authorization
111 server.
113 Another goal of the assisted token flow is to simplify integration of
114 the client with the authorization server. Though [RFC6749] resulted
115 in a much simpler integration for client applications compared to its
116 predecessor, [RFC5849], developers still struggle with the many
117 inputs required to perform the various OAuth flows. For this reason,
118 the assisted token flow introduces a new endpoint called the assisted
119 token endpoint rather than extending and reusing the token endpoint
120 defined in Section 3.2 of [RFC6749]. As a result, client developers
121 do not need to specify a response_type parameter in the authorization
122 request. This coupled with the use of HTML's postMessage interface
123 for communication between the client and the authorization server
124 means that the redirect_uri and state parameters are also
125 unnecessary. Consequently, client developers only need to provide a
126 client_id, create a dynamic iframe or open a child window, and handle
127 the postMessage that is fired by the authorization server in order to
128 implement OAuth.
130 This interaction is shown in Figure 1.
132 +----------------------------+ +---------------+
133 | Client | | Authorization |
134 | +--------------------------+ | Server |
135 | | +-----------+ | |
136 | |--(A)-------->| |--(B)-- Client ------>| |
137 | | | | Identifier | |
138 | | | Hidden | | |
139 | | | iframe |<-(C)-- HTML with ----| |
140 | |<-(D)- Token -| | postMessage | |
141 | | or | | including | |
142 | | error +-----------+ access token | |
143 | +--------------------------+ or error | |
144 | | | |
145 +----------------------------+ +---------------+
147 Figure 1: Assisted Token Flow
149 The assisted token flow illustrated in Figure 1 includes the
150 following steps:
152 (A) The client creates a hidden iframe element using a scripting
153 language like JavaScript. The src attribute of this iframe is
154 the URL of the assisted token endpoint of the authorization
155 server.
157 (B) The query string of the src attribute on the iframe includes, at
158 a minimum, the client identifier.
160 (C) If the user is already logged in and has granted consent to the
161 client, the authorization server immediately returns an HTML
162 document that includes a script that is executing; this fires an
163 event which is communicated to the client using an HTML
164 window.postMessage.
166 (D) The client handles this event -- the payload of which is either
167 an access token or an error; the client then closes the dynamic
168 iframe without revealing it to the user.
170 If the resource owner has not authenticated or has not authorized the
171 client, then interaction between the resource owner and the
172 authorization server is required to obtain these. In such a case,
173 the HTML in step (C) of Figure 1 will include an error indicating
174 that user involvement is required. This will be handled by the
175 client in step (D) and login and/or consent will commence. This
176 process is illustrated in Figure 2.
178 +----------------------------+ +---------------+
179 | Client | | Authorization |
180 | +--------------------------+ | Server |
181 | | +-----------+ Client | |
182 | |--(E)-------->| |--(F)-- Identifier -->| |
183 | | | Visible | | |
184 | | | iframe |--(G)-- User -------->| |
185 | | | or child | interaction | |
186 | |<-(I)- Token -| window | | |
187 | | | |<-(H)-- HTML with ----| |
188 | | +-----------+ postMessage | |
189 | +--------------------------+ including | |
190 | | access token | |
191 +----------------------------+ +---------------+
193 Figure 2: Assisted Token Login and/or Consent Flow
195 The flow shown in Figure 2 includes the following steps:
197 (E) The client creates a "visible" iframe or pops open a child
198 window after receiving an indication from the authorization
199 server that user interaction is required. As in the previous
200 flow, the src attribute value of this iframe or the input to the
201 open method of the user agents's window object is the URL of the
202 authorization server's assisted token endpoint.
204 (F) The query string of this URL includes, at a minimum, the client
205 identifier.
207 (G) The authorization server prompts the resource owner to
208 authenticate and/or authorize the client.
210 (H) The authorization server returns an HTML document that includes
211 a script that is executed; this fires an event which is
212 communicated to the client using an HTML window.postMessage.
214 (I) The client handles this event -- the payload of which is an
215 access token; the client then closes the iframe or child window
216 that it previously opened to facilitate user interaction.
218 2. Terminology
220 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
221 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
222 "OPTIONAL" in this document are to be interpreted as described in
223 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
224 capitals, as shown here.
226 Handle Token
227 An opaque token that refers to internal data of the
228 authorization server (e.g., the user ID, scope of the token,
229 etc.) as described in Section 3.1 of [RFC6819].
231 All other terms used in this document are as defined in [RFC6749].
232 Unless otherwise noted, all the protocol parameter names and values
233 are case sensitive.
235 3. Assisted Token Endpoint
237 The means through which the client obtains the location of the
238 assisted token endpoint is either by using the authorization server's
239 metadata as set forth in Section 6, the service documentation, or
240 some other method that is beyond the scope of this specification.
242 The endpoint URI MAY include an "application/x-www-form-urlencoded"
243 formatted (per Appendix B of [RFC6749]) query component (see
244 Section 3.4 of [RFC3986]), which MUST be retained when adding
245 additional query parameters. The endpoint URI MUST NOT include a
246 fragment component.
248 Since requests to the assisted token endpoint result in the
249 transmission of clear-text credentials (in the HTTP request and
250 response), the authorization server MUST require the use of TLS as
251 described in Section 1.6 of [RFC6749] when sending requests to the
252 assisted token endpoint.
254 The client MUST use the HTTP "GET" method when making access token
255 requests to this endpoint.
257 Parameters sent without a value MAY be treated as if they were
258 omitted from the request. The authorization server MUST ignore
259 unrecognized request parameters. Request and response parameters
260 MUST NOT be included more than once.
262 After completing its interaction with the resource owner, the
263 authorization server will fire an event using the HTML postMessage
264 interface. This message MUST NOT be posted to all origins, denoted
265 by "*". Instead, the authorization server MUST post this message
266 only to the client's allowed origin(s) previously established with
267 the authorization server during the client registration process.
269 3.1. Access Token Scope
271 Like the authorization and token endpoints, the assisted token
272 endpoint allows the client to specify the scope of the access request
273 using the "scope" request parameter. In turn, the authorization
274 server uses the "scope" response parameter to inform the client of
275 the scope of the access token issued. Unlike the typical behavior of
276 those endpoints, however, access tokens issued by the authorization
277 server using the assisted token endpoint MUST use the client's pre-
278 configured scope or the authorization server's pre-defined default if
279 none have been configured for the client.
281 If the client did not include a "scope" request parameter or if the
282 issued access token scope is different from the one requested by the
283 client, the authorization server MUST include the "scope" response
284 parameter to inform the client of the actual scope granted. Even
285 when the scope of the issued access token is the same as the one
286 requested by the client, the authorization server SHOULD include the
287 "scope" response parameter.
289 The format, constraints, and grammar of the scope parameter value is
290 as defined in Section 3.3 of [RFC6749].
292 The authorization server SHOULD NOT return an error if a scope has
293 not been pre-configured for the client; only if the authorization
294 server does not have a pre-defined default scope.
296 3.2. Cross-Origin Support
298 The assisted token endpoint MAY support CORS as defined in
299 [W3C.WD-cors-20120403].
301 4. Protocol
303 4.1. Assisted Token Request
305 The assisted token request is an HTTP GET request constructed by the
306 client with the following parameters provided on the query string:
308 client_id
309 REQUIRED. The client identifier as described in Section 2.2
310 of [RFC6749].
312 for_origin
313 OPTIONAL. The origin of the client in case multiple allowed
314 origins are configured with the authorization server and
315 support for user agents that do not support [CSP-2] but only
316 "X-Frame-Options" (as defined in [RFC7034]). See Section 8.1
317 for details.
319 prompt
320 OPTIONAL. Space delimited, case sensitive list of [ASCII]
321 string values that can be used to determine the login state
322 of the resource owner at the authorization server. The
323 defined values are:
325 none
326 The authorization server MUST NOT display any
327 authentication or consent user interface pages. An
328 error is returned if the user is not already
329 authenticated or if the client has not received
330 consent (either explicitly by the resource owner or
331 by the authorization server's configuration of the
332 client) or if the authorization server cannot fulfill
333 other conditions for processing. This can be used as
334 a method to probing for existing authentication and/
335 or consent.
337 consent
338 The authorization server SHOULD prompt the user for
339 consent before returning information to the client.
340 If it cannot obtain consent, it MUST return an error.
342 Other values may be provided in this list; the authorization
343 server MUST ignore them without producing an error if it
344 cannot understand them.
346 scope
347 OPTIONAL. The scope of the access request as described in
348 Section 3.1.
350 4.2. Assisted Token Response
352 The response from the assisted token endpoint is an HTML document
353 that executes a script which invokes the HTML postMessage interface
354 to send a message to either the parent window (in the case shown in
355 Figure 1) or the opener. The origin that this event is posted to is
356 that of the client. The contents of this message is a JSON object
357 with the following fields:
359 access_token
360 REQUIRED. The access token issued by the authorization
361 server.
363 expires_in
364 RECOMMENDED. The lifetime in seconds of the access token.
366 scope
367 REQUIRED. The scope of the access token as described in
368 Section 3.1.
370 sub
371 RECOMMENDED. A locally unique and never reassigned
372 identifier within the authorization server for the user,
373 which is intended to be consumed by the client. The sub
374 value is a case sensitive string.
376 token_type
377 REQUIRED. The type of the token issued as described in
378 Section 7.1 of [RFC6749]. The value is case insensitive.
380 This JSON object MAY contain additional fields. If the client does
381 not understand or recognize such additional fields, it MUST ignore
382 them.
384 4.3. Error Response
386 As with a successful response, an error is returned to the client
387 using an the HTML postMessage interface. Such an error is returned
388 whenever the resource owner denies the access request or whenever the
389 request fails for reasons other than the origin of the client being
390 disallowed to frame the assisted token endpoint. The error message
391 includes a JSON object with the following fields:
393 error
394 REQUIRED. A single [ASCII] error code from the following:
396 invalid_request
397 The request is missing a required parameter, includes
398 an invalid parameter value, includes a parameter more
399 than once, or is otherwise malformed.
401 unauthorized_client
402 The client is not authorized to request an access
403 token using this method.
405 access_denied
406 The resource owner or authorization server denied the
407 request.
409 consent_required
410 The client includes a prompt value of consent, but
411 consent by the resource owner was required.
413 interaction_required
414 The client included a prompt value of none, but
415 either the user needed to authenticate or consent to
416 the client's access or some other requirement of the
417 authorization server prevented it from providing
418 access without some form of user interaction.
420 unsupported_response_type
421 The authorization server does not support obtaining
422 an access token using this method.
424 invalid_scope
425 The requested scope is invalid, unknown, or
426 malformed.
428 server_error
429 The authorization server encountered an unexpected
430 condition that prevented it from fulfilling the
431 request. (This error code is needed because a 500
432 Internal Server Error HTTP status code cannot be
433 returned to the client directly.)
435 temporarily_unavailable
436 The authorization server is currently unable to
437 handle the request due to a temporary overloading or
438 maintenance of the server. (This error code is
439 needed because a 503 Service Unavailable HTTP status
440 code cannot be returned to the client directly.)
442 Values for the "error" parameter MUST NOT include characters
443 outside the set %x20-21 / %x23-5B / %x5D-7E.
445 error_description
446 OPTIONAL. Human-readable [ASCII] text providing additional
447 information, used to assist the client developer in
448 understanding the error that occurred. Values for the
449 "error_description" parameter MUST NOT include characters
450 outside the set %x20-21 / %x23-5B / %x5D-7E.
452 error_uri
453 OPTIONAL. A URI identifying a human-readable web page with
454 information about the error, used to provide the client
455 developer with additional information about the error.
456 Values for the "error_uri" parameter MUST conform to the URI-
457 reference syntax and thus MUST NOT include characters outside
458 the set %x21 / %x23-5B / %x5D-7E.
460 5. Client Metadata
462 The authorization server MAY allow dynamic clients to request the use
463 of the assisted token flow when registering. Such a client may
464 indicate that it will interact with the authorization server using
465 the assisted token flow by including the string element
466 "urn:ietf:params:oauth:grant-type:assisted_token" in the array
467 associated with the "grant_types" metadata field sent to the client
468 registration endpoint (as defined in Section 3 of [RFC7591]). If the
469 authorization server allows the client to register with this grant
470 type, the "grant_types" included in the response MUST include the
471 value "urn:ietf:params:oauth:grant-type:assisted_token". The
472 inclusion of this value in the "grant_types" field is done despite
473 the fact that the client will not use this grant type at the token
474 endpoint but rather the assisted token endpoint (see Section 3).
476 If dynamic clients are allowed to register themselves with the
477 authorization server, then additional verification of the origins
478 include in the request MUST be performed in some manner. The way in
479 which this is accomplished by the authorization server is not defined
480 by this specification. Because this additional verification is
481 required and because clients using the assisted token flow are
482 typically ephemeral in nature, it is NOT RECOMMENDED that the
483 authorization server support dynamic client registration of the
484 "urn:ietf:params:oauth:grant-type:assisted_token" grant type.
486 The following client metadata field is defined by this specification.
487 It MAY be included in a registration request, as set forth in
488 Section 2 of [RFC7591].
490 allowed_origins
491 Array of origin strings for use in sending messages from the
492 authorization server to the client using the HTML's
493 postMessage interface.
495 6. Authorization Server Metadata
497 Support for the assisted token flow SHOULD be declared in the
498 authorization server's metadata (as defined in [RFC8414]) with the
499 following metadata:
501 assisted_token_endpoint
502 RECOMMENDED. URL of the authorization server's assisted
503 token endpoint defined in Section 3.
505 grant_types_supported
506 RECOMMENDED. A JSON array specified in Section 2 of
507 [RFC8414] which SHOULD contain the value
508 "urn:ietf:params:oauth:grant-type:assisted_token" as defined
509 in Section 5.
511 7. IANA Considerations
513 7.1. OAuth URI Registration
515 This specification registers the following values in the IANA "OAuth
516 URI" registry (https://www.iana.org/assignments/oauth-
517 parameters/#uri) [IANA.OAuth.Parameters] established by [RFC6755].
519 7.1.1. Registry Contents
521 * URN: urn:ietf:params:oauth:grant-type:assisted_token
523 * Common Name: Assisted token flow grant type for OAuth 2.0
525 * Change controller: CURITY: info@curity.io
527 * Specification Document: Section 5 of [[ this specification ]]
529 7.2. OAuth Parameters
531 This specification registers the following values in the IANA "OAuth
532 Parameter" registry (https://www.iana.org/assignments/oauth-
533 parameters/#parameters) [IANA.OAuth.Parameters] established by
534 [RFC6749].
536 7.2.1. Registry Contents
538 * for_origin
540 * Parameter usage location: authorization request
542 * Change controller: CURITY: info@curity.io
544 * Specification Document: Section 4 of [[ this specification ]]
546 7.3. OAuth 2.0 Authorization Server Metadata
548 This specification registers the following values in the IANA "OAuth
549 2.0 Authorization Server Metadata" registry
550 (https://www.iana.org/assignments/oauth-parameters/#authorization-
551 server-metadata) [IANA.OAuth.Parameters] established by [RFC8414].
553 7.3.1. Registry Contents
555 * Metadata name: assisted_token_endpoint
557 * Metadata Description: The Assisted Token Endpoint.
559 * Change controller: CURITY: info@curity.io
561 * Specification Document: Section 6 of [[ this specification ]]
563 8. Security Considerations
565 In addition to all the security considerations discussed in
566 [RFC6819], the following security considerations SHOULD be taken into
567 account.
569 8.1. Framing
571 Due to the use of an iframe to host the assisted token endpoint, the
572 authorization server MUST take precautions to ensure that only
573 trusted origins are allowed to frame it. The authorization server
574 MUST prevent any origin from framing the assisted token endpoint
575 except ones deemed trustworthy. This attestation may come byway of
576 explicit administrative action or automated techniques available to
577 the authorization server. Additional care is REQUIRED if dynamic
578 client registration is supported or clients may be registered in a
579 self-service manner.
581 One such mechanism that MAY be deployed is Content Security Policy
582 [CSP-2]. This protocol SHOULD be used on the assisted token endpoint
583 (and, if applicable, other endpoints used to authenticated the user
584 in a specific deployment) to prevent framing from unauthorized
585 origins. Using CSP allows the authorization server to specify
586 multiple origins in a single response header field and to constrain
587 these using flexible patterns (see [CSP-2] for details). This
588 standard provides a robust mechanism for protecting against click-
589 jacking by using policies that restrict the origin of frames (using
590 "frame-ancestors") together with those that restrict the sources of
591 scripts allowed to execute on an HTML page (by using "script-src").
592 A non-normative example of such a policy is shown in the following
593 listing:
595 HTTP/1.1 200 OK
596 Content-Security-Policy: frame-ancestors https://a.example.org:8000
597 Content-Security-Policy: script-src 'self'
598 X-Frame-Options: ALLOW-FROM https://a.example.org:8000
599 ...
601 Figure 3: Example CSP that will help protect against click-jacking
603 Because some user agents do not support [CSP-2], this technique
604 SHOULD be combined with others. In particular, the authorization
605 server SHOULD return an "X-Frame-Options" response header on the
606 assisted token endpoint (and, if applicable, other endpoints used to
607 authenticate the user and authorize the client in a specific
608 deployment). As defined in [RFC7034], this header will cause user
609 agents that support it (but not CSP) to block framing from any origin
610 that is not specified in this header's value. Because this header's
611 value can only include one origin, the framer is RECOMMENDED to use
612 the "for_origin" parameter (as specified in Section 4.1) with its own
613 origin as the value.
615 Some user agents do not support [RFC7034] nor [CSP-2]. Therefore,
616 the authorization server SHOULD include a frame-busting script like
617 that shown in Figure 7 of [FRAME-BUSTING]. Such a script would use
618 JavaScript to break out of any unauthorized origin that is framing
619 the assisted token endpoint. The authorization server MAY simply
620 break out of all frames in case [RFC7034] and [CSP-2] are unsupported
621 by the user agent, though this would render the assisted token flow
622 non-functional. The choice of whether or not this drastic
623 countermeasure should be employed depends on the user agents being
624 targeted in a certain deployment.
626 When the authorization server and client are provided by separate
627 parties, it is important that the resource owner is able to
628 distinguish the two. One safe way of doing so is by examination of
629 the user agent's address bar by the resource owner where the validity
630 of the certificate and location can be verified. In such situations,
631 whenever user interaction is required, the client MUST open the
632 assisted token endpoint in a new browser window rather than a hidden
633 iframe. The authorization server MUST take measures deemed
634 appropriate in a deployment to ensure that the client has not framed
635 the user's manual interaction; however, the necessity for interactive
636 user authentication and/or consent SHOULD be possible for the client
637 to determine in a hidden iframe.
639 8.2. WebAuthn
641 [WebAuthn] MAY be used to ensure that the user is authenticated to
642 the authorization server in a safe manner. This protocol offers
643 authentication processes that are resistant to man-in-the-middle
644 attacks. The API defined by this standard can be used to verify that
645 user authentication is performed at the expected origin. This is
646 superior to manual verification of the origin in the address bar of
647 the browser by the resource owner. It also provides a mechanism to
648 restrict the client framing the assisted token endpoint to be in the
649 same origin. When it is not, the use of [WebAuthn] will force the
650 client to use a separate window for user authentication.
652 8.3. Handle Tokens
654 Because the client applications that use the assisted token flow are
655 written in scripting languages like JavaScript and are hosted in Web
656 pages, users may keep such applications open in their user agents for
657 a prolonged period of time. During such period, the token issued to
658 the client may expire or be revoked. To ensure that such expired
659 tokens left remnant in the user agent are benign, a Handle Token
660 SHOULD always be issued by the assisted token endpoint. This ensures
661 that no identity data is exposed (even when the token is not yet
662 expired) and that a revoked token does not increase risks.
664 8.4. Warning Against Untrusted Scripts
666 As admitted in Section 8 of [RFC6454], preventing exfiltration of
667 cookies, tokens, and other such credentials in web browsers has
668 historically proven difficult to implement. Instead, the same-origin
669 policy has emerged as the cornerstone of security for such user
670 agents. Using this security model, it is not possible to prevent
671 access to a token issued to a client if that client includes
672 nefarious scripts from untrustworthy sources that have access to the
673 Document Object Model (DOM) where the token is stored. For this
674 reason, the authorization server MUST warn client application
675 developers who interact with the assisted token endpoint _not_ to use
676 untrusted scripts in their applications. This warning SHOULD at
677 least be conveyed through the documentation but MAY also be provided
678 through other mechanisms.
680 8.5. Origin of Event and Authorization Server
682 As described in Section 4.1, the authorization server will return an
683 access token to the client using HTML's postMessage interface. The
684 receiver of this message is provided with an event object that
685 contains an origin property. A client application MUST compare this
686 with that of the authorization server before consuming the message.
687 Otherwise, it runs the risk of processing messages posted from
688 untrusted origins. An example of a proper message handler is shown
689 in the following non-normative, JavaScript listing:
691
700 Figure 4: Comparing the origin of the postMessage event with that
701 of the authorization server
703 8.6. Token Storage
705 Most client applications that use the assisted token flow will
706 maintain the access token issued by the authorization server in a
707 persisted state; this will commonly be an HTTP cookie or local
708 storage. This is necessary, for instance, to create a pleasing user
709 experience when a user navigates away from the application in their
710 web browser and then returns. To ensure that the token is stored
711 safely, the authorization server MAY provide application developers
712 with guidance in the accompanying documentation on how to safely
713 persist tokens. The authorization server MAY also provide script
714 libraries that perform this action according to best common
715 practices. The authorization server MAY also store the token in an
716 HTTP cookie in its own DNS domain (rather than that of the client)
717 using the assisted token endpoint's path. In some cases, this would
718 elevate any storage requirements from the client application
719 developer. Besides simplifying the programming model for developers,
720 this technique allows the authorization server to check the validity
721 of the token and determine if the token has expired or if the
722 associated grant has been revoked in subsequent requests to the
723 assisted token endpoint; this will be possible because the requests
724 might include the token in the HTTP Cookie request header. In such
725 cases, the authorization server can take the appropriate action, such
726 as authenticating the user anew or request consent, before issuing a
727 new token. If the token is stored by the application, however, this
728 kind of verification cannot be performed by the authorization server
729 without an explicit request to validate a stored token.
731 9. Privacy Considerations
733 In some deployments, the assisted token endpoint may be served from a
734 distinct domain from that of the client. In such cases, the client
735 will be a third-party domain, and the resource owner's user agent may
736 prevent the authorization server from storing any third-party
737 cookies. If the authorization server requires state to be persisted
738 when performing the assisted token flow, it SHOULD provide a privacy-
739 preserving mechanism to store and retrieve its state even when the
740 assisted token endpoint is hosted on a distinct domain from that of
741 the client. The technical details of how to accomplish this are
742 implementation specific, and are beyond the scope of this
743 specification. If the authorization server does not support clients
744 that are hosted from a third-party domain, it MUST indicate this to
745 the client through some mechanism (e.g., its associated
746 documentation).
748 10. Normative References
750 [ASCII] American National Standards Institute, "Coded Character
751 Set -- 7-bit American Standard Code for Information
752 Interchange", ANSI X3.4, 1986.
754 [IANA.OAuth.Parameters]
755 IANA, "OAuth Parameters",
756 .
758 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
759 Requirement Levels", BCP 14, RFC 2119,
760 DOI 10.17487/RFC2119, March 1997,
761 .
763 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
764 Resource Identifier (URI): Generic Syntax", STD 66,
765 RFC 3986, DOI 10.17487/RFC3986, January 2005,
766 .
768 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
769 RFC 6749, DOI 10.17487/RFC6749, October 2012,
770 .
772 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and
773 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol",
774 RFC 7591, DOI 10.17487/RFC7591, July 2015,
775 .
777 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
778 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
779 May 2017, .
781 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0
782 Authorization Server Metadata", RFC 8414,
783 DOI 10.17487/RFC8414, June 2018,
784 .
786 11. Informative References
788 [CSP-2] West, M., Barth, A., and D. Veditz, "Content Security
789 Policy Level 2", July 2015, .
791 [FRAME-BUSTING]
792 Rydstedt, G., Bursztein, E., Boneh, D., and C. Jackson,
793 "Busting frame busting: a study of clickjacking
794 vulnerabilities at popular sites", July 2010,
795 .
798 [RFC5849] Hammer-Lahav, E., Ed., "The OAuth 1.0 Protocol", RFC 5849,
799 DOI 10.17487/RFC5849, April 2010,
800 .
802 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454,
803 DOI 10.17487/RFC6454, December 2011,
804 .
806 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace
807 for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012,
808 .
810 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0
811 Threat Model and Security Considerations", RFC 6819,
812 DOI 10.17487/RFC6819, January 2013,
813 .
815 [RFC7034] Ross, D. and T. Gondrom, "HTTP Header Field X-Frame-
816 Options", RFC 7034, DOI 10.17487/RFC7034, October 2013,
817 .
819 [W3C.WD-cors-20120403]
820 Kesteren, A., "Cross-Origin Resource Sharing", World Wide
821 Web Consortium LastCall WD-cors-20120403, 3 April 2012,
822 .
824 [WebAuthn] Balfanz, D., Czeskis, A., Hodges, J., Jones, J.C., Jones,
825 M., Kumar, A., Liao, A., Lindemann, R., and E. Lundberg,
826 "Web Authentication: An API for accessing Public Key
827 Credentials", World Wide Web Consortium
828 (W3C) Recommendation, 4 March 2019,
829 .
831 Appendix A. Acknowledgements
833 The following individuals contributed ideas, feedback, and wording to
834 this specification:
836 Mark Dobrinic, Karl McGuinness, Renato Athaydes, Daniel Lindau, Louis
837 Jannett
839 Appendix B. Document History
841 [[ to be removed by the RFC editor before publication as an RFC ]]
843 This section is to be removed before publishing as an RFC.
845 -05
847 * Clarified text and figures
849 * Added note about DCR not being recommended
851 * Fixed change controller for IANA registry entries
853 * Clarified and reorganized framing and address bar security
854 considerations based on L. Lannett's feedback
856 * Added WebAuthn security consideration
858 -04
860 * Updated IANA references to use the "short version" without file
861 extension or extra path information.
863 * Updated repository reference.
865 -03
867 * Updated repository links.
869 -02
871 * Updated section 8.1 with regards to the CSP headers.
873 * Updated authorization server metadata in section 6.
875 * Updated IANA Considerations section 7.
877 -01
879 * Updated to v. 3 XML format
881 -00
883 * Initial draft.
885 Authors' Addresses
887 Jacob Ideskog
888 Curity AB
890 Email: jacob@curity.io
892 Travis Spencer
893 Curity AB
895 Email: travis@curity.io