]> MongoDB

ietf@justin.richer.org

Security Web Authorization Protocol next generation unicorn AI-native This client-side process allows clients to use the authorization code grant type without the ability to host the redirect_uri themselves. This process creates a single copyable value that the resource owner can copy from a simple helper page into the waiting client application. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction The OAuth authorization code grant type defined in 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 , 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).

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 when, and only when, they appear in all capitals, as shown here.

Out of Band Authorization Code Transfer | | | | | | | | | |--(2)------------------------->| | | | | | | | | |<-(3)----------| | | | | | | | | |--(4)--------->| | | | | | | | | | |--(5)--------->| | | | | | | | | | |--+ | | | | | | (6) | | | | |<-+ | | | | | |<-(7)----------------------------------------------------------| | | | | | |--(8)--------->| | | | | | | | | | |--+ | | | | | | (9) | | | | |<-+ | | | | | | | | | |--(10)-------->| | | | | | | | ]]>

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
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
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.

Creating the Combined Code The state and code values are combined using a HKDF function and a simple bytewise XOR.

1. The code is translated to UTF8 bytes. Since the authorization code is ASCII per , no additional encoding is needed for valid inputs.
2. The HKDF function creates a derived key based on the state value, the result that is exactly the same length as the code value.
3. The code value and the HKDF output are XORed together, bytewise, to create an encoded value E.
4. A 3-byte checksum is created by hashing the code value with .
5. The combined code CC is the concatenated checksum from (4) and the encoded value E from (3), both separately base64 URL encoded (with no padding).

The helper page MUST display the combined code value to the user.

Processing the Combined Code When the client receives the combined code, it uses its state value and extracts the code value for use at the AS.

1. Extract the checksum as sent over the wire and decode it using Base64 URL with no padding into 3 bytes (4 Base64 chars).
2. Decode the remainder of the string into a byte array representing the encoded value E.
3. The HKDF function creates the derived key based on the state value, the result is exactly the same length as the encoded value E.
4. The combined code and the HKDF output are XORed together, bytewise, to extract the code.
5. A 3-byte checksum is created by hashing the extracted code value with .
6. If the checksum against the extracted code doesn't match the checksum sent over the wire, fail.

Any combined codes equal to or fewer than the checksum length (4 characters / 3 decoded bytes) MUST be discarded. The client then uses the code value in its request to the token endpoint. If the state value doesn't match, the key derivation will fail to produce a valid code, and the token request will fail.

Limitations and Implementation Considerations

Helper Page The helper page is designed to be a statically hosted page with no backend processing and no state. Consequently, any person (or attacker) could use the same page to create combined codes using this algorithm by providing arbitrary code and state values. As such, the use of this does not protect clients from theft of code and state values.

Stateless Clients In order to use this, a client needs to know its state value at the time the request comes in. Stateless clients that depend on the state value to bootstrap the request won't be able to extract the code value from a combined code and shouldn't use this method.

Fall-through For Static Pages If the helper page is unable to process the HKDF calculation, such as JavaScript being disabled, the helper page SHOULD tell the user as much. To support such cases, the client SHOULD additionally support the user copying and pasting the entire helper page URL, with parameters, and extracting the code and state values directly, just as if the client had served the URL itself. For this case, there is no use of the HKDF to create a combined code.

Issuer Parameter This process focuses only on the code and state parameters, and drops all other parameters including iss. This value could be used as the INFO parameter to the HKDF, but only if the client knows that the iss parameter is returned from the AS.

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.

IANA Considerations This document has no IANA actions.

References Normative References The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. This specification replaces and obsoletes the OAuth 1.0 protocol described in RFC 5849. [STANDARDS-TRACK] This document specifies a simple Hashed Message Authentication Code (HMAC)-based key derivation function (HKDF), which can be used as a building block in various protocols and applications. The key derivation function (KDF) is intended to support a wide range of applications and requirements, and is conservative in its use of cryptographic hash functions. This document is not an Internet Standards Track specification; it is published for informational purposes. This document describes the commonly used base 64, base 32, and base 16 encoding schemes. It also discusses the use of line-feeds in encoded data, use of padding in encoded data, use of non-alphabet characters in encoded data, use of different encoding alphabets, and canonical encodings. [STANDARDS-TRACK] Federal Information Processing Standard, FIPS In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Informative References The OAuth 2.0 device authorization grant is designed for Internet- connected devices that either lack a browser to perform a user-agent- based authorization or are input constrained to the extent that requiring the user to input text in order to authenticate during the authorization flow is impractical. It enables OAuth clients on such devices (like smart TVs, media consoles, digital picture frames, and printers) to obtain user authorization to access protected resources by using a user agent on a separate device.

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