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

Set the consent policy

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.

The following PATCH request sets the consent policy to transactional-authorization-with-mfa for an existing resource server:

curl --location --request PATCH 'https://$tenant/api/v2/resource_servers/$resource_server_id' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "consent_policy": "transactional-authorization-with-mfa"
  }'

Was this helpful?

/

Register authorization_details types

The resource server must register the authorization_details types that are accepted, similar to registering which scopes are allowed.

The following PATCH request registers payment_initiation and money_transfer as authorization_details types for an existing resource server:

curl --location --request PATCH 'https://$tenant/api/v2/resource_servers/$resource_server_id' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "authorization_details": [{"type": "payment_initiation"}, {"type": "money_transfer"}]
  }'

Was this helpful?

/

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?

/

Set customized consent prompt to render the authorization details

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.