oauth2-purpose-01 August 2025
Postnikov Standards Track [Page]
Workgroup:
TBC
Published:
Author:
DP. Postnikov
ConnectID

OAuth 2 Purpose Request Parameter Implementers' Draft 1

Introduction

This specification introduces a new OAuth 2.0 RFC6749 extension to capture a transaction level human readable purpose for any OAuth 2.0 authorization (e.g.: limited access to an HTTP service). Purpose is intended to be displayed to a resource owner during and after the approval interaction.

Notational Conventions

The key words "shall", "shall not", "should", "should not", "may", and "can" in this document are to be interpreted as described in ISO Directive Part 2. These key words are not used as dictionary terms such that any occurrence of them shall be interpreted as key words and are not to be interpreted with their natural language meanings.

▲

Table of Contents

1. Normative references

The following referenced documents are indispensable for the application of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.

RFC6749 - The OAuth 2.0 Authorization Framework

RFC9126 - OAuth 2.0 Pushed Authorization Requests

ISODIR2 - ISO/IEC Directives Part 2

2. Non-normative references

OWASP - C4: Encode and Escape Data

3. Transaction specific purpose

"purpose" is a text description that provides context to the Resource Owner about the authorization request. This human-readable string appears in the Authorization Server's user interface during the authorization flow and/or afterwards.

To set a transaction specific purpose, use the additional purpose parameter as part of the request: purpose={Purpose}.

The purpose parameter value:

  1. shall be human-readable text in any language encoded as UTF-8.
  2. shall not be shorter than 3 characters
  3. shall not be longer than 300 characters

If these rules are violated, the authorization request shall fail and the authorization response redirection URL (HTTP status code 302) will contain the parameters error=invalid_request and error_description=invalid_purpose.

4. Authorization request parameter

This specification introduces a new request parameter to be supplied by a client as a part of the authorization request.

Table 1
Parameter Description
purpose Transaction specific purpose as descibed in this specification

5. Authorization Server

The Authorization Server:

  1. shall record the purpose supplied by the client for each transaction, if supplied.

6. Client

The Client:

  1. should supply purpose for each transaction.

7. Authorization request examples

7.1. Example with parameters conveyed via query string

The following is a non-normative example of a request with purpose supplied via query string:

     GET /authorize?client_id=s6BhdRkqt3&response_type=code&redirect_uri=https://example.com/callback&purpose=Account%20Access HTTP/1.1
     Host: as.example.com

7.2. Invalid purpose error message example

The following is an example of an error message returned if the Client provides an invalid purpose:

https://{Redirect URI}?state=-ZBPQz_Rj5DA8c9X7Y9wzgiMsJYdtYoRpwOB0qdeyBQ
&error=invalid_request&error_description=Invalid%20Purpose

7.3. Example with parameters conveyed via Pushed Authorization Request (PAR)

The following is a non-normative example of a request with purpose supplied via PAR RFC9126:

     POST /as/par HTTP/1.1
     Host: as.example.com
     Content-Type: application/x-www-form-urlencoded

&client_id=s6BhdRkqt3
&response_type=code
&state=duk681S8n00GsJpe7n9boxdzen
&redirect_uri=https://example.com/callback
&purpose=Account%20Access
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJraWQiOiI0MiIsImFsZyI6IkVTMjU2In0.eyJpc3MiOiJDTElFTlQxMjM0Iiwic3ViIjoiQ0xJRU5UMTIzNCIsImF1ZCI6Imh0dHBzOi8vc2VydmVyLmV4YW1wbGUuY29tIiwiZXhwIjoxNjI1ODY4ODc4fQ.Igw8QrpAWRNPDGoWGRmJumLBMwbLjeIYwqWUu-ywgvvufl_0sQJftNs3bzjIrP0BV9rRG-3eI1Ksh0kQ1CwvzA

8. Acknowledgements

=======

9. Security considerations

9.1. Code Injection and Input Validation

In line with section 10.14 of OAuth 2.0 specification RFC6749, the authorization server shall validate any value received in purpose parameter.

Apart from syntactic validation (e.g. length), the authorization server may apply additional semantic validation.

The string containing purpose parameter shall be encoded and escaped before displaying it in any UI. See OWASP section C4 recommendations for more details.

10. Acknowledgements

We would like to thank Daniel Fett, Mark Haine, Joseph Heenan, Ralph Bragg, Paul Ruskin, Igor Janicijevic, Diogo Goncalves and others for their valuable feedback and contributions that helped to evolve this specification.

Appendix A. Notices

Appendix B. Change History

B.1. Version 1.0 Implementers Draft 1

Published: 21st September 2023

Changes:

  • Add PAR example (21st September 2023)
  • Added security considerations (21st September 2023)
  • Purpose description tweaked (21st September 2023)
  • Minor editorial and akcnowledgements (20th Sep 2023)
  • Initial draft (22nd May 2023)
  • Updated authorization request example (4th September 2023)

Author's Address

Dima Postnikov
ConnectID
URI: www.connectid.com.au