Out of Band Authorization Code Delivery for OAuth 2.0

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 1 April 2027.¶

Copyright Notice

Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

The OAuth authorization code grant type defined in [OAUTH] relies on the front-channel to communicate parameters between the client and authorization server (AS) using query parameters. This process relies on the resource owner's browser being able to launch a URI that is hosted on each of the AS and the client.¶

In some circumstances, such as a command line client running on a remote terminal, the resource owner's browser cannot reach a URL hosted by the client. These kinds of clients have traditionally used alternatives such as the device code grant type [DEVICECODE], but the split between different grant types depending on where the client is running is a complication that requires server-side support, multiple network roundtrips (with polling), and potentially multiple different client registrations.¶

Instead of using a different grant type, an out-of-band mechanism, such as the resource owner copying and pasting values into the waiting client, to deliver the authorization code and state value from the AS to the client. This process can be error prone as multiple separate values need to be transferred intact to the client without having their values conflated with each other.¶

This specification defines a method to harden the out-of-band delivery of the code and state parameters to the client to be a single value that is less error-prone. No changes or participation by the AS is required (apart from a valid redirect_uri for the helper page).¶

2. Out of Band Authorization Code Transfer

1. The client registers its helper page https://c.example.com/callback as a valid redirect_uri¶

2. The client creates a state value and sends it with other parameters to the browser as part of the authorization URI; the client waits for a paste input¶

3. The browser fetches the authorization URI at the AS¶

4. The AS completes the OAuth transaction and creates a code value and sends this to the browser as part of the callback¶

5. The browser fetches the helper page with the code and state parameters¶

6. The helper page parses the code and state parameters in javascript and calculates the combined code using HKDF in Section 2.1¶

7. The user copies the combined code from the helper page¶

8. The user pastes the combined code into the client¶

9. The client uses its stored state value to derive the code value from the combined code in Section 2.2¶

10. The client presents the derived code value to the token endpoint for an access token, along with other parmeters¶

Throughout this process, the client and AS need not have previously agreed on any shared secrets or encodings. The client does not start an HTTP server and does not receive the call to the redirect URI at all.¶

The client does need to know the value of the INFO parameter of the HKDF that the helper page uses and use the same value.¶

1.  C  = UTF8(code)
2.  KS = HKDF(ikm  = UTF8(state),
              salt = "" (zero-length),
              info = INFO,
              L    = len(C)) ; always the same length as C
3.  E  = C ^ KS ; bytewise XOR
4.  T  = SHA256(C)[0..2] ; checksum
5.  CC = B64Uenc(T) || B64Uenc(E) ; concatenate the checksum

1.  T' = B64Udec(CC[0..3])
2.  E  = B64Udec(CC[4..len(CC)])
3.  KS = HKDF(ikm  = UTF8(state),
              salt = "" (zero-length),
              info = INFO,
              L    = len(E))
4.  C = E ^ KS ; bytewise XOR
5.  T = SHA256(C)[0..2] ; checksum
6.  If T != T': FAIL

3. Limitations and Implementation Considerations

4. Security Considerations

This process provides no additional security protections beyond that already provided by the basic authorization code grant. While cryptographic functions are used, the code value is still passed in the browser during the first steps and is not kept secret.¶

The code and state values are passed to whatever server, CDN, or system serves the static helper page, including its mirrors and caches, as part of the HTTP GET request.¶

The state value now needs to be cryptographically random enough to support the HKDF, and at the very least needs to be unique per request. Two identical (or guessable) state values could decode different codes on different requests.¶

5. IANA Considerations

This document has no IANA actions.¶

6. References

Acknowledgments

Thank you to Jeff Lombardo for an early review of this work.¶

Author's Address