How to Configure authorizationDetails for Rich Authorization Requests in Auth0-Auth-JS

To configure authorizationDetails for Rich Authorization Requests (RAR) in Auth0-Auth-JS, pass an array of AuthorizationDetails objects via the authorizationDetails option when calling backchannelAuthentication() or initiateBackchannelAuthentication(). The SDK automatically serializes this array to JSON and transmits it as the authorization_details parameter to Auth0's /bc-authorize endpoint.

Rich Authorization Requests (RAR), defined in RFC 8707, enable fine-grained authorization specifications in OAuth 2.0 flows. The auth0/auth0-auth-js repository implements first-class, type-safe support for RAR within Client-Initiated Backchannel Authentication (CIBA) flows, allowing developers to define precise authorization requirements using the authorizationDetails parameter.

Understanding the AuthorizationDetails Interface

The SDK models RAR data using the AuthorizationDetails interface defined in src/types.ts (lines 489-492). This interface requires a type field representing the RAR type identifier, while allowing arbitrary extension properties for custom authorization data.

// src/types.ts
export interface AuthorizationDetails {
  readonly type: string;
  readonly [parameter: string]: unknown;
}

This structure accommodates standard RAR types (such as payment_initiation or account_information) alongside custom domain-specific types. The index signature permits any additional properties required by your specific authorization scenario.

Configuring authorizationDetails in CIBA Methods

The library supports RAR configuration in both full token exchange and initiate-only CIBA methods. In src/auth-client.ts, the SDK handles serialization via JSON.stringify() before appending the parameter to the request.

Using backchannelAuthentication

When calling backchannelAuthentication (lines 480-482 in src/auth-client.ts), supply the authorizationDetails array in the options object:

params.append('authorization_details', JSON.stringify(options.authorizationDetails));

This automatic serialization ensures proper URL-encoding and JSON formatting for the Auth0 /bc-authorize endpoint.

Using initiateBackchannelAuthentication

For flows requiring only the auth_req_id (polling scenarios), initiateBackchannelAuthentication (lines 534-536 in src/auth-client.ts) implements identical RAR handling:

params.append('authorization_details', JSON.stringify(options.authorizationDetails));

Both methods append the serialized data to the request body sent to Auth0's backchannel authorization endpoint.

Alternative: Raw authorization_params Configuration

If you construct authorization parameters manually, embed the JSON string directly within the authorizationParams object:

await authClient.backchannelAuthentication({
  bindingMessage: 'Approve login',
  loginHint: { sub: 'auth0|987654321' },
  authorizationParams: {
    authorization_details: JSON.stringify([
      { type: 'accepted' },
    ]),
  },
});

This approach bypasses the typed authorizationDetails option while achieving identical protocol behavior.

Receiving Authorization Details in TokenResponse

After Auth0 processes the request, any echoed RAR data returns in the token response. The TokenResponse class (defined in src/types.ts, lines 525-531) exposes this via the optional authorizationDetails property:

// TokenResponse includes:
authorizationDetails?: AuthorizationDetails[];

Unit tests in src/auth-client.spec.ts (lines 925-933) verify that supplied authorizationDetails arrays correctly round-trip through the Auth0 backend and appear in the response object.

Complete Code Examples for RAR Configuration

Basic RAR with Immediate Token Exchange

Configure Rich Authorization Requests during a standard backchannel authentication flow:

import { AuthClient } from '@auth0/auth0-auth-js';

const authClient = new AuthClient({
  domain: 'YOUR_DOMAIN',
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
  authorizationParams: { audience: 'https://api.example.com' },
});

const response = await authClient.backchannelAuthentication({
  bindingMessage: 'Approve login for ExampleApp',
  loginHint: { sub: 'auth0|1234567890' },
  authorizationDetails: [
    {
      type: 'urn:example:payment',
      actions: ['pay', 'refund'],
      amount: 49.99,
      currency: 'USD',
    },
  ],
});

console.log('Access token:', response.accessToken);
console.log('Returned RAR type:', response.authorizationDetails?.[0].type);

RAR in Initiate-Only Flows

Configure authorizationDetails when obtaining only the authorization request ID for later polling:

const init = await authClient.initiateBackchannelAuthentication({
  bindingMessage: 'Approve login',
  loginHint: { sub: 'auth0|123' },
  authorizationDetails: [{ type: 'accepted' }],
});

console.log('Auth request ID:', init.authReqId);
// authorization_details was sent to Auth0 during initiation

Summary

• The AuthorizationDetails interface in src/types.ts defines the RAR structure with a required type string and extensible property signatures.
• Both backchannelAuthentication and initiateBackchannelAuthentication methods in src/auth-client.ts accept an authorizationDetails option and automatically serialize it using JSON.stringify() before transmission.
• Auth0 validates the RAR payload against the client's configured authorization_details_types_supported and echoes applicable details in the TokenResponse, accessible via the authorizationDetails property.
• The unit tests in src/auth-client.spec.ts confirm correct parameter forwarding and response handling for Rich Authorization Requests.

Frequently Asked Questions

What RFC standard defines Rich Authorization Requests?

Rich Authorization Requests are defined in RFC 8707. The Auth0-Auth-JS SDK implements this standard specifically for CIBA flows by mapping the JavaScript authorizationDetails option to the OAuth 2.0 authorization_details parameter.

Can I use authorizationDetails with authorization code flows or other grant types?

Based on the current implementation in src/auth-client.ts, the authorizationDetails parameter is specifically handled within the backchannelAuthentication and initiateBackchannelAuthentication methods for CIBA flows. Support for other OAuth 2.0 flows would require explicit implementation in the respective authorization methods.

How does the SDK validate the authorizationDetails structure?

The SDK relies on TypeScript typing via the AuthorizationDetails interface but does not perform runtime validation of RAR content. Auth0's authorization server validates the authorization_details against the client configuration's authorization_details_types_supported after receiving the request.

What happens if Auth0 modifies the authorizationDetails in the response?

The TokenResponse constructor captures any authorization_details returned by Auth0 into the authorizationDetails property (as defined in src/types.ts lines 525-531). Always inspect response.authorizationDetails after token exchange, as Auth0 may filter or modify the requested authorization details based on policy or user consent.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}