features.richAuthorizationRequests

RFC9396 - OAuth 2.0 Rich Authorization Requests

Note

This is an experimental feature.

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.

default value:

{
  ack: undefined,
  enabled: false,
  rarForAuthorizationCode: [Function: rarForAuthorizationCode], // see expanded details below
  rarForBackchannelResponse: [Function: rarForBackchannelResponse], // see expanded details below
  rarForCodeResponse: [Function: rarForCodeResponse], // see expanded details below
  rarForIntrospectionResponse: [Function: rarForIntrospectionResponse], // see expanded details below
  rarForRefreshTokenResponse: [Function: rarForRefreshTokenResponse], // see expanded details below
  types: {}
}

(Click to expand) features.richAuthorizationRequests options details

rarForAuthorizationCode

Specifies a helper function that shall be invoked to transform the requested and granted Rich Authorization Request details for storage in the authorization code. This function enables filtering and processing of authorization details according to authorization server policy before code persistence. The function shall return an array of authorization details or undefined.

default value:

rarForAuthorizationCode(ctx) {
  // decision points:
  // - ctx.oidc.client
  // - ctx.oidc.resourceServers
  // - ctx.oidc.params.authorization_details (unparsed authorization_details from the authorization request)
  // - ctx.oidc.grant.rar (authorization_details granted)
  throw new Error(
    'features.richAuthorizationRequests.rarForAuthorizationCode not implemented',
  );
}

rarForBackchannelResponse

Specifies a helper function that shall be invoked to transform the requested and granted Rich Authorization Request details for inclusion in the Access Token Response as authorization_details and assignment to the issued Access Token during the ciba grant. This function enables resource-specific filtering and transformation of authorization details according to token endpoint policy. The function shall return an array of authorization details or undefined.

default value:

rarForBackchannelResponse(ctx, resourceServer) {
  // decision points:
  // - ctx.oidc.client
  // - resourceServer
  // - ctx.oidc.entities.BackchannelAuthenticationRequest.rar (the rar applied during await provider.backchannelResult())
  // - ctx.oidc.entities.BackchannelAuthenticationRequest.params.authorization_details (the original backchannel authentication request authorization_details object)
  // - ctx.oidc.params.authorization_details (unparsed authorization_details from the body params in the Access Token Request)
  // - ctx.oidc.grant.rar (authorization_details granted)
  throw new Error(
    'features.richAuthorizationRequests.rarForBackchannelResponse not implemented',
  );
}

rarForCodeResponse

Specifies a helper function that shall be invoked to transform the requested and granted Rich Authorization Request details for inclusion in the Access Token Response as authorization_details and assignment to the issued Access Token during the authorization code grant. This function enables resource-specific filtering and transformation of authorization details according to token endpoint policy. The function shall return an array of authorization details or undefined.

default value:

rarForCodeResponse(ctx, resourceServer) {
  // decision points:
  // - ctx.oidc.client
  // - resourceServer
  // - ctx.oidc.authorizationCode.rar (previously returned from rarForAuthorizationCode)
  // - ctx.oidc.params.authorization_details (unparsed authorization_details from the body params in the Access Token Request)
  // - ctx.oidc.grant.rar (authorization_details granted)
  throw new Error(
    'features.richAuthorizationRequests.rarForCodeResponse not implemented',
  );
}

rarForIntrospectionResponse

Specifies a helper function that shall be invoked to transform the token’s stored Rich Authorization Request details for inclusion in the Token Introspection Response. This function enables filtering and processing of authorization details according to introspection endpoint policy and requesting party authorization. The function shall return an array of authorization details or undefined.

default value:

rarForIntrospectionResponse(ctx, token) {
  // decision points:
  // - ctx.oidc.client
  // - token.kind
  // - token.rar
  // - ctx.oidc.grant.rar
  throw new Error(
    'features.richAuthorizationRequests.rarForIntrospectionResponse not implemented',
  );
}

rarForRefreshTokenResponse

Specifies a helper function that shall be invoked to transform the requested and granted Rich Authorization Request details for inclusion in the Access Token Response during refresh token exchanges as authorization_details and assignment to the newly issued Access Token. This function enables resource-specific processing of previously granted authorization details according to refresh token policy. The function shall return an array of authorization details or undefined.

default value:

rarForRefreshTokenResponse(ctx, resourceServer) {
  // decision points:
  // - ctx.oidc.client
  // - resourceServer
  // - ctx.oidc.refreshToken.rar (previously returned from rarForAuthorizationCode and later assigned to the refresh token)
  // - ctx.oidc.params.authorization_details (unparsed authorization_details from the body params in the Access Token Request)
  // - ctx.oidc.grant.rar
  throw new Error(
    'features.richAuthorizationRequests.rarForRefreshTokenResponse not implemented',
  );
}

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.

default value:

{}

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()
            }
          },
        },
      },
    },
  },
}

---