feat: add RAR support to CIBA flows

resolves #1358

Author: panva

docs/README.md

@@ -2051,6 +2051,7 @@ _**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
@@ -2080,9 +2081,30 @@ rarForAuthorizationCode(ctx) {
 }
 ```
 
+#### 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**_:
+```js
+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. 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.  
+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**_:

lib/actions/authorization/index.js

@@ -174,8 +174,8 @@ export default function authorizationAction(provider, endpoint) {
   use(() => checkRedirectUri,                               A,                PAR    );
   use(() => checkPKCE,                                      A,                PAR    );
   use(() => checkClaims,                                    A, DA,            PAR, BA);
-  use(() => unsupportedRar,                                    DA,                 BA);
-  use(() => checkRar,                                       A,                PAR    );
+  use(() => unsupportedRar,                                    DA                    );
+  use(() => checkRar,                                       A,                PAR, BA);
   use(() => checkResource,                                  A, DA, R, CV, DR, PAR, BA);
   use(() => checkMaxAge,                                    A, DA,            PAR, BA);
   use(() => checkRequestedExpiry,                                                  BA);

lib/actions/grants/ciba.js

@@ -11,6 +11,7 @@ import epochTime from '../../helpers/epoch_time.js';
 import getCtxAccountClaims from '../../helpers/account_claims.js';
 import { setRefreshTokenBindings } from '../../helpers/set_rt_bindings.js';
 import { checkAttestBinding } from '../../helpers/check_attest_binding.js';
+import checkRar from '../../shared/check_rar.js';
 
 const {
   AuthorizationPending,
@@ -23,10 +24,6 @@ export const gty = 'ciba';
 export const handler = async function cibaHandler(ctx) {
   presence(ctx, 'auth_req_id');
 
-  if (ctx.oidc.params.authorization_details) {
-    throw new errors.InvalidRequest('authorization_details is unsupported for this grant_type');
-  }
-
   const {
     findAccount,
     issueRefreshToken,
@@ -36,6 +33,7 @@ export const handler = async function cibaHandler(ctx) {
       mTLS: { getCertificate },
       dPoP: { allowReplay },
       resourceIndicators,
+      richAuthorizationRequests,
     },
   } = instance(ctx.oidc.provider).configuration;
 
@@ -156,6 +154,7 @@ export const handler = async function cibaHandler(ctx) {
     at.setThumbprint('jkt', dPoP.thumbprint);
   }
 
+  await checkRar(ctx, () => {});
   const resource = await resolveResource(ctx, request, { userinfo, resourceIndicators });
 
   if (resource) {
@@ -168,6 +167,10 @@ export const handler = async function cibaHandler(ctx) {
     at.scope = grant.getOIDCScopeFiltered(request.scopes);
   }
 
+  if (richAuthorizationRequests.enabled && at.resourceServer) {
+    at.rar = await richAuthorizationRequests.rarForBackchannelResponse(ctx, at.resourceServer);
+  }
+
   ctx.oidc.entity('AccessToken', at);
   const accessToken = await at.save();
 
@@ -189,6 +192,7 @@ export const handler = async function cibaHandler(ctx) {
       scope: request.scope,
       sessionUid: request.sessionUid,
       sid: request.sid,
+      rar: request.rar,
     });
 
     await setRefreshTokenBindings(ctx, at, rt);
@@ -232,6 +236,7 @@ export const handler = async function cibaHandler(ctx) {
     refresh_token: refreshToken,
     scope: request.scope ? at.scope : (at.scope || undefined),
     token_type: at.tokenType,
+    authorization_details: at.rar,
   };
 };
 

lib/actions/grants/refresh_token.js

@@ -13,12 +13,11 @@ import checkRar from '../../shared/check_rar.js';
 import getCtxAccountClaims from '../../helpers/account_claims.js';
 import { checkAttestBinding } from '../../helpers/check_attest_binding.js';
 
-import { gty as cibaGty } from './ciba.js';
 import { gty as deviceCodeGty } from './device_code.js';
 
 function rarSupported(token) {
   const [origin] = token.gty.split(' ');
-  return origin !== cibaGty && origin !== deviceCodeGty;
+  return origin !== deviceCodeGty;
 }
 
 const gty = 'refresh_token';

lib/helpers/defaults.js

@@ -1933,7 +1933,8 @@ function makeDefaults() {
          *
          * description: 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. This function enables
+         *   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.
          */
@@ -1949,6 +1950,29 @@ function makeDefaults() {
             'features.richAuthorizationRequests.rarForCodeResponse not implemented',
           );
         },
+        /*
+         * features.richAuthorizationRequests.rarForBackchannelResponse
+         *
+         * description: 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.
+         */
+        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)
+          mustChange('features.richAuthorizationRequests.rarForBackchannelResponse', 'transform the requested and granted RAR details to be returned in the Access Token Response as authorization_details as well as assigned to the issued Access Token');
+          throw new Error(
+            'features.richAuthorizationRequests.rarForBackchannelResponse not implemented',
+          );
+        },
         /*
          * features.richAuthorizationRequests.rarForRefreshTokenResponse
          *

lib/models/backchannel_authentication_request.js

@@ -20,6 +20,7 @@ export default (provider) => class BackchannelAuthenticationRequest extends appl
       'error',
       'errorDescription',
       'params',
+      'rar',
     ];
   }
 };

lib/provider.js

@@ -237,6 +237,7 @@ export class Provider extends Koa {
     sessionUid,
     expiresWithSession,
     sid,
+    rar,
   } = {}) {
     if (typeof request === 'string' && request) {
       // eslint-disable-next-line no-param-reassign
@@ -281,6 +282,7 @@ export class Provider extends Koa {
           sessionUid,
           expiresWithSession,
           sid,
+          rar,
         });
         break;
       case result instanceof OIDCProviderError: