features.ciba

OIDC Client Initiated Backchannel Authentication Flow (CIBA)

Enables Core CIBA Flow, when combined with features.fapi and features.requestObjects.request enables Financial-grade API: Client Initiated Backchannel Authentication Profile - Implementer’s 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

Fine-tune the supported token delivery modes. Supported values are

• poll
• ping

default value:

[
  'poll'
]

processLoginHint

Helper function used to process the login_hint parameter and return the accountId value to use for processsing the request.

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

recommendation: Use return undefined or when you can’t determine the accountId from the 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

Helper function used to process the login_hint_token parameter and return the accountId value to use for processsing the request.

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

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

recommendation: Use return undefined or when you can’t determine the accountId from the login_hint.

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

Helper function used to trigger the authentication and authorization on end-user’s Authentication Device. It is called after accepting the backchannel authentication request but before sending client back the response.
When the end-user authenticates use provider.backchannelResult() to finish 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');
}

(Click to expand) provider.backchannelResult() method

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

const provider = new 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

Helper function used to process the binding_message parameter and throw if its not following the authorization server’s policy.

recommendation: Use throw new errors.InvalidBindingMessage('validation error message') when the binding_message is invalid.

recommendation: Use return undefined when a binding_message isn’t required and wasn’t provided.

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 && !/^[a-zA-Z0-9-._+/!?#]{1,20}$/.exec(bindingMessage)) {
    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

Helper function used to process the request_context parameter and throw if its not following the authorization server’s policy.

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

recommendation: Use return undefined when a request_context isn’t required and wasn’t provided.

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

Helper function used to verify the user_code parameter value is present when required and verify its value.

recommendation: Use throw new errors.MissingUserCode('validation error message') when user_code should have been provided but wasn’t.

recommendation: Use throw new errors.InvalidUserCode('validation error message') when the provided user_code is invalid.

recommendation: Use return undefined when no user_code was provided and isn’t required.

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');
}