features.richAuthorizationRequests

RFC9396 - OAuth 2.0 Rich Authorization Requests

Specifies whether Rich Authorization Request capabilities shall be enabled. When enabled, the authorization server shall support the authorization_details parameter at the authorization and token endpoints to enable issuing Access Tokens with fine-grained authorization data and enhanced authorization scope control.

This provider profile requires features.resourceIndicators and supports authorization requests whose response type contains code but not token. Deployments handling sensitive authorization details SHOULD use JAR or PAR, sanitize all consent presentation, compare string values exactly without Unicode normalization, and disclose details to clients and Resource Servers only as required by policy.

default value:

{
  authorizationDetailsForAccessToken: [Function: authorizationDetailsForAccessToken], // see expanded details below
  authorizationDetailsForGrantSource: [Function: authorizationDetailsForGrantSource], // see expanded details below
  authorizationDetailsForIntrospection: [Function: authorizationDetailsForIntrospection], // see expanded details below
  enabled: false,
  types: {}
}

(Click to expand) features.richAuthorizationRequests options details

authorizationDetailsForAccessToken

Specifies a helper function that shall be invoked before an AccessToken or ClientCredentials token is persisted whenever Rich Authorization Request details were requested or inherited from the grant source. The function shall perform type-specific grant comparison, client policy enforcement, resource-specific filtering, and any response enrichment. It shall return the exact authorization details assigned to the access token and returned from the token endpoint, or undefined. An empty array is treated as undefined. source is the exchanged grant source, or undefined for client credentials; grantType is the exact token request grant_type value, including full URN values. To reject client-provided authorization details, throw errors.InvalidAuthorizationDetails.

default value:

function authorizationDetailsForAccessToken(
  ctx: KoaContextWithOIDC,
  token: AccessToken | ClientCredentials,
  source: | AuthorizationCode
        | BackchannelAuthenticationRequest
        | DeviceCode
        | PreAuthorizedCode
        | RefreshToken
        | undefined,
  grantType: string,
): CanBePromise<readonly AuthorizationDetail[] | undefined> { /* implementation required */ }

authorizationDetailsForGrantSource

Specifies a helper function that shall be invoked before an AuthorizationCode or DeviceCode grant source is persisted when Rich Authorization Request details were requested or granted. The function shall apply authorization server policy to the requested and granted details and return the authorization details to store in the grant source, or undefined. An empty array is treated as undefined.

default value:

function authorizationDetailsForGrantSource(
  ctx: KoaContextWithOIDC,
  source: AuthorizationCode | DeviceCode,
): CanBePromise<readonly AuthorizationDetail[] | undefined> { /* implementation required */ }

authorizationDetailsForIntrospection

Specifies a helper function that shall be invoked when a token containing Rich Authorization Request details is introspected. It shall apply authorization server policy for the requesting party and return the authorization details to include as the top-level authorization_details introspection response member, or undefined. An empty array is treated as undefined.

default value:

function authorizationDetailsForIntrospection(
  ctx: KoaContextWithOIDC,
  token: AccessToken | ClientCredentials | RefreshToken,
): CanBePromise<readonly AuthorizationDetail[] | undefined> { /* implementation required */ }

types

Specifies the authorization details type identifiers that shall be supported by the authorization server. Each type identifier MUST have an associated validation function that defines the required structure and constraints for authorization details of that specific type according to authorization server policy. The validation function is responsible for rejecting unknown fields as well as missing or invalid type-specific fields with errors.InvalidAuthorizationDetails.

default value:

const types: Readonly<Record<string, RichAuthorizationRequestType>> = {};

Example: (Click to expand) Authorization details type validation for tax data access.

import { z } from 'zod'
const TaxData = z
  .object({
    duration_of_access: z.number().int().positive(),
    locations: z
      .array(
        z.literal('https://taxservice.govehub.no.example.com'),
      )
      .length(1),
    actions: z
      .array(z.literal('read_tax_declaration'))
      .length(1),
    periods: z
      .array(
        z.coerce
          .number()
          .max(new Date().getFullYear() - 1)
          .min(1997),
      )
      .min(1),
    tax_payer_id: z.string().min(1),
  })
  .strict()
const configuration = {
  features: {
    richAuthorizationRequests: {
      enabled: true,
      // ...
      types: {
        tax_data: {
          validate(ctx, detail, client) {
            const { success: valid, error } =
              TaxData.safeParse(detail)
            if (!valid) {
              throw new InvalidAuthorizationDetails()
            }
          },
        },
      },
    },
  },
}