Skip to main content

OAuth Rich Authorization Requests (RAR)

Learn what rich authorization requests (RARs) are, what their advantages are, and when you should think about enabling RAR.

What Rich Authorization Requests (RAR) Are

OAuth 2.0 Rich Authorization Requests (RAR) is an OAuth 2.0 specification that allows client applications to extend the payload of authorization requests to the authorization server by adding authorization_details parameter containing more fine-grained authorization requirements than the standard scope mechanism.

Rich Authorization Requests (RAR) Example

The RAR instance presented in RFC 9396 serves as an illustrative example showcasing the practical application of Rich Authorization Requests (RAR) within the context of a request for bank transfer authorization.

{
   "type": "payment_initiation",
   "locations": [
      "https://example.com/payments"
   ],
   "instructedAmount": {
      "currency": "EUR",
      "amount": "123.50"
   },
   "creditorName": "Merchant A",
   "creditorAccount": {
      "bic":"ABCIDEFFXXX",
      "iban": "DE02100100109307118603"
   },
   "remittanceInformationUnstructured": "Ref Number Merchant"
}

This data structure provides an exhaustive repository of information regarding the scheduled payment. It covers a spectrum of crucial elements, including the precise payment amount, designated currency, and the creditor involved. These details are essential for informing the user and obtaining their consent. The enforcement of this consent is a collaborative effort between the authorization server and the corresponding resource server, which offers the payment initiation API.

Rich Authorization Requests (RAR) structure

RAR introduces a significant enhancement through the incorporation of the authorization_details parameter within the authorization request which takes the form of a JSON array of objects. The sole obligatory element within an object is the type, represented as a string, which determines the content of the authorization_details object. A single instance of the authorization_details parameter can encapsulate multiple objects sharing a common type. There is a common set of object's fields that are defined by RAR RFC.

  • locations - contain URLs that represent the location of a resource or resource server.

  • actions - contain the types of actions to be taken at the resource, e.g., read, write, deposit, withdraw.

  • datatypes - specify the type of data requested, e.g., files, photos, contacts.

  • identifier - identifies a specific resource available in the API, e.g., account-123, patient-987.

  • privileges - define the level of access requested for a given resource, e.g., admin.

While those fields are not obligatory, they serve as versatile building blocks for API designers, offering a comprehensive framework for customization. However, it is imperative to note that all fields and their respective values must be defined within the specific type.

Rich Authorization Requests (RAR) Use Case

RAR finds its utility in scenarios where the conventional scope mechanism falls short in delineating intricate authorization prerequisites. Instances where a more nuanced understanding is imperative for user consent are plentiful, encompassing a broad spectrum of applications.

Consider, for instance, a bank transfer, file sharing operation, or the retrieval of sensitive medical data. In these contexts, RAR shines by allowing for a deeper and more context-rich specification of the permissions sought. It empowers users to make informed decisions and grants organizations the flexibility to tailor authorization requests to the intricacies of each scenario.

In this section: