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. Returning undefined causes the request to fail because no end-user could be identified.

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: KoaContextWithOIDC,
  loginHint?: string,
): Promise<string | undefined> { /* implementation required */ }

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. Returning undefined causes the request to fail because no end-user could be identified.

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: KoaContextWithOIDC,
  loginHintToken?: string,
): Promise<string | undefined> { /* implementation required */ }

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: KoaContextWithOIDC,
  request: BackchannelAuthenticationRequest,
  account: Account,
  client: Client,
): Promise<void> { /* implementation required */ }

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: KoaContextWithOIDC,
  bindingMessage?: string,
): Promise<void> {
  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: KoaContextWithOIDC,
  requestContext?: string,
): Promise<void> { /* implementation required */ }

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: KoaContextWithOIDC,
  account: Account,
  userCode?: string,
): Promise<void> { /* implementation required */ }