features.ciba

OIDC Client Initiated Backchannel Authentication Flow (CIBA)

Specifies whether Core CIBA Flow shall be enabled. When combined with features.fapi and features.requestObjects this also enables Financial-grade API: Client Initiated Backchannel Authentication Profile - Implementers Draft 01 as well.

default value:

{
  deliveryModes: [
    'poll'
  ],
  enabled: false,
  processLoginHint: [AsyncFunction: processLoginHint], // see expanded details below
  processLoginHintToken: [AsyncFunction: processLoginHintToken], // see expanded details below
  triggerAuthenticationDevice: [AsyncFunction: triggerAuthenticationDevice], // see expanded details below
  validateBindingMessage: [AsyncFunction: validateBindingMessage], // see expanded details below
  validateRequestContext: [AsyncFunction: validateRequestContext], // see expanded details below
  verifyUserCode: [AsyncFunction: verifyUserCode] // see expanded details below
}

(Click to expand) features.ciba options details

deliveryModes

Specifies the token delivery modes supported by this authorization server. The following delivery modes are defined:

• poll - Client polls the token endpoint for completion
• ping - Authorization server notifies client of completion via HTTP callback

default value:

[
  'poll'
]

processLoginHint

Specifies a helper function that shall be invoked to process the login_hint parameter and extract the corresponding accountId value for request processing. This function MUST validate the hint format and content according to authorization server policy.

recommendation: Use throw new errors.InvalidRequest('validation error message') when the login_hint format or content is invalid.

recommendation: Use return undefined when the accountId cannot be determined from the provided login_hint.

default value:

async function processLoginHint(ctx, loginHint) {
  // @param ctx - koa request context
  // @param loginHint - string value of the login_hint parameter
  throw new Error('features.ciba.processLoginHint not implemented');
}

processLoginHintToken

Specifies a helper function that shall be invoked to process the login_hint_token parameter and extract the corresponding accountId value for request processing. This function MUST validate token expiration and format according to authorization server policy.

recommendation: Use throw new errors.ExpiredLoginHintToken('validation error message') when the login_hint_token has expired.

recommendation: Use throw new errors.InvalidRequest('validation error message') when the login_hint_token format or content is invalid.

recommendation: Use return undefined when the accountId cannot be determined from the provided login_hint_token.

default value:

async function processLoginHintToken(ctx, loginHintToken) {
  // @param ctx - koa request context
  // @param loginHintToken - string value of the login_hint_token parameter
  throw new Error('features.ciba.processLoginHintToken not implemented');
}

triggerAuthenticationDevice

Specifies a helper function that shall be invoked to initiate authentication and authorization processes on the end-user’s Authentication Device as defined in the CIBA specification. This function is executed after accepting the backchannel authentication request but before transmitting the response to the requesting client.

Upon successful end-user authentication, implementations shall use provider.backchannelResult() to complete the Consumption Device login process.

default value:

async function triggerAuthenticationDevice(ctx, request, account, client) {
  // @param ctx - koa request context
  // @param request - the BackchannelAuthenticationRequest instance
  // @param account - the account object retrieved by findAccount
  // @param client - the Client instance
  throw new Error('features.ciba.triggerAuthenticationDevice not implemented');
}

Example: (Click to expand) provider.backchannelResult() method.

backchannelResult is a method on the Provider prototype, it returns a Promise with no fulfillment value.

import * as oidc from 'oidc-provider';
const provider = new oidc.Provider(...);
await provider.backchannelResult(...);

backchannelResult(request, result[, options]);

• request BackchannelAuthenticationRequest - BackchannelAuthenticationRequest instance.
• result Grant | OIDCProviderError - instance of a persisted Grant model or an OIDCProviderError (all exported by errors).
• options.acr?: string - Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied.
• options.amr?: string[] - Identifiers for authentication methods used in the authentication.
• options.authTime?: number - Time when the end-user authentication occurred.

validateBindingMessage

Specifies a helper function that shall be invoked to validate the binding_message parameter according to authorization server policy. This function MUST reject invalid binding messages by throwing appropriate error instances.

recommendation: Use throw new errors.InvalidBindingMessage('validation error message') when the binding_message violates authorization server policy.

recommendation: Use return undefined when a binding_message is not required by policy and was not provided in the request.

default value:

async function validateBindingMessage(ctx, bindingMessage) {
  // @param ctx - koa request context
  // @param bindingMessage - string value of the binding_message parameter, when not provided it is undefined
  if (bindingMessage?.match(/^[a-zA-Z0-9-._+/!?#]{1,20}$/) === null) {
    throw new errors.InvalidBindingMessage(
      'the binding_message value, when provided, needs to be 1 - 20 characters in length and use only a basic set of characters (matching the regex: ^[a-zA-Z0-9-._+/!?#]{1,20}$ )',
    );
  }
}

validateRequestContext

Specifies a helper function that shall be invoked to validate the request_context parameter according to authorization server policy. This function MUST enforce policy requirements for request context validation and reject non-compliant requests.

recommendation: Use throw new errors.InvalidRequest('validation error message') when the request_context is required by policy but missing or invalid.

recommendation: Use return undefined when a request_context is not required by policy and was not provided in the request.

default value:

async function validateRequestContext(ctx, requestContext) {
  // @param ctx - koa request context
  // @param requestContext - string value of the request_context parameter, when not provided it is undefined
  throw new Error('features.ciba.validateRequestContext not implemented');
}

verifyUserCode

Specifies a helper function that shall be invoked to verify the presence and validity of the user_code parameter when required by authorization server policy.

recommendation: Use throw new errors.MissingUserCode('validation error message') when user_code is required by policy but was not provided.

recommendation: Use throw new errors.InvalidUserCode('validation error message') when the provided user_code value is invalid or does not meet policy requirements.

recommendation: Use return undefined when no user_code was provided and it is not required by authorization server policy.

default value:

async function verifyUserCode(ctx, account, userCode) {
  // @param ctx - koa request context
  // @param account -
  // @param userCode - string value of the user_code parameter, when not provided it is undefined
  throw new Error('features.ciba.verifyUserCode not implemented');
}

---