idnits 2.17.1
draft-ideskog-assisted-token-01.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 (24 November 2019) is 1609 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: 27 May 2020 24 November 2019
7 OAuth 2.0 Assisted Token
8 draft-ideskog-assisted-token-01
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 Status of This Memo
24 This Internet-Draft is submitted in full conformance with the
25 provisions of BCP 78 and BCP 79.
27 Internet-Drafts are working documents of the Internet Engineering
28 Task Force (IETF). Note that other groups may also distribute
29 working documents as Internet-Drafts. The list of current Internet-
30 Drafts is at https://datatracker.ietf.org/drafts/current/.
32 Internet-Drafts are draft documents valid for a maximum of six months
33 and may be updated, replaced, or obsoleted by other documents at any
34 time. It is inappropriate to use Internet-Drafts as reference
35 material or to cite them other than as "work in progress."
37 This Internet-Draft will expire on 27 May 2020.
39 Copyright Notice
41 Copyright (c) 2019 IETF Trust and the persons identified as the
42 document authors. All rights reserved.
44 This document is subject to BCP 78 and the IETF Trust's Legal
45 Provisions Relating to IETF Documents (https://trustee.ietf.org/
46 license-info) in effect on the date of publication of this document.
47 Please review these documents carefully, as they describe your rights
48 and restrictions with respect to this document.
50 Table of Contents
52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
53 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
54 3. Assisted Token Endpoint . . . . . . . . . . . . . . . . . . . 5
55 3.1. Access Token Scope . . . . . . . . . . . . . . . . . . . 6
56 3.2. Cross-Origin Support . . . . . . . . . . . . . . . . . . 7
57 4. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 7
58 4.1. Assisted Token Request . . . . . . . . . . . . . . . . . 7
59 4.2. Assisted Token Response . . . . . . . . . . . . . . . . . 8
60 4.3. Error Response . . . . . . . . . . . . . . . . . . . . . 8
61 5. Client Metadata . . . . . . . . . . . . . . . . . . . . . . . 10
62 6. Authorization Server Metadata . . . . . . . . . . . . . . . . 10
63 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
64 7.1. OAuth URI Registration . . . . . . . . . . . . . . . . . 11
65 7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 11
66 7.2. OAuth 2.0 Authorization Server Metadata . . . . . . . . . 11
67 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 11
68 8. Security Considerations . . . . . . . . . . . . . . . . . . . 12
69 8.1. Framing . . . . . . . . . . . . . . . . . . . . . . . . . 12
70 8.2. Handle Tokens . . . . . . . . . . . . . . . . . . . . . . 13
71 8.3. Warning Against Untrusted Scripts . . . . . . . . . . . . 13
72 8.4. Origin of Event and Authorization Server . . . . . . . . 13
73 8.5. Token Storage . . . . . . . . . . . . . . . . . . . . . . 14
74 8.6. Visibility of User Agent's Address Bar . . . . . . . . . 14
75 9. Privacy Considerations . . . . . . . . . . . . . . . . . . . 15
76 10. Normative References . . . . . . . . . . . . . . . . . . . . 15
77 11. Informative References . . . . . . . . . . . . . . . . . . . 16
78 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 17
79 Appendix B. Document History . . . . . . . . . . . . . . . . . . 17
80 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 17
82 1. Introduction
84 The OAuth 2.0 protocol flow for Single-page Applications (SPA)
85 defined in this memo, often referred to as the assisted token flow,
86 provides clients written in scripting languages, like JavaScript,
87 with a simplified integration (compared to the implicit or
88 authorization code flow) and ensures that end users are not
89 redirected away from the current page in order to obtain
90 authorization from the resource owner. The communication between the
91 client and the authorization server takes place within an HTML iframe
92 element or child window that is only displayed when interactive user
93 interaction is required; this is the case when authentication and/or
94 authorization are necessary. To communicate the result from this
95 iframe or child window to the client application, HTML's postMessage
96 interface is used instead of the redirection endpoint defined in
97 Section 3.1.2 of [RFC6749]. This difference is important for many
98 SPAs which take time to reload and may not be able to recreate the
99 same state prior to the user being redirected to the authorization
100 server.
102 Another goal of the assisted token flow is to simplify integration of
103 the client with the authorization server. Though [RFC6749] resulted
104 in a much simpler integration for client applications compared to its
105 predecessor, [RFC5849], developers still struggle with the many
106 inputs required to perform the various OAuth flows. For this reason,
107 the assisted token flow introduces a new endpoint called the assisted
108 token endpoint rather than extending and reusing the token endpoint
109 defined in Section 3.2 of [RFC6749]. As a result, client developers
110 do not need to specify a response_type parameter in the authorization
111 request. This coupled with the use of HTML's postMessage interface
112 for communication between the client and the authorization server
113 means that the redirect_uri and state parameters are also
114 unnecessary. Consequently, client developers only need to provide a
115 client_id, create a dynamic iframe or open a child window, and handle
116 the postMessage that is fired by the authorization server in order to
117 implement OAuth.
119 This interaction is shown in Figure 1.
121 +----------------------------+ +---------------+
122 | Client | | Authorization |
123 | +--------------------------+ | Server |
124 | | +-----------+ | |
125 | |--(A)-------->| |--(B)-- Client ------>| |
126 | | | | Identifier | |
127 | | | Hidden | | |
128 | | | iframe |<-(C)-- HTML with ----| |
129 | |<-(D)- Token -| | postMessage | |
130 | | or | | including | |
131 | | error +-----------+ access token | |
132 | +--------------------------+ or error | |
133 | | | |
134 +----------------------------+ +---------------+
136 Figure 1: Assisted Token Flow
138 The assisted token flow illustrated in Figure 1 includes the
139 following steps:
141 (A) The client creates a hidden iframe element using a scripting
142 language like JavaScript. The src attribute of this iframe is
143 the URL of the assisted token endpoint of the authorization
144 server.
146 (B) The query string of the src attribute on the iframe includes, at
147 a minimum, the client identifier.
149 (C) If the user is already logged in and has granted consent to the
150 client, the authorization server immediately returns an HTML
151 document that includes a script that is executing; this fires an
152 event which is communicated to the client using an HTML
153 window.postMessage.
155 (D) The client handles this event -- the payload of which is either
156 an access token or an error; the client then closes the dynamic
157 iframe without revealing it to the user.
159 If the resource owner has not authenticated or has not authorized the
160 client, then interaction between the resource owner and the
161 authorization server is required to obtain these. In such a case,
162 the HTML in step (C) of Figure 1 will include an error indicating
163 that user involvement is required. This will be handled by the
164 client in step (D) and login and/or consent will commence. This
165 process is illustrated in Figure 2.
167 +----------------------------+ +---------------+
168 | Client | | Authorization |
169 | +--------------------------+ | Server |
170 | | +-----------+ Client | |
171 | |--(E)-------->| |--(F)-- Identifier -->| |
172 | | | Visible | | |
173 | | | iframe |--(G)-- User -------->| |
174 | | | or child | authenticates | |
175 | |<-(I)- Token -| window | | |
176 | | | |<-(H)-- HTML with ----| |
177 | | +-----------+ postMessage | |
178 | +--------------------------+ including | |
179 | | access token | |
180 +----------------------------+ +---------------+
182 Figure 2: Assisted Token Login and/or Consent Flow
184 The flow shown in Figure 2 includes the following steps:
186 (E) The client creates a "visible" iframe or pops open a child
187 window after receiving an indication from the authorization
188 server that user interaction is required. As in the previous
189 flow, the src attribute value of this iframe or the input to the
190 open method of the user agents's window object is the URL of the
191 authorization server's assisted token endpoint.
193 (F) The query string of this URL includes, at a minimum, the client
194 identifier.
196 (G) The authorization server prompts the resource owner to
197 authenticate and/or authorize the client.
199 (H) The authorization server returns an HTML document that includes
200 a script that is executed; this fires an event which is
201 communicated to the client using an HTML window.postMessage.
203 (I) The client handles this event -- the payload of which is an
204 access token; the client then closes the iframe or child window
205 that it previously opened to facilitate user interaction.
207 2. Terminology
209 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
210 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
211 "OPTIONAL" in this document are to be interpreted as described in
212 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
213 capitals, as shown here.
215 Handle Token
216 An opaque token that refers to internal data of the
217 authorization server (e.g., the user ID, scope of the token,
218 etc.) as described in Section 3.1 of [RFC6819].
220 All other terms used in this document are as defined in [RFC6749].
221 Unless otherwise noted, all the protocol parameter names and values
222 are case sensitive.
224 3. Assisted Token Endpoint
226 The means through which the client obtains the location of the
227 assisted token endpoint is either by using the authorization server's
228 metadata as set forth in Section 6, the service documentation, or
229 some other method that is beyond the scope of this specification.
231 The endpoint URI MAY include an "application/x-www-form-urlencoded"
232 formatted (per Appendix B of [RFC6749]) query component (see
233 Section 3.4 of [RFC3986]), which MUST be retained when adding
234 additional query parameters. The endpoint URI MUST NOT include a
235 fragment component.
237 Since requests to the assisted token endpoint result in the
238 transmission of clear-text credentials (in the HTTP request and
239 response), the authorization server MUST require the use of TLS as
240 described in Section 1.6 of [RFC6749] when sending requests to the
241 assisted token endpoint.
243 The client MUST use the HTTP "GET" method when making access token
244 requests to this endpoint.
246 Parameters sent without a value MAY be treated as if they were
247 omitted from the request. The authorization server MUST ignore
248 unrecognized request parameters. Request and response parameters
249 MUST NOT be included more than once.
251 After completing its interaction with the resource owner, the
252 authorization server will fire an event using the HTML postMessage
253 interface. This message MUST NOT be posted to all origins, denoted
254 by "*". Instead, the authorization server MUST post this message
255 only to the client's allowed origin(s) previously established with
256 the authorization server during the client registration process.
258 3.1. Access Token Scope
260 Like the authorization and token endpoints, the assisted token
261 endpoint allows the client to specify the scope of the access request
262 using the "scope" request parameter. In turn, the authorization
263 server uses the "scope" response parameter to inform the client of
264 the scope of the access token issued. Unlike the typical behavior of
265 those endpoints, however, access tokens issued by the authorization
266 server using the assisted token endpoint MUST use the client's pre-
267 configured scope or the authorization server's pre-defined default if
268 none have been configured for the client.
270 If the client did not include a "scope" request parameter or if the
271 issued access token scope is different from the one requested by the
272 client, the authorization server MUST include the "scope"response
273 parameter to inform the client of the actual scope granted. Even
274 when the scope of the issued access token is the same as the one
275 requested by the client, the authorization server SHOULD include the
276 "scope" response parameter.
278 The format, constraints, and grammar of the scope parameter value is
279 as defined in Section 3.3 of [RFC6749].
281 The authorization server SHOULD NOT return an error if a scope has
282 not been pre-configured for the client; only if the authorization
283 server does not have a pre-defined default scope.
285 3.2. Cross-Origin Support
287 The assisted token endpoint MAY support CORS as defined in
288 [W3C.WD-cors-20120403].
290 4. Protocol
292 4.1. Assisted Token Request
294 The assisted token request is an HTTP GET request constructed by the
295 client with the following parameters provided on the query string:
297 client_id
298 REQUIRED. The client identifier as described in Section 2.2
299 of [RFC6749].
301 for_origin
302 OPTIONAL. The origin of the client in case multiple allowed
303 origins are configured with the authorization server and
304 support for user agents that do not support [CSP-2] but only
305 "X-Frame-Options" (as defined in [RFC7034]). See Section 8.1
306 for details.
308 prompt
309 OPTIONAL. Space delimited, case sensitive list of [ASCII]
310 string values that can be used to determine the login state
311 of the resource owner at the authorization server. The
312 defined values are:
314 none
315 The authorization server MUST NOT display any
316 authentication or consent user interface pages. An
317 error is returned if the user is not already
318 authenticated or if the client has not received
319 consent (either explicitly by the resource owner or
320 by the authorization server's configuration of the
321 client) or if the authorization server cannot fulfill
322 other conditions for processing. This can be used as
323 a method to probing for existing authentication and/
324 or consent.
326 consent
327 The authorization server SHOULD prompt the user for
328 consent before returning information to the client.
329 If it cannot obtain consent, it MUST return an error.
331 Other values may be provided in this list; the authorization
332 server MUST ignore them without producing an error if it
333 cannot understand them.
335 scope
336 OPTIONAL. The scope of the access request as described in
337 Section 3.1.
339 4.2. Assisted Token Response
341 The response from the assisted token endpoint is an HTML document
342 that executes a script which invokes the HTML postMessage interface
343 to send a message to either the parent window (in the case shown in
344 Figure 1) or the opener (in the case illustrated in Figure 2). The
345 origin that this event is posted to is that of the client. The
346 contents of this message is a JSON object with the following fields:
348 access_token
349 REQUIRED. The access token issued by the authorization
350 server.
352 expires_in
353 RECOMMENDED. The lifetime in seconds of the access token.
355 scope
356 REQUIRED. The scope of the access token as described in
357 Section 3.1.
359 sub
360 RECOMMENDED. A locally unique and never reassigned
361 identifier within the authorization server for the user,
362 which is intended to be consumed by the client. The sub
363 value is a case sensitive string.
365 token_type
366 REQUIRED. The type of the token issued as described in
367 Section 7.1 of [RFC6749]. Value is case insensitive.
369 4.3. Error Response
371 As with a successful response, an error is returned to the client
372 using an the HTML postMessage interface. Such an error is returned
373 whenever the resource owner denies the access request or whenever the
374 request fails for reasons other than the origin of the client being
375 disallowed to frame the assisted token endpoint. The error message
376 includes a JSON object with the following fields:
378 error
379 REQUIRED. A single [ASCII] error code from the following:
381 invalid_request
382 The request is missing a required parameter, includes
383 an invalid parameter value, includes a parameter more
384 than once, or is otherwise malformed.
386 unauthorized_client
387 The client is not authorized to request an access
388 token using this method.
390 access_denied
391 The resource owner or authorization server denied the
392 request.
394 consent_required
395 The client includes a prompt value of consent, but
396 consent by the resource owner was required.
398 interaction_required
399 The client included a prompt value of none, but
400 either the user needed to authenticate or consent to
401 the client's access or some other requirement of the
402 authorization server prevented it from providing
403 access without some form of user interaction.
405 unsupported_response_type
406 The authorization server does not support obtaining
407 an access token using this method.
409 invalid_scope
410 The requested scope is invalid, unknown, or
411 malformed.
413 server_error
414 The authorization server encountered an unexpected
415 condition that prevented it from fulfilling the
416 request. (This error code is needed because a 500
417 Internal Server Error HTTP status code cannot be
418 returned to the client directly in the child frame.)
420 temporarily_unavailable
421 The authorization server is currently unable to
422 handle the request due to a temporary overloading or
423 maintenance of the server. (This error code is
424 needed because a 503 Service Unavailable HTTP status
425 code cannot be returned to the client directly in the
426 child frame.)
428 Values for the "error" parameter MUST NOT include characters
429 outside the set %x20-21 / %x23-5B / %x5D-7E.
431 error_description
432 OPTIONAL. Human-readable [ASCII] text providing additional
433 information, used to assist the client developer in
434 understanding the error that occurred. Values for the
435 "error_description" parameter MUST NOT include characters
436 outside the set %x20-21 / %x23-5B / %x5D-7E.
438 error_uri
439 OPTIONAL. A URI identifying a human-readable web page with
440 information about the error, used to provide the client
441 developer with additional information about the error.
442 Values for the "error_uri" parameter MUST conform to the URI-
443 reference syntax and thus MUST NOT include characters outside
444 the set %x21 / %x23-5B / %x5D-7E.
446 5. Client Metadata
448 The authorization server MAY allow dynamic clients to request the use
449 of the assisted token flow when registering. Such a client may
450 indicate that it will interact with the authorization server using
451 the assisted token flow by including the string element
452 "urn:ietf:params:oauth:grant-type:assisted_token" in the array
453 associated with the "grant_types" metadata field sent to the client
454 registration endpoint (as defined in Section 3 of [RFC7591]). If the
455 authorization server allows the client to register with this grant
456 type, the "grant_types" included in the response MUST include the
457 value "urn:ietf:params:oauth:grant-type:assisted_token". The
458 inclusion of this value in the "grant_types" field is done despite
459 the fact that the client will not use this grant type at the token
460 endpoint but rather the assisted token endpoint (see Section 3).
462 The following client metadata field is defined by this specification.
463 It MAY be included in a registration request, as set forth in
464 Section 2 of [RFC7591].
466 allowed_origins
467 Array of origin strings for use in sending messages from the
468 authorization server to the client using the HTML's
469 postMessage interface.
471 6. Authorization Server Metadata
473 Support for the assisted token flow MUST be declared in the
474 authorization server's metadata (as defined in [RFC8414]) with the
475 following metadata:
477 assisted_token_endpoint
478 REQUIRED. URL of the authorization server's assisted token
479 endpoint defined in Section 3.
481 grant_types_supported
482 REQUIRED. A JSON array specified in Section 2 of [RFC8414]
483 which should contain the value "urn:ietf:params:oauth:grant-
484 type:assisted_token" as defined in Section 5.
486 7. IANA Considerations
488 7.1. OAuth URI Registration
490 This specification registers the following values in the IANA "OAuth
491 URI" registry (https://www.iana.org/assignments/oauth-parameters/
492 oauth-parameters.xhtml#uri) [IANA.OAuth.Parameters] established by
493 [RFC6755].
495 7.1.1. Registry Contents
497 * URN: urn:ietf:params:oauth:grant-type:assisted_token
499 * Common Name: Assisted token flow grant type for OAuth 2.0
501 * Change controller: IESG
503 * Specification Document: Section 5 of [[ this specification ]]
505 7.2. OAuth 2.0 Authorization Server Metadata
507 This specification registers the following values in the IANA "OAuth
508 2.0 Authorization Server Metadata" registry
509 (https://www.iana.org/assignments/oauth-parameters/oauth-
510 parameters.xhtml#authorization-server-metadata)
511 [IANA.OAuth.Parameters] established by [RFC8414].
513 7.2.1. Registry Contents
515 * Metadata name: assisted_token_endpoint
517 * Metadata Description: The Assisted Token Endpoint.
519 * Change controller: IESG
521 * Specification Document: Section 6 of [[ this specification ]]
523 8. Security Considerations
525 In addition to all the security considerations discussed in
526 [RFC6819], the following security considerations SHOULD be taken into
527 account.
529 8.1. Framing
531 Due to the use of an iframe to host the assisted token endpoint, the
532 authorization server MUST take precautions to ensure that only
533 trusted origins are allowed to frame it. The authorization server
534 MUST prevent any origin from framing the assisted token endpoint
535 except ones that an administrator has explicitly allowed. It may do
536 this in any manner that is available to the application.
538 One such mechanism that MAY be deployed is Content Security Policy
539 [CSP-2]. This protocol SHOULD be used on the assisted token endpoint
540 (and, if applicable, other endpoints used to authenticated the user
541 in a specific deployment) to prevent framing from unauthorized
542 origins. Using CSP allows the authorization server to specify
543 multiple origins in a single response header field and to constrain
544 these using flexible patterns (see [CSP-2] for details). This
545 standard provides a robust mechanism for protecting against click-
546 jacking when combining policies that restrict "child-src" with the
547 sources of scripts that are allowed to execute by using "script-src"
548 policies.
550 Because some user agents do not support [CSP-2], this technique
551 SHOULD be combined with others. In particular, the authorization
552 server SHOULD return an "X-Frame-Options" response header on the
553 assisted token endpoint (and, if applicable, other endpoints used to
554 authenticate the user in a specific deployment). As defined in
555 [RFC7034], this header will cause user agents that support it (but
556 not CSP) to block framing from any origin that is not specified in
557 this header's value. Because this header's value can only include
558 one origin, the framer should use the "for_origin" parameter (as
559 specified in Section 4.1) to include its own origin.
561 Some user agents do not support [RFC7034] nor [CSP-2]. Therefore,
562 the authorization server SHOULD include a frame-busting script like
563 that shown in Figure 7 of [FRAME-BUSTING]. Such a script would use
564 JavaScript to break out of any unauthorized origin that is framing
565 the assisted token endpoint. The authorization server MAY simply
566 break out of all frames in case [RFC7034] and [CSP-2] are unsupported
567 by the user agent, though this would render the assisted token flow
568 non-functional. The choice of whether or not this drastic
569 countermeasure should be employed depends on the user agents being
570 targetted in a certain deployment.
572 8.2. Handle Tokens
574 Because the client applications that use the assisted token flow are
575 written in scripting languages like JavaScript and are hosted in Web
576 pages, users may keep such applications open in their user agents for
577 a prolonged period of time. During such period, the token issued to
578 the client may expire or be revoked. To ensure that such expired
579 tokens left remnant in the user agent are benign, a Handle Token
580 SHOULD always be issued by the assisted token endpoint. This ensures
581 that no identity data is exposed (even when the token is not yet
582 expired) and that a revoked token does not increase risks.
584 8.3. Warning Against Untrusted Scripts
586 As admitted in Section 8 of [RFC6454], preventing exfiltration of
587 cookies, tokens, and other such credentials in web browsers has
588 historically proven difficult to implement. Instead, the same-origin
589 policy has emerged as the cornerstone of security for such user
590 agents. Using this security model, it is not possible to prevent
591 access to a token issued to a client if that client includes
592 nefarious scripts from untrustworthy sources that have access to the
593 Document Object Model (DOM) where the token is stored. For this
594 reason, the authorization server MUST warn client application
595 developers who interact with the assisted token endpoint _not_ to use
596 untrusted scripts in their applications. This warning SHOULD at
597 least be conveyed through the documentation but MAY also be provided
598 through other mechanisms.
600 8.4. Origin of Event and Authorization Server
602 As described in Section 4.1, the authorization server will return an
603 access token to the client using HTML's postMessage interface. The
604 receiver of this message is provided with an event object that
605 contains an origin property. A client application MUST compare this
606 with that of the authorization server before consuming the message.
607 Otherwise, it runs the risk of processing messages posted from
608 untrusted origins. An example of a proper message handler is shown
609 in the following non-normative, JavaScript listing:
611
619 Figure 3: Comparing the origin of the postMessage event with that
620 of the authorization server
622 8.5. Token Storage
624 Most client applications that use the assisted token flow will
625 maintain the access token issued by the authorization server in a
626 persisted state; this will commonly be an HTTP cookie or local
627 storage. This is necessary, for instance, to create a pleasing user
628 experience when a user navigates away from the application in their
629 web browser and then returns. To ensure that the token is stored
630 safely, the authorization server MAY provide application developers
631 with guidance in the accompanying documentation on how to safely
632 persist tokens. The authorization server MAY also provide script
633 libraries that perform this action according to best common
634 practices. The authorization server MAY also store the token in an
635 HTTP cookie in its own DNS domain (rather than that of the client)
636 using the assisted token endpoint's path. In some cases, this would
637 elevate any storage requirements from the client application
638 developer. Besides simplifying the programming model for developers,
639 this technique allows the authorization server to check the validity
640 of the token and determine if the token has expired or if the
641 associated grant has been revoked in subsequent requests to the
642 assisted token endpoint; this will be possible because the requests
643 will include the token in the HTTP Cookie request header. In such
644 cases, the authorization server can take the appropriate action, such
645 as authenticating the user anew or request consent, before issuing a
646 new token. If the token is stored by the application, however, this
647 kind of verification cannot be performed by the authorization server
648 without an explicit request to validate a stored token.
650 8.6. Visibility of User Agent's Address Bar
652 When the authorization server and client are provided by separate
653 parties, it is important that the resource owner is able to
654 distinguish the two. The only safe way of doing so is by examination
655 of the user agent's address bar where the validity of the certificate
656 and location can be made. In such situations, whenever user
657 interaction is required, the client SHOULD open the assisted token
658 endpoint in a new browser window rather than a hidden iframe. The
659 authorization serer MAY take any measures deemed appropriate in a
660 deployment to ensure that the client has not framed the user's manual
661 interaction; however, the necessity for interactive user
662 authentication and/or consent SHOULD be possible for the client to
663 determine in a hidden iframe.
665 9. Privacy Considerations
667 In some deployments, the assisted token endpoint may be served from a
668 distinct domain from that of the client. In such cases, the client
669 will be a third-party domain, and the resource owner's user agent may
670 prevent the authorization server from storing any third-party
671 cookies. If the authorization server requires state to be persisted
672 when performing the assisted token flow, it SHOULD provide a privacy-
673 preserving mechanism to store and retrieve its state even when the
674 assisted token endpoint is hosted on a distinct domain from that of
675 the client. The technical details of how to accomplish this are
676 implementation specific, and are beyond the scope of this
677 specification. If the authorization server does not support clients
678 that are hosted from a third-party domain, it MUST indicate this to
679 the client through some mechanism (e.g., its associated
680 documentation).
682 10. Normative References
684 [ASCII] American National Standards Institute, "Coded Character
685 Set -- 7-bit American Standard Code for Information
686 Interchange", ANSI X3.4, 1986.
688 [IANA.OAuth.Parameters]
689 IANA, "OAuth Parameters",
690 .
692 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
693 Requirement Levels", BCP 14, RFC 2119,
694 DOI 10.17487/RFC2119, March 1997,
695 .
697 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
698 Resource Identifier (URI): Generic Syntax", STD 66,
699 RFC 3986, DOI 10.17487/RFC3986, January 2005,
700 .
702 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
703 RFC 6749, DOI 10.17487/RFC6749, October 2012,
704 .
706 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and
707 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol",
708 RFC 7591, DOI 10.17487/RFC7591, July 2015,
709 .
711 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
712 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
713 May 2017, .
715 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0
716 Authorization Server Metadata", RFC 8414,
717 DOI 10.17487/RFC8414, June 2018,
718 .
720 11. Informative References
722 [CSP-2] West, M., Barth, A., and D. Veditz, "Content Security
723 Policy Level 2", July 2015, .
725 [FRAME-BUSTING]
726 Rydstedt, G., Bursztein, E., Boneh, D., and C. Jackson,
727 "Busting frame busting: a study of clickjacking
728 vulnerabilities at popular sites", July 2010,
729 .
732 [RFC5849] Hammer-Lahav, E., Ed., "The OAuth 1.0 Protocol", RFC 5849,
733 DOI 10.17487/RFC5849, April 2010,
734 .
736 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454,
737 DOI 10.17487/RFC6454, December 2011,
738 .
740 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace
741 for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012,
742 .
744 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0
745 Threat Model and Security Considerations", RFC 6819,
746 DOI 10.17487/RFC6819, January 2013,
747 .
749 [RFC7034] Ross, D. and T. Gondrom, "HTTP Header Field X-Frame-
750 Options", RFC 7034, DOI 10.17487/RFC7034, October 2013,
751 .
753 [W3C.WD-cors-20120403]
754 Kesteren, A., "Cross-Origin Resource Sharing", World Wide
755 Web Consortium LastCall WD-cors-20120403, 3 April 2012,
756 .
758 Appendix A. Acknowledgements
760 The following individuals contributed ideas, feedback, and wording to
761 this specification:
763 Mark Dobrinic, Karl McGuinness, Renato Athaydes, Daniel Lindau
765 Appendix B. Document History
767 [[ to be removed by the RFC editor before publication as an RFC ]]
769 This section is to be removed before publishing as an RFC.
771 -01
773 * Updated to v. 3 XML format
775 -00
777 * Initial draft.
779 Authors' Addresses
781 Jacob Ideskog
782 Curity AB
784 Email: jacob@curity.io
786 Travis Spencer
787 Curity AB
789 Email: travis@curity.io