Configure Rich Authorization Requests (RAR)

Prerequisites

Before configuring Rich Authorization Requests (RAR) for an API, first set up: 

  • A custom domain.

  • A custom Universal Login Pages template. Read the Page templates API to learn how to customize a Universal Login Page template using the Management API.

Configure the resource server

The consent policy determines when and how Auth0 shows the consent prompt to the end user.

The resource server (i.e. the API) registered in an Auth0 tenant needs to define in advance which consent policy to apply to authorize the Rich Authorization Request (RAR). 

The default consent policy is null or undefined. Auth0 also supports the consent policy, transactional-authorization-with-mfa, which covers the transactional authorization use case that always requires the explicit consent of the resource owner (i.e the end user). The table below summarizes Auth0's consent policy behavior:

Is it a Rich Authorization Request? MFA Required? null or undefined (default) transactional-authorization-with-mfa
No No Standard consent is shown unless there is a grant that includes the requested access. Customized consent is shown regardless of previously granted accesses.
Yes No Authorization request is rejected with invalid_request. Customized consent is shown regardless of previously granted accesses.
Yes Yes, with an authentication factor that is not a push notification Authorization request is rejected with invalid_request. Customized consent is shown after the user fulfills MFA challenges.
Yes Yes, with a push notification factor Authorization request is rejected with invalid_request. No consent is shown. The consent is handled in the mobile application that received the push notification challenge.

Set the consent policy in your API settings using the Auth0 Dashboard.

  1. Navigate to Auth0 Dashboard > Applications > APIs.

  2. Select the Settings tab.

  3. Under Access Settings, choose Transactional Authorization with MFA.

  4. Save your changes.

Dashboard > Applications > APIs > Settings > Access Settings

Register authorization_details types

The resource server must register the authorization_details types that are accepted, similar to registering which scopes are allowed. Make sure the authorization_details follows these requirements:

  • Maximum 5Kb

  • Must be valid JSON

  • Must be an array of objects

  • Maximum of 5 entries in the array

  • Every object must have a type property (that is pre-registered on the API)

  • Maximum of 10 properties per object

  • Maximum length of property names is 255

  • Maximum length of property value is 255

  • Maximum of 5 levels of nested objects

  • Property names can only contain the following characters: a-zA-Z0-9_.-

You can register authorization_details types with the Auth0 Dashboard or Management API.

You can add authorization_details in the Auth0 Dashboard.

  1. Navigate to Auth0 Dashboard > Applications > APIs.

  2. Select the Permissions tab.

  3. Under Add an Authorization Details type, add payment_initiation. Select the +Add option. Add money_transfer and select the +Add option.

Dashboard > Applications > APIs > Permissions

Create a resource server for Rich Authorization Requests

The following POST request creates and configures a resource server to receive Rich Authorization Requests:

curl --location --request POST 'https://$tenant/api/v2/resource-servers/' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "Payments API",
  "identifier": "https://payments.api/",
  "consent_policy": "transactional-authorization-with-mfa",
  "authorization_details": [{"type": "payment_initiation"}]
  }'

Was this helpful?

/

To render the authorization details of a Rich Authorization Request in the consent screen, you need to configure the customized-consent prompt with the appropriate template partials.

The following PUT request configures the customized consent partials:

curl --location --request PUT "https://$tenant/api/v2/prompts/customized-consent/partials" \
    --header "Authorization: Bearer $management_access_token" \
    --header "Content-Type: application/json" \
    --data '{
          "customized-consent": {
            "form-content": "<div style=\"font-size: 1.3em; font-weight: bold;\">Operation Details</div><hr style=\"margin: 10px 0;\"><div style=\"margin-bottom: 20px;\"></div><div style=\"font-weight: bold;\">Transaction Type</div><div>{{ transaction.params.authorization_details[0].type }}</div><div style=\"margin-bottom: 20px;\"></div><div style=\"font-weight: bold;\">Amount</div><div>{{ transaction.params.authorization_details[0].instructedAmount.amount }} {{ transaction.params.authorization_details[0].instructedAmount.currency }}</div><div style=\"margin-bottom: 20px;\"></div><div style=\"font-weight: bold;\">Recipient</div><div>{{ transaction.params.authorization_details[0].beneficiary }}</div><div style=\"margin-bottom: 20px;\"></div><div style=\"font-weight: bold;\">Destination Account</div><div>{{ transaction.params.authorization_details[0].destinationAccount }}</div><div style=\"margin-bottom: 20px;\"></div>"
          }
        }'

Was this helpful?

/

The customized consent template renders the authorization details in the following consent prompt that Auth0 shows to the end user:

To learn more about how to customize the consent prompt, read Customize New Universal Login Pages and Customize New Universal Login with the No-Code Editor.