Multi-Factor Authentication (MFA) in the Facade

Note: This page is about MFA support within the Financial Data API Facade. For MFA support in the Finicity API, see Multi-Factor Authentication (MFA).

The term Multi-Factor Authentication (MFA) describes various styles of authentication challenges provided by financial institutions, such as text questions, image matching, “captcha” images, etc.

When an account being aggregated encounters an MFA challenge, the account's aggrStatusCode is set to code 185. To resolve the this code, the app must call updateInstitutionLogin and follow the steps for Scenario #2: Accounts with 185 status.

MFA Frequency

Many institutions present MFA challenges when an account is accessed from a new machine or browser. When the MFA challenge is answered correctly, the institution will send a cookie or provide some other mechanism to avoid MFA for subsequent connections from the same environment. The cookie is usually valid for some period of time (such as 30 days or 90 days, depending on the institution's policy).

The Finicity platform is typically treated as a new machine, so the institution will require MFA on the first connection from Finicity, during account discovery. When the MFA challenge is answered correctly, the Finicity platform will store any cookie that is provided by the institution, in order to bypass MFA for subsequent calls to refresh that account.

This means that after an account has been activated, most calls through the Facade will not require additional MFA challenges. However, an account can go to status 185 at anytime, because it will happen again whenever the account's stored MFA bypass expires.

Handling Encoded Images

MFA style Image will return the image data in a standard Base64-encoded format. This format is handled natively by HTML, Javascript, CSS, and other formats.

To display the image in an HTML document, just paste the prefix data:image/png;base64,data:image/png;base64,  (including the final comma) followed by the contents of the image element directly into the src attribute of an HTML <img> tag. For example, if the MFA challenge includes this element:

  <image>R0l...AOw==</image>

...the image can be displayed in an HTML document like this:

  <html><body><img src="data:image/png;base64,R0l...AOw=="/></body></html>

For an explanation of Base64 encoding, see this page on the FreeFormatter website. The page gives examples showing how to display Base64 images in Javascript, CSS, and other formats, and includes a utility for experimenting with this encoding style. To view a decoded image using the FreeFormatter utility, do the following:

  1. Paste into the "Option 1" field all of the data from the <image> tag. (In the example above, you would paste the text R0l...AOw== into the field.)
  2. Click the Decode button.
  3. Answer Yes to the question about whether you are decoding a binary file.

Your browser will store the output as a file on disk, which can be viewed with any image viewer.

Challenges Segment

XML Name Description
Challenges Root element
challenge

Wrapper for all <test><choice>, and <image> elements.

Note that the Challenges element may include multiple individual challenge elements. The client app must handle the case where multiple challenges are returned in a single Challenges response.

MFA Styles

You can experiment with the various styles of MFA using testing accounts. There are testing account credentials for each MFA style.

Text based MFA

Testing account credentials: tfa_text :: go

JSON Implementation

{
"challenge": [
{
"textOrImageAndChoice": [
"Enter your first pet's name:"
]
}
]
}

XML Implementation

<Challenges xmlns="http://schema.intuit.com/platform/fdatafeed/challenge/v1">
<challenge>
<text>Enter your first pet's name:</text>
</challenge>
</Challenges>

Multiple choice MFA

Testing account credentials: tfa_choice :: go

JSON Implementation

{
"challenge": [
{
"textOrImageAndChoice": [
"Which high school did you attend?",
{
"val": "Washington",
"text": "Washington"
},
{
"val": "Jefferson",
"text": "Jefferson"
}
]
}
]
}

XML Implementation

<Challenges xmlns="http://schema.intuit.com/platform/fdatafeed/challenge/v1">
<challenge>
<text>Which high school did you attend?</text>
<choice>
<text>Washington</text>
<val>Washington</val>
</choice>
<choice>
<text>Jefferson</text>
<val>Jefferson</val>
</choice>
</challenge>
</Challenges>

Image MFA

Testing account credentials: tfa_image :: go

JSON Implementation

{
"challenge": [
{
"textOrImageAndChoice": [
"Enter the word in the image below",
"/9j/4AAQSkZVL...GdPCKEuaTuf/Z"
]
}
]
}

XML Implementation

<Challenges xmlns="http://schema.intuit.com/platform/fdatafeed/challenge/v1">
<challenge>
<text>Enter the word in the image below</text>
<image>/9j/4AAQSkZVL...GdPCKEuaTuf/Z</image>
</challenge>
</Challenges>

Answering the Challenge

The HTTP response containing the MFA challenges will include two HTTP headers: challengeSessionId and challengeNodeId. These headers and their values must be copied as headers on the HTTP request that is constructed to answer the challenge. This sequence allows the platform to continue the aggregation process that was interrupted by the MFA challenge.

The challenge session identifier expires after 120 seconds, and is only valid for one reply to an MFA challenge. There is never a reason to store the challenge session identifier for use in later requests.

If one of the answers sent for an MFA challenge is rejected, your application must start again at the beginning of the sequence to obtain a new session identifier. 

An MFA challenge may be returned from discoverAndAddAccounts or from updateInstitutionLogin (scenario 2). To answer the MFA challenge(s), call the same service again, following these steps to build the request:

  • Copy the headers challengeSessionId and challengeNodeId from the Challenges response as headers on the new request.
  • Add the following body to the request, substituting the correct answer for MFA_ANSWER:

JSON Implementation

{
"challengeResponses" : {
"response" : [
"MFA_ANSWER"
]
}
}

XML Implementation

<InstitutionLogin xmlns="http://schema.intuit.com/platform/fdatafeed/institutionlogin/v1">
<challengeResponses>
<response xmlns="http://schema.intuit.com/platform/fdatafeed/challenge/v1">MFA_ANSWER</response>
</challengeResponses>
</InstitutionLogin>

If the Challenges element contains multiple challenges, this request must contain one response for each challenge, in the same order the challenges were given.

Have more questions? Submit a request

Comments

Powered by Zendesk