Internet-Draft One-Time Refresh Proofs November 2026
Gerber Expires 23 May 2027 [Page]
Workgroup:
Web Authorization Protocol
Internet-Draft:
draft-gerber-oauth-refresh-one-time-proofs-00
Published:
Intended Status:
Experimental
Expires:
Author:
M. Gerber
Twilio

OAuth 2.0 One-Time Refresh Proofs

Abstract

Refresh token rotation asks the authorization server to deliver a new secret to the client in every refresh response, and then treats any later appearance of the old secret as evidence of theft. When a response is lost, the legitimate client's retry is indistinguishable from token theft, and the grant is revoked.

This document defines an alternative for clients that are unable or unwilling to implement DPoP. The client generates a key pair, registers the public key when it redeems the authorization code, and thereafter accompanies each use of a non-rotating refresh token with a signature over a strictly increasing counter and a nonce. Everything the client needs in order to retry is something the client itself generated, so a lost response can no longer desynchronize the two parties. Replay of a captured request yields nothing, and concurrent use of a copied key is detected in the same way that rotation detects reuse.

Discussion Venues

This note is to be removed before publishing as an RFC.

Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (oauth@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/oauth/.

Source for this draft and an issue tracker can be found at https://github.com/maxwellgerber/draft-gerber-oauth-refresh-one-time-proofs.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on 23 May 2027.

▲

Table of Contents

1. Introduction

OAuth 2.0 Security Best Current Practice (Section 4.14.2 of [RFC9700]) requires that refresh tokens issued to public clients be either sender-constrained or rotated on use. Sender-constraining in practice means DPoP [RFC9449] or mutual TLS [RFC8705]. Many clients implement neither, and so rely on rotation.

Rotation makes the token endpoint an exactly-once operation carried over a transport that offers at-most-once delivery. The authorization server invalidates the old refresh token when it issues the new one, but the new one exists only in a response that may never arrive. A client that retries with the token it still holds is presenting a superseded token, which is what reuse detection is designed to treat as theft.

Grace periods reduce the frequency of this failure but keep the underlying design, in which the next secret travels from server to client in a response that may not arrive.

This document removes the server-to-client secret:

A lost response therefore cannot desynchronize the client and the authorization server. This mechanism does not bind access tokens; Section 2.1 compares it with DPoP.

1.1. Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Refresh key:

an asymmetric key pair generated by the client for one grant.

Refresh proof:

a signature made with the private refresh key over the refresh token, a counter and a nonce.

Attempt:

one (counter, nonce) pair. Retransmissions of an attempt carry the same pair.

Accepted attempt:

an attempt for which the authorization server issued an access token.

Base64url:

the URL-safe encoding of Section 5 of [RFC4648], with trailing padding omitted.

2. Protocol Overview

The figure shows a code exchange followed by two refreshes, the second of which loses its response.

+--------+                                          +---------------+
|        |--(A) code, code_verifier, refresh_pub -->|               |
|        |<-(B) access_token, refresh_token --------|               |
|        |                                          |               |
|        |--(C) refresh_token, counter=1, nonce,    |               |
|        |      proof ----------------------------->|               |
|        |<-(D) access_token -----------------------|               |
|        |                                          |               |
| Client |--(E) refresh_token, counter=2, nonce',   | Authorization |
|        |      proof' ---------------------------->|    Server     |
|        |        X<-(F) access_token --------------|               |
|        |                                          |               |
|        |--(G) refresh_token, counter=2, nonce',   |               |
|        |      proof'' --------------------------->|               |
|        |<-(H) error: duplicate_request -----------|               |
|        |                                          |               |
|        |--(I) refresh_token, counter=3, nonce'',  |               |
|        |      proof''' -------------------------->|               |
|        |<-(J) access_token -----------------------|               |
+--------+                                          +---------------+
Figure 1: Code exchange, refresh, and recovery from a lost response

Had the request at (E) been lost instead of the response at (F), the retransmission at (G) would simply have been accepted.

2.1. Comparison with Rotation and DPoP

The table compares this mechanism with refresh token rotation as described in [RFC9700] and with DPoP-bound refresh tokens that are not also rotated. "Detected" means the grant is revoked at a later refresh; "prevented" means the attacker obtains nothing.

Table 1: Comparison with rotation and DPoP-bound refresh tokens
Threat Rotation Refresh proofs DPoP-bound
Lost token response User is logged out No effect No effect
Replay of a captured refresh request Detected Prevented Prevented
Capture of the code exchange (request or response) Attacker holds tokens Refresh token unusable; access token as issued Refresh token unusable; access token as issued
Offline copy of client storage, extractable key Detected Detected Not detected
Offline copy of client storage, non-extractable key Detected Prevented Prevented
Attacker executing in the client Detected Detected Not detected
Disclosure of the authorization server's grant store Depends on token storage Nothing usable Nothing usable

DPoP [RFC9449] already binds refresh tokens issued to public clients to the DPoP key, and an authorization server that does so need not rotate them. A client that implements DPoP has no need of this document.

This document is for the client that does not. It requires one key generation and one signature per refresh, over three concatenated strings. There is no JWS, no htu or htm to canonicalize, no server-provided nonce, and no involvement of resource servers. In exchange it does less: access tokens remain bearer tokens. What it adds, relative to a DPoP-bound refresh token, is the counter, and with it detection of a key that has been copied or is being used by an attacker inside the client.

Whether the counter would be better specified as an extension to DPoP is an open question (Appendix B).

3. Establishing the Refresh Key

3.1. Token Request

A client that wants a proof-bound refresh token generates a new ECDSA key pair on the P-256 curve [FIPS186-5] and adds the following parameter to an authorization code token request (Section 4.1.3 of [RFC6749]):

refresh_pub:

REQUIRED for this specification. The public refresh key, as the 65-octet uncompressed elliptic curve point (0x04 || X || Y, [SEC1], Section 2.3.3), base64url encoded.

The client MUST generate a new key pair for each authorization and MUST NOT use the key for any other purpose. The client SHOULD generate the private key as non-extractable where the platform supports it.

3.2. Token Response

The authorization server MUST reject the request with invalid_request if refresh_pub is not a valid P-256 public key.

Otherwise, having validated the request as usual, the authorization server stores the public key with the grant, sets the grant's last accepted counter to zero, and returns an ordinary token response (Section 5.1 of [RFC6749]). The refresh token in that response is proof-bound: it can be used only as described in Section 4.

4. Using the Refresh Token

4.1. Refresh Request

A refresh request for a proof-bound refresh token is a request as described in Section 6 of [RFC6749], with three additional parameters:

refresh_counter:

REQUIRED. A positive integer in base 10 with no leading zeros, sign or other decoration. The first attempt for a grant uses 1.

refresh_nonce:

REQUIRED. Between 16 and 64 characters from the base64url alphabet, generated with at least 128 bits of entropy.

refresh_proof:

REQUIRED. The refresh proof described in Section 4.2.

4.2. Refresh Proof

The signing input is the ASCII octets of the following concatenation, where . is a single period:

refresh_token "." refresh_counter "." refresh_nonce

The proof is an ECDSA signature over the signing input using P-256 and SHA-256, computed with the private refresh key and base64url encoded.

4.3. Authorization Server Processing

The authorization server processes a refresh request for a proof-bound refresh token in this order.

  1. Grant. If the refresh token is unknown, expired or revoked, respond with invalid_grant.

  2. Syntax. If any of the three parameters is absent or malformed, respond with invalid_request. A request without a proof MUST NOT be honoured: a proof-bound refresh token is never a bearer token.

  3. Signature. Verify the proof against the stored public key. If verification fails, respond with invalid_grant. The authorization server MUST NOT revoke the grant on a failed verification: the refresh token is not secret, so anyone who had seen it could otherwise force revocation.

  4. Sequence. Let last be the grant's last accepted counter. As a single atomic operation on the grant:

    • If the counter equals last + 1, record the counter as last, retain the (counter, nonce) pair, and issue an access token.

    • Otherwise, if the (counter, nonce) pair is one the authorization server has retained, respond with the duplicate_request error (Section 4.4). No token is issued and the grant is unchanged.

    • Otherwise, revoke the grant, including outstanding access tokens where that is possible, and respond with invalid_grant.

The third branch is the theft signal. A valid signature over a counter the authorization server has already moved past, with a nonce it does not recognize, can only have been made by a second holder of the private key.

A successful response is as described in Section 5.1 of [RFC6749]. It MUST NOT contain a refresh_token parameter with a value different from the one presented, and SHOULD omit the parameter.

The authorization server MUST retain the most recently accepted pair, and SHOULD retain accepted pairs for at least as long as a request could plausibly remain in flight; a few minutes is suggested. A duplicate that arrives after its pair has been discarded falls into the third branch and revokes the grant.

4.4. The duplicate_request Error

This document defines one new error code for the token endpoint:

duplicate_request:

The request repeats an attempt that the authorization server has already accepted. The client should consider that attempt consumed and proceed with the next counter.

It is returned with HTTP status 400 in the usual error response format (Section 5.2 of [RFC6749]).

An authorization server could instead answer a duplicate by issuing another access token, saving a round trip. It MUST NOT do so, because a duplicate is exactly what a replayed capture looks like.

5. Client Behaviour

The properties described in this document depend on the following client behaviour.

5.1. Persist Before Sending

The client maintains, per grant, the counter of its last consumed attempt and at most one pending attempt. Before sending a new attempt, the client MUST durably store the pending (counter, nonce) pair. The proof itself need not be stored; ECDSA signatures are randomized, and a freshly computed proof over the same pair is equally acceptable.

5.2. Retransmit the Same Attempt

While an attempt is pending, every refresh request the client sends for that grant MUST carry that attempt's counter and nonce. The client treats the following as a lost response and retransmits, with suitable backoff:

  • a connection failure or timeout;

  • any 5xx status;

  • a response that cannot be parsed, or that is successful in status but lacks the required members;

  • any error other than invalid_grant, invalid_client and duplicate_request. This includes rate limiting and error responses generated by intermediaries.

A client that gives up for the moment keeps the pending attempt and resumes with it later, including after a restart.

5.3. Advance Only on Knowledge

The client records an attempt as consumed, and clears the pending attempt, only when:

  • it has received and stored a successful response, or

  • it has received duplicate_request.

After duplicate_request the client has no access token to show for the attempt, so it immediately begins a new attempt with the next counter and a new nonce.

On invalid_grant or invalid_client the client discards the grant. Nothing else is terminal.

5.4. One Attempt at a Time

The client MUST ensure that at most one refresh is in progress per grant across every thread, process, tab or window that shares the grant's storage. Two contexts that each read the same counter and each mint a nonce will present the authorization server with the theft signal described in Section 4.3, and the grant will be revoked.

6. Security Considerations

6.1. Captured Requests

A refresh request contains the refresh token, a counter, a nonce and a signature over all three. An attacker who captures one, for instance from the logs of a TLS-terminating intermediary, can replay it and can do nothing else: the authorization server answers a replay of an accepted attempt with duplicate_request, and the attacker cannot produce a signature over any other counter or nonce.

The exception is an attacker who captures a request and also prevents it from reaching the authorization server. That attacker can deliver the request itself and will receive one access token. The client's retransmission then draws duplicate_request and the client proceeds normally. This is not detected. Preventing it would require binding the request to the transport.

6.2. Theft Detection and Its Limits

Two parties holding the same key and the same counter will, sooner or later, present the same counter with different nonces. The second to do so causes revocation. This is the same property refresh token rotation provides and it has the same weakness: an attacker who refreshes while the legitimate client is idle is undetected until the client returns.

If storage is copied while an attempt is pending, both parties hold the same pending pair. One is accepted, the other receives duplicate_request, and each then proceeds to the next counter with its own nonce. Detection therefore arrives one refresh later than it otherwise would, and each party obtains one further access token in the meantime.

An attacker executing inside the client (cross-site scripting, say) can ask a non-extractable key to sign. Non-extractability confines the attack to the period of compromise; it does not prevent it.

7. References

7.1. Normative References

[FIPS186-5]
National Institute of Standards and Technology, "Digital Signature Standard (DSS)", FIPS PUB 186-5, DOI 10.6028/NIST.FIPS.186-5, , <https://doi.org/10.6028/NIST.FIPS.186-5>.
[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/rfc/rfc2119>.
[RFC4648]
Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, DOI 10.17487/RFC4648, , <https://www.rfc-editor.org/rfc/rfc4648>.
[RFC6749]
Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, , <https://www.rfc-editor.org/rfc/rfc6749>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/rfc/rfc8174>.
[SEC1]
Standards for Efficient Cryptography Group, "SEC 1: Elliptic Curve Cryptography", Version 2.0, , <https://www.secg.org/sec1-v2.pdf>.

7.2. Informative References

[RFC8705]
Campbell, B., Bradley, J., Sakimura, N., and T. Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens", RFC 8705, DOI 10.17487/RFC8705, , <https://www.rfc-editor.org/rfc/rfc8705>.
[RFC9449]
Fett, D., Campbell, B., Bradley, J., Lodderstedt, T., Jones, M., and D. Waite, "OAuth 2.0 Demonstrating Proof of Possession (DPoP)", RFC 9449, DOI 10.17487/RFC9449, , <https://www.rfc-editor.org/rfc/rfc9449>.
[RFC9700]
Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, "Best Current Practice for OAuth 2.0 Security", BCP 240, RFC 9700, DOI 10.17487/RFC9700, , <https://www.rfc-editor.org/rfc/rfc9700>.

Appendix A. Example

One grant, from code exchange to a recovered lost response. The key and signatures are real and verify against the public key shown. The responses are illustrative. Line breaks inside values are for display only.

# Code exchange: register the public key.

POST /token
  grant_type=authorization_code
  client_id=app
  code=i9aa_UbUHSIwX_3rnb_Jyw
  code_verifier=pKRFjmAIOwcsbHrG5UMLj0rVg0YtximebMTtZW2fcpo
  redirect_uri=https://app.example/cb
  refresh_pub=BPA5CdTORvBMgWTzXE9MB0X7U9Lxx0r95AE2VMwQCqg5Y2fl7O6UGJ
              D8DEaPm0ho46P6jztsQlcYxYhJ5Qqnuhc

200 {"access_token":"2YotnFZFEjr1zCsicMWpAA",
     "token_type":"Bearer","expires_in":600,
     "refresh_token":"oYmn5yIe5ez3y5hsJkajPTl1W3B7gjwIB7LbkLRohDk"}

# Refresh, counter 1. Signing input:
#   oYmn5yIe5ez3y5hsJkajPTl1W3B7gjwIB7LbkLRohDk.1.lZxgLFHMUrz3MvtZ14GF_w

POST /token
  grant_type=refresh_token
  client_id=app
  refresh_token=oYmn5yIe5ez3y5hsJkajPTl1W3B7gjwIB7LbkLRohDk
  refresh_counter=1
  refresh_nonce=lZxgLFHMUrz3MvtZ14GF_w
  refresh_proof=DD0KfNFW2roiDffShIj64XxAmJGrk32WkNMmp4dArullkLVMHCQZm1
                1dKIoRdoGkKOozR4yzpHNBblnivtEq3A

200 {"access_token":"P8NgAGKHqv7QUEw555LDbpUyY-RBObDR4YG-CL1wFEY",
     "token_type":"Bearer","expires_in":600}

# Refresh, counter 2. The AS accepts it; the response is lost.

POST /token
  grant_type=refresh_token
  client_id=app
  refresh_token=oYmn5yIe5ez3y5hsJkajPTl1W3B7gjwIB7LbkLRohDk
  refresh_counter=2
  refresh_nonce=M_RTesmwhOkhr4ArD5xGEQ
  refresh_proof=Nj29r5X6komZUrWQTz3KxdZt16eO51VygXTnf2BflkufMSUg8DvwBO
                M2QF25SzVSbqsZy7EbkokbpaujcDyQ9Q

(no response received)

# Retransmission: same counter and nonce. The client re-signs, so the
# proof octets differ.

POST /token
  grant_type=refresh_token
  client_id=app
  refresh_token=oYmn5yIe5ez3y5hsJkajPTl1W3B7gjwIB7LbkLRohDk
  refresh_counter=2
  refresh_nonce=M_RTesmwhOkhr4ArD5xGEQ
  refresh_proof=(a fresh signature over the same input)

400 {"error":"duplicate_request"}

# Counter 2 is known to be consumed. Next attempt.

POST /token
  grant_type=refresh_token
  client_id=app
  refresh_token=oYmn5yIe5ez3y5hsJkajPTl1W3B7gjwIB7LbkLRohDk
  refresh_counter=3
  refresh_nonce=HlbePMcpunkMH8Jp7eekDw
  refresh_proof=Xej7iclBC0hJm3AXa2QhPfGgTBOo7VzZ8hjA4uqMwKOW3nByYYiuIb
                b1_PvmkuR1aF516fNBaLy8YQxH0mZC8A

200 {"access_token":"zaG7uKGCJACz7SloYUnDlMr2vXe7Siq2NOQgqzn-ctA",
     "token_type":"Bearer","expires_in":600}

Appendix B. Open Issues

  1. Lost code exchange response. Not addressed. The client restarts the authorization. An idempotent retry of the code exchange is possible.

  2. Discovery. Nothing tells a client that the authorization server supports this, or that the refresh token it received is proof-bound. A server that ignores refresh_pub returns an ordinary bearer refresh token.

  3. Algorithm agility. The encodings are specific to P-256. Is one algorithm enough?

  4. Retention window. Section 4.3 suggests "a few minutes". Should there be a normative minimum?

  5. Other grants. Only the authorization code grant is covered.

  6. Should this be a DPoP extension? A counter and nonce in a DPoP proof at the token endpoint would give DPoP clients the same detection property.

  7. Missing sections. Key storage guidance, denial of service, authorization server consistency requirements, metadata and IANA registrations are not yet written.

  8. Names. All parameter names are placeholders.

Author's Address

Maxwell Gerber
Twilio