idnits 2.17.1 draft-ietf-oauth-refresh-token-expiration-03.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 6 instances of too long lines in the document, the longest one being 3 characters in excess of 72. ** The abstract seems to contain references ([RFC6749]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- -- The document date (6 July 2026) is 119 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'RFC 9700' is mentioned on line 395, but not defined == Unused Reference: 'RFC9700' is defined on line 511, but no explicit reference was found in the text Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Web Authorization Protocol N. Watson 3 Internet-Draft Google, LLC 4 Intended status: Informational 6 July 2026 5 Expires: 7 January 2027 7 OAuth 2.0 Refresh Token and Authorization Expiration 8 draft-ietf-oauth-refresh-token-expiration-03 10 Abstract 12 This specification extends OAuth 2.0 [RFC6749] by adding new token 13 endpoint response parameters to specify refresh token expiration and 14 user authorization expiration. 16 About This Document 18 This note is to be removed before publishing as an RFC. 20 The latest revision of this draft can be found at 21 https://drafts.oauth.net/rt-expiration/draft-ietf-oauth-refresh- 22 token-expiration.html. Status information for this document may be 23 found at https://datatracker.ietf.org/doc/draft-ietf-oauth-refresh- 24 token-expiration/. 26 Discussion of this document takes place on the Web Authorization 27 Protocol Working Group mailing list (mailto:oauth@ietf.org), which is 28 archived at https://mailarchive.ietf.org/arch/browse/oauth/. 29 Subscribe at https://www.ietf.org/mailman/listinfo/oauth/. 31 Source for this draft and an issue tracker can be found at 32 https://github.com/oauth-wg/rt-expiration. 34 Status of This Memo 36 This Internet-Draft is submitted in full conformance with the 37 provisions of BCP 78 and BCP 79. 39 Internet-Drafts are working documents of the Internet Engineering 40 Task Force (IETF). Note that other groups may also distribute 41 working documents as Internet-Drafts. The list of current Internet- 42 Drafts is at https://datatracker.ietf.org/drafts/current/. 44 Internet-Drafts are draft documents valid for a maximum of six months 45 and may be updated, replaced, or obsoleted by other documents at any 46 time. It is inappropriate to use Internet-Drafts as reference 47 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on 7 January 2027. 50 Copyright Notice 52 Copyright (c) 2026 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 57 license-info) in effect on the date of publication of this document. 58 Please review these documents carefully, as they describe your rights 59 and restrictions with respect to this document. Code Components 60 extracted from this document must include Revised BSD License text as 61 described in Section 4.e of the Trust Legal Provisions and are 62 provided without warranty as described in the Revised BSD License. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 67 2. Requirements Notation and Conventions . . . . . . . . . . . . 3 68 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 69 4. Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . 4 70 4.1. Authorization expiration . . . . . . . . . . . . . . . . 4 71 4.2. Refresh token timeout . . . . . . . . . . . . . . . . . . 4 72 5. Refresh token expiration . . . . . . . . . . . . . . . . . . 4 73 6. Token endpoint response . . . . . . . . . . . . . . . . . . . 5 74 6.1. Successful response . . . . . . . . . . . . . . . . . . . 5 75 6.1.1. Relationship of authorization_expires_in to scopes . 6 76 6.1.2. Indefinite Expiration . . . . . . . . . . . . . . . . 6 77 6.2. Error response . . . . . . . . . . . . . . . . . . . . . 7 78 6.3. Example . . . . . . . . . . . . . . . . . . . . . . . . . 7 79 7. Update to Token Introspection . . . . . . . . . . . . . . . . 8 80 8. Update to Authorization Server Metadata . . . . . . . . . . . 8 81 9. User Experience Considerations . . . . . . . . . . . . . . . 8 82 10. Security Considerations . . . . . . . . . . . . . . . . . . . 9 83 11. Privacy Considerations . . . . . . . . . . . . . . . . . . . 9 84 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 85 12.1. OAuth Parameters Registration . . . . . . . . . . . . . 9 86 12.1.1. Registry Contents . . . . . . . . . . . . . . . . . 10 87 12.2. OAuth Authorization Server Metadata Registration . . . . 10 88 12.2.1. Registry Contents . . . . . . . . . . . . . . . . . 10 89 12.3. Change History . . . . . . . . . . . . . . . . . . . . . 10 90 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 91 13.1. Normative References . . . . . . . . . . . . . . . . . . 11 92 13.2. Informative References . . . . . . . . . . . . . . . . . 11 93 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 12 94 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 12 96 1. Introduction 98 RFC6749 defines the OAuth 2.0 protocol, part of which is the ability 99 for a client to receive a refresh token that may be repeatedly 100 exchanged for more access tokens. OAuth 2.0 does not contain any 101 normative language around expiration or lack thereof for refresh 102 tokens, mentioning only that they are "typically long-lasting". 104 In the years since the publication of OAuth 2.0, in response to 105 changing security and privacy landscapes, many authorization servers 106 have begun to issue shorter-lived refresh tokens for two main 107 reasons: 109 * The authorization server or user may decide that the access being 110 granted is too sensitive to allow indefinite access (e.g. mail or 111 health data). 113 * The authorization server enforces a maximum duration that refresh 114 tokens may be held without being exchanged on the token endpoint. 116 Clients may wish to implement special handling for expiring refresh 117 tokens. For example, if the user has granted expiring access, the 118 client may notify the user that they will need to reauthorize access 119 before a certain date to avoid interruption of service. 121 2. Requirements Notation and Conventions 123 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 124 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 125 "OPTIONAL" in this document are to be interpreted as described in 126 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 127 capitals, as shown here. 129 3. Terminology 131 This specification uses terminology defined in [RFC6749]. The 132 following terms are used throughout this document: 134 Resource owner and user May be used interchangeably to refer to the 135 entity capable of granting access to a protected resource. 137 Client, application, and relying party May be used interchangeably 138 to refer to the application making protected resource requests on 139 behalf of the resource owner and with its authorization. 141 Authorization The resource owner's permission grant for a client to 142 access protected resources on their behalf, as described in 143 [RFC6749] Sec 4.1.1. 145 Access token A credential used by the client to access protected 146 resources on behalf of the resource owner, as referenced in 147 [RFC6749] Sec 1.4. Access tokens represent proof of 148 authorization. 150 Refresh token A credential used by the client to obtain new access 151 tokens without prompting the user, as referenced in [RFC6749] Sec 152 1.5. Refresh tokens do not grant authorization or renew 153 authorization, they only provide a mechanism for obtaining new 154 access tokens within the bounds of an existing authorization. 156 4. Concepts 158 There are two mechanisms that can affect refresh token expiration. 160 4.1. Authorization expiration 162 When granting authorization for an application to access their data 163 as referenced in [RFC6749] Sec 4.1.1, the user may opt to time-limit 164 that authorization, especially if the data is sensitive or they 165 aren't sure how long they'll continue using the application. The 166 authorization server itself may also impose mandatory limits on 167 authorization duration. 169 4.2. Refresh token timeout 171 Authorization servers may wish to define a maximum amount of time 172 clients can hold a refresh token without exchanging it. Beyond the 173 security benefit provided by expiring credentials, this also provides 174 a convenient mechanism for authorization servers to ensure there 175 aren't ancient valid credentials out in the wild, which could 176 complicate tasks like refresh token key rotation. 178 5. Refresh token expiration 180 The refresh token MUST NOT expire later than the user authorization 181 expires. It MAY expire earlier if the authorization server also 182 enforces a maximum duration between refresh token exchanges. 184 If the user renews their authorization, the authorization server 185 SHOULD update the expiration time of existing refresh tokens if their 186 lifetime was truncated due to user authorization expiration. (This 187 is especially true if the authorization was updated out of band as 188 discussed in User Experience Considerations (Section 9).) The 189 authorization server MUST NOT accept expired refresh tokens for any 190 purpose, even if it has no way to update the expiration time of 191 existing refresh tokens. 193 Access tokens MUST NOT expire later than the user authorization 194 expires. If the user renews their authorization, the authorization 195 server MAY update the expiration time of existing access tokens if 196 possible. Resource servers MUST NOT accept expired access tokens for 197 any purpose, even if the authorization server has no way to update 198 the expiration time of existing access tokens. 200 6. Token endpoint response 202 This specification introduces two new response parameters. 204 6.1. Successful response 206 refresh_token_timeout 207 The time in seconds that the refresh token may be held by the client 208 without exchanging. For example, the value 604800 denotes that the 209 refresh token will expire in one week from the time the response was 210 generated. This value SHALL NOT exceed the value in 211 authorization_expires_in. 213 authorization_expires_in 214 The lifetime in seconds of the user's authorization for the scopes 215 contained in the issued or presented refresh token. For example, the 216 value 2629800 denotes that the authorization will expire in one month 217 from the time the response was generated. This value MAY exceed that 218 of refresh_token_timeout. 220 An authorization server MAY return only one of these parameters. 221 Providing refresh_token_timeout without authorization_expires_in 222 indicates that the user's authorization is indefinite, but the 223 refresh token must be used within the specified timeout to remain 224 valid. Providing authorization_expires_in without 225 refresh_token_timeout indicates that the authorization has a fixed 226 duration, but the refresh token has no maximum idle time and may 227 remain valid if the authorization is extended out of band. 229 If finite, the authorization server MUST return these values whenever 230 the token endpoint response contains the refresh_token field. The 231 authorization server MAY return these values even if the response 232 contains no refresh_token field, in which case the values correspond 233 to the presented refresh_token. This can be useful in the following 234 example cases: 236 * For refresh_token_timeout, the authorization server could have 237 updated the existing refresh token lifetime in place. 239 * For authorization_expires_in, the user's authorization lifetime 240 could have been modified out of band. 242 * In all cases, it can be convenient for the client to receive these 243 values in each response. 245 6.1.1. Relationship of authorization_expires_in to scopes 247 Though authorization_expires_in is returned from the token endpoint 248 when refresh tokens are used, it corresponds to the user's 249 authorization for _scopes_ (or finer-grained access through RAR 250 [RFC9396]) rather than individual tokens. The authorization server 251 SHOULD ensure consistent lifetimes across multiple refresh tokens for 252 the same scopes. 254 Tying authorization lifetime to scopes means it's possible to have 255 some access valid for one duration and other access valid for a 256 different duration. For example, a user could grant indefinite 257 access for the openid scope and short-lived access for a calendar 258 scope. In situations like this, it is RECOMMENDED that the 259 authorization server return the minimum time that any access granted 260 by the refresh token is valid. This does run some risk of the client 261 asking the user to reauthorize prematurely. In the previous example, 262 the client might ask the user to reauthorize the openid scope because 263 it received an authorization_expires_in value corresponding to the 264 short-lived calendar scope. 266 If clients are requesting multiple scopes that can have different 267 lifetimes, they will ultimately need to make their own tradeoffs to 268 decide how and when to ask the user for reauthorization. This 269 specification's goal is simply to provide them with more information 270 to make this decision. 272 6.1.2. Indefinite Expiration 274 Omitted values indicate that there is no fixed upper bound on the 275 lifetime of the credential or authorization. If the authorization 276 server has not declared its support for refresh token lifetime in the 277 Authorization Server Metadata, omitted response fields could indicate 278 either indefinite validity or simply lack of support for this 279 specification. However, indefinite expiration and lack of 280 information about expiration should be handled by the client in the 281 same way. That is to say, the client must always handle refresh 282 token invalidation not caused by expiration, such as by explicit user 283 revocation. Clients MUST NOT make any assumptions that omitted 284 response fields in one response imply their omission in later 285 responses too. 287 Rather than omitting a response value, an authorization server may 288 choose to return a large arbitrary value, e.g. 315569520 for 10 289 years. This avoids any ambiguity around support for indefinite 290 values while achieving a similar practical effect. Clients MUST 291 treat all large values as literals and MUST NOT make any assumptions 292 about which may be considered indefinite. 294 6.2. Error response 296 The existing invalid_grant error code already explicitly covers token 297 expiration and should be sufficient. Upon receiving this error code 298 the client SHOULD start a new authorization grant flow. 300 6.3. Example 302 Suppose an authorization server enforces that refresh tokens must be 303 exchanged at least once every 7 days, and a user has granted 304 authorization to an application for access for 10 days. The initial 305 authorization code grant (Day 0) will result in the following 306 response values: 308 refresh_token_timeout: 604800 // 7 days 309 authorization_expires_in: 864000 // 10 days 311 A refresh token grant on Day 2 will result in the following response 312 values: 314 refresh_token_timeout: 604800 // 7 days 315 authorization_expires_in: 691200 // 8 days 317 A refresh token grant on Day 7 will result in the following response 318 values: 320 refresh_token_timeout: 259200 // 3 days 321 authorization_expires_in: 259200 // 3 days 323 If instead, the client held the initial refresh token for 8 days 324 (i.e. exceeding refresh_token_timeout but not 325 authorization_expires_in), the refresh token grant will fail: 327 error: invalid_grant 328 error_description: "expired refresh token" 330 Note that the error description text is non-normative and for 331 illustrative purposes only. 333 7. Update to Token Introspection 335 While Token Introspection [RFC7662] is primarily intended for 336 resource servers seeking information about received access tokens, 337 the specification does permit refresh token introspection as well. 338 Authorization servers supporting refresh token introspection SHOULD 339 support the refresh_token_timeout and authorization_expires_in 340 parameters on the endpoint with the same semantics as defined in 341 Token endpoint response (Section 6). These parameters SHOULD be 342 returned only when the presented token is a refresh token. 344 Use of a refresh token on token introspection MUST NOT reset any 345 refresh_token_timeout duration. 347 8. Update to Authorization Server Metadata 349 Support for the expiring refresh tokens SHOULD be declared in the 350 OAuth 2.0 Authorization Server Metadata [RFC8414] with the following 351 metadata: 353 refresh_token_expiration_types_supported 354 OPTIONAL. JSON array of supported expiration types. The possible values 355 are "authorization" and "token_timeout". 357 If the authorization server omits expiration time response fields to 358 indicate indefinite validity, it MUST declare 359 refresh_token_expiration_types_supported in its metadata to indicate 360 to the client that it's aware of this spec. 362 9. User Experience Considerations 364 While clients must be able to gracefully handle tokens' expiring at 365 any time, the user experience may suffer if there's an unintended 366 interruption of service. This degradation of experience would most 367 likely be felt by users of clients running in the background, such as 368 task or travel management apps that rely on access to a user's 369 calendar or inbox. 371 If an application recognizes that its access is nearing expiration, 372 it can proactively prompt the user for reauthorization next time 373 they're "in the loop" (e.g. using a parameter like prompt=consent 374 from [OpenID]), or even communicate to the user out of band that 375 their granted access is expiring. 377 Another option an authorization server could provide to the user is a 378 management surface where the user can go proactively extend the 379 lifetime of their own grant, which would update the lifetime of the 380 client's refresh token(s) in place. The client would discover the 381 extended expiration on its next refresh token grant request. 383 10. Security Considerations 385 While it is possible to allow refresh token expiration to exceed that 386 of user authorization expiration if the authorization server checks 387 both timestamps when validating a refresh token, this is a 388 potentially dangerous source of bugs in systems with complicated user 389 authorization models. By requiring refresh tokens to expire no later 390 than user authorization expires, there is less risk of bugs that 391 accidentally provide data access to the client beyond the term of the 392 user's authorization. 394 Authorization servers implementing token rotation on every refresh 395 [RFC 9700] Sec 4.14 may wish to enforce a maximum duration that a 396 refresh token may be held without rotation, and this specification 397 allows that duration to be communicated as part of the API rather 398 than relying on documentation. 400 Clients may wish to maintain multiple refresh tokens with different 401 access in order to separate different lifetimes across different 402 scopes. For example, a short-lived token to access financial data 403 and a long-lived token to access basic user info. There is a 404 tradeoff here, both in complexity of token management and also in 405 increased friction for the user to authorize multiple tokens. 407 11. Privacy Considerations 409 Allowing users to time-limit their authorization is a privacy 410 improvement. While this was already doable in regular OAuth 411 implementations, the potential interruption of service for the user 412 may have discouraged implementation of the feature. This 413 specification provides a standardized way to mitigate that concern 414 and should lead to greater adoption of time-limited authorization. 416 12. IANA Considerations 418 12.1. OAuth Parameters Registration 420 This specification registers the following OAuth parameter 421 definitions in the IANA OAuth Parameters registry. 423 12.1.1. Registry Contents 425 * Name: refresh_token_timeout 427 - Parameter Usage Location: token response 429 - Change Controller: IETF 431 - Reference: This document 433 * Name: authorization_expires_in 435 - Parameter Usage Location: token response 437 - Change Controller: IETF 439 - Reference: This document 441 12.2. OAuth Authorization Server Metadata Registration 443 This specification registers the following Authorization Server 444 Metadata definitions in the IANA OAuth Authorization Server Metadata 445 registry. 447 12.2.1. Registry Contents 449 * Metadata Name: refresh_token_expiration_types_supported 451 - Metadata Description: What types of refresh token expiration 452 are supported by the authorization server 454 - Change Controller: IETF 456 - Reference: This document 458 12.3. Change History 460 Delete this section before publication. 462 * May 8, 2026: 464 - Incorporate Vanshaj's review: 466 o Add language on backwards compatibility for definite 467 duration becoming finite. 469 o refresh_token_expiration_types_supported "credential" value 470 renamed to "token_timeout". 472 o Simplified example 474 o Linking UX considerations from RT expiration section 476 * Feb 27, 2026: 478 - Address Issues 4, 5, 6 from George to discuss tradeoffs around 479 managing multiple tokens or scopes with different expirations, 480 as well as out of band reauthorization by the user. 482 - Rewording and clarification based on Dan's suggestions on the 483 list. 485 13. References 487 13.1. Normative References 489 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 490 Requirement Levels", BCP 14, RFC 2119, 491 DOI 10.17487/RFC2119, March 1997, 492 . 494 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 495 RFC 6749, DOI 10.17487/RFC6749, October 2012, 496 . 498 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 499 RFC 7662, DOI 10.17487/RFC7662, October 2015, 500 . 502 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 503 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 504 May 2017, . 506 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 507 Authorization Server Metadata", RFC 8414, 508 DOI 10.17487/RFC8414, June 2018, 509 . 511 [RFC9700] Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 512 "Best Current Practice for OAuth 2.0 Security", BCP 240, 513 RFC 9700, DOI 10.17487/RFC9700, January 2025, 514 . 516 13.2. Informative References 518 [OpenID] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 519 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 520 . 522 [RFC9396] Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 523 Rich Authorization Requests", RFC 9396, 524 DOI 10.17487/RFC9396, May 2023, 525 . 527 Acknowledgments 529 A special thanks to Aaron Parecki for his continuous feedback and 530 invaluable assistance in guiding the author through the IETF draft 531 process. 533 The author would also like to thank Andrii Deinega, George Fletcher, 534 Dan Moore, and Vanshaj Singhania for their reviews and technical 535 suggestions on the repo and mailing list. 537 Author's Address 539 Nicholas Watson 540 Google, LLC 541 Email: nwatson@google.com