Handling Multifactor Authentication
This guide explains how to handle multifactor authentication (MFA) when running an aggregation job.
MFA is controlled by the institution's security settings, not by MX. MFA can be encountered at any step in the aggregation process.
If you've been prompted for MFA, you've likely completed these steps:
- Called an aggregation endpoint such as aggregation, IAV, account owner identification, or extend transaction history.
- Checked the member's connection status:
GET /users/{user_guid}/members/{member_guid}/status.
MFA is indicated when you see a connection_status of CHALLENGED. The response also returns a challenges array that includes the question(s) the end user must answer to proceed.
Make a note of both the guid in the challenges array and the label (for example: What city were you born in?).
Here is an example:
_18{_18 "member": {_18 "aggregated_at": "2020-09-21T19:48:57Z",_18 "challenges": [_18 {_18 "field_name": null,_18 "guid": "CRD-8f841084-66cb-4e3d-9253-96f97093100a",_18 "label": "What city were you born in?",_18 "type": 0_18 }_18 ],_18 "connection_status": "CHALLENGED",_18 "guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",_18 "is_authenticated": false,_18 "is_being_aggregated": true,_18 "successfully_aggregated_at": "2020-09-21T19:44:17Z"_18 }_18}
Use the Resume Endpoint
The PUT /users/{user_guid}/members/{member_guid}/resume endpoint allows you to answer the challenges presented during MFA and continue the process. There are also other forms of MFA, such as choosing from multiple options (like choosing from a list of phone numbers to text a code to) or choosing the correct pre-determined photo. These are not covered in this guide, but they are possible scenarios with the MX API.
A relatively common scenario is requiring a one-time code texted to a phone number. In this case, use the resume endpoint twice: once to choose the phone number and again to provide the correct code. Also, use the connection status endpoint multiple times to get two different challenge GUIDs: one for the phone number and one for the code.
In this guide, we're using MX Bank test institution. To mimic a successful answer, use correct as the value.
In an actual MFA situation, the end user will need to provide the correct answer to the question. If the security question is What city were you born in?, the answer may be Chicago, Tallahassee, etc.
In the body of the request, include the challenge guid provided in the previous response and the correct answer for the label field.
Notice that connection_status changed to RESUMED while is_being_aggregated remains true. The is_authenticated field is still false—meaning the MFA answer was accepted and the connection is proceeding, but the member's login credentials haven't been fully authenticated yet. Continue to poll the member's status to confirm there are no additional challenges or errors.