RequestChallengeQuestions Method

Download the challenge questions when Multi-Factor Authentication (MFA) is required.

Syntax

fiprofile.requestChallengeQuestions([callback])

Callback

The 'callback' parameter specifies a function which will be called when the operation completes (or an error is encountered). If the 'callback' parameter is not specified, then the method will block and will not return until the operation completes (or an error is encountered).

The callback for this method is defined as:

function(err){ }

'err' is the error that occurred. If there was no error, then 'err' is 'null'.

'err' has 2 properties which hold detailed information:

err.code
err.message

Remarks

This function generates the Signon and Multi-Factor Authentication challenge questions request page, submits it to the financial institution via HTTP, receives the response, and parses it.

When sending requests to a FI, if the information in the signon request is correct, but it is not sufficient to authenticate the user, the server can reply with a signon error code of 3000, which indicates that the client must perform multi-factor challenge authentication before proceeding with future OFX requests.

When this error is returned, the user should call this RequestChallengeQuestions method, which request the server to send a list of challenge questions that must be correctly answered before the OFX client may proceed with further OFX requests.

Upon successful response, the server will return a list of challenge questions, stored to ChallengeQuestions, where each question is specified by ChallengeQuestionId and ChallengeQuestion. If the server does not return such list, the class will throw an HTTP 400 error.

The user should inspect the ChallengeQuestions. When this list of challenge questions is returned, then the user has to answer each question by setting the ChallengeAnswer for each ChallengeQuestion, and then call the SendChallengeAnswers method to send the answers back to the server. The class will include these answers within the signon request included as part of the next request message. If these answers are correct, the server will process the request file. If they are incorrect, the server will return an error code of 3001.

When MFA is required, to prevent servers from needing to authenticate the user with each OFX request, the server may respond to a correct set of challenge answers with a OFXAccessKey on the signon response. However, the server determines the contents of this optional element. On each subsequent signon request, the client will send the last value of the OFXAccessKey it has received, even after the end of the current session. The server has the option to respond to any subsequent request with a 3000 error code, requiring the client to send the MFA challenge questions request. This allows the server to determine the lifetime of the OFXAccessKey.

Note: If in the profile response SignOnMFAChallengeFirst is True, the client must send this MFA challenge request in the first connection with the server, before sending any other requests.

The following properties are populated as a result of parsing a successful response:

• ChallengeQuestions

Note: The Multi-Factor Authentication (MFA) is applicable only in OFXVersions: 1.0.3, 2.0.3, 2.1.0, and 2.1.1.