Authorization Code Flow with Rich Authorization Requests (RAR)

Rich Authorization Requests (RAR) extends the OAuth2 protocol to provide a way for clients to request and obtain fine-grained authorization data from resource owners such as end users during the Authorization Code Flow.

In traditional OAuth2 flows, clients typically request access to a set of scopes from a resource server, and the resource owner grants access to those resources to the client. However, this approach does not allow for granular control over the access granted to a client and can lead to over-provisioning of access, which can pose security risks.

With RAR, clients can pass an authorization_details parameter to request specific permissions for each resource they wish to access. This allows for more fine-grained control over access and can help mitigate security risks associated with over-provisioning.

Overall, RAR is a powerful extension to the OAuth2 protocol that provides enhanced security and control over resource access for both clients and resource owners.

How do I use it?

After you configure RAR for your API, you can add the authorization_details parameter to a request passed to the /par endpoint. The parameter is an array of objects. Each object must have a type field, but types do not have to be unique in the array. Here’s an example using the authorization code flow:

curl --location 'https://$tenant/oauth/par' \
--request POST \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=$client_id' \
--data-urlencode 'client_secret=$client_secret' \
--data-urlencode 'redirect_uri=https://jwt.io' \
--data-urlencode 'audience=urn:my-api' \
--data-urlencode 'response_type=code' \
--data-urlencode 'authorization_details=[{"type": "money_transfer", "instructedAmount": {"amount": 2500, "currency": "USD"},   "sourceAccount": "xxxxxxxxxxx1234", "destinationAccount": "xxxxxxxxxxx9876", "beneficiary": "Hanna Herwitz", "subject": "A Lannister Always Pays His Debts"}]'

Was this helpful?

/

Each authorization_details element can be completely custom as long as it contains a type field.

When you exchange your authorization code at the /oauth/token endpoint, as illustrated by the following code sample:

POST https://$tenant/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=[CLIENT_ID]&client_secret=[CLIENT_SECRET]&code=[AUTHZ_CODE]&redirect_uri=https://jwt.io

Was this helpful?

/

You receive a response with the access token and authorization_details array:

{
  "access_token": "ey...ZQ",
  "expires_in": 86400,
  "authorization_details": [
{
  "type": "money_transfer", 
  "instructedAmount": {"amount": 2500, "currency": "USD"},   
  "sourceAccount": "xxxxxxxxxxx1234", 
  "destinationAccount": "xxxxxxxxxxx9876", 
  "beneficiary": "Hanna Herwitz", 
  "subject": "A Lannister Always Pays His Debts"
}
  ],
  "token_type": "Bearer"
}

Was this helpful?

/

The authorization_details array helps the client understand the scope of the authorization granted to it without having to inspect the access token. In general, the client should never inspect the access token, which is detailed in the IETF’s JSON Web Token Profile for OAuth 2.0 Access Tokens. Instead, the resource server is the one that needs to inspect the access token.

If the requested audience is an API configured to use JWE access tokens, all fields apart from type will be removed from authorization_details elements in the response from the /oauth/token endpoint. Access token claims are unaffected.

{
  "iss": "https://my_tenant.auth0.com/",
  "sub": "auth0|me",
  "aud": "https://myapi.authzero.com",
  "iat": 1683661385,
  "exp": 1683747785,
  "azp": "my_client",
  "authorization_details": [
{
  "type": "money_transfer", 
  "instructedAmount": {"amount": 2500, "currency": "USD"},   
  "sourceAccount": "xxxxxxxxxxx1234", 
  "destinationAccount": "xxxxxxxxxxx9876", 
  "beneficiary": "Hanna Herwitz", 
  "subject": "A Lannister Always Pays His Debts"
}
  ]
}

Was this helpful?

/

Access authorization_details in Actions

In addition to the standard protocol support, we also expose RAR inside the post-login Action via the event.transaction.requested_authorization_details property. Use this property to make decisions about the transaction, including stepping up Multi-Factor Authentication.

What doesn’t Auth0 support?

At this stage, Auth0 doesn’t support:

  • Updating RAR in Actions.

  • Advertising RAR types for clients to discover.

Validate the RAR objects beyond checking that they have a type property that matches allowed types for the API. For more information, see Configure RAR.

Learn more