We are building an aggregation application working with Yodlee data and while most of the institutions we work with have security questions if they use MultiFactor Authentication, there is one institution (JP Morgan) that has a "MULTI_LEVEL" MFA approach. In attempting to test and handle this, we used the Java sample application "Aggregation12" (which is what we used as the implementation example for all other Yodlee SOAP interaction so far.
When trying to use the console app "yconsole.sh" talk to any MULTI_LEVEL MFA institution (JP Morgan Retirement options [cobrand ID 4999] is a real one, DagMultilevel [cobrand ID 15682] is a test one), the initial login step works fine but we're unable to get past the first token step in multi level auth without an error message. The XML from our access logs looks like this:
=======================================================
= Elapsed: 538 milliseconds
= In message: <?xml version="1.0" encoding="UTF-8"?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><soapenv:Body><putMFARequestForSite xmlns="http://refresh.refresh.core.soap.yodlee.com"><userContext xmlns=""><cobrandId>10008392</cobrandId><channelId>-1</channelId><locale><country>US</country><language>en</language><variant></variant></locale><tncVersion>2</tncVersion><applicationId>7A318B9CD555B6A3FF82D22CBF3C9F00</applicationId><cobrandConversationCredentials xsi:type="ns1:SessionCredentials" xmlns:ns1="http://login.ext.soap.yodlee.com"><sessionToken>10122012_0:87e50a0bac49909f03763e2819c5c3f7da170f0c0b6b8e74efc594875089b25efeb4142bbe5b42d73f5682d33c44c8a33718c15d53d5f4afda68c8d389e15f39</sessionToken></cobrandConversationCredentials><preferenceInfo><currencyCode>USD</currencyCode><timeZone>PST</timeZone><dateFormat>MM/dd/yyyy</dateFormat><currencyNotationType>SYMBOL_NOTATION</currencyNotationType><numberFormat><decimalSeparator>.</decimalSeparator><groupingSeparator>,</groupingSeparator><groupPattern>###,https://www.pivotaltracker.com/epic/show/0.##</groupPattern></numberFormat></preferenceInfo><fetchAllLocaleData>false</fetchAllLocaleData><conversationCredentials xsi:type="ns2:SessionCredentials" xmlns:ns2="http://login.ext.soap.yodlee.com"><sessionToken>10122012_0:794aeae009e6ae1d6b7f89be3a133b74c7618ec794917b9ca41b83e903d847ab7a318260120729e5851b1bdc956711d37549d29e941dd1e25fb628d70e5b70d5</sessionToken></conversationCredentials><valid>true</valid><isPasswordExpired>false</isPasswordExpired></userContext><userResponse xsi:type="ns3:MFATokenResponse" xmlns="" xmlns:ns3="http://mfarefresh.core.soap.yodlee.com"><token xsi:type="xsd:string">5731234567</token></userResponse><memSiteAccId xmlns="">14616812</memSiteAccId></putMFARequestForSite></soapenv:Body></soapenv:Envelope>
= Out message: <?xml version="1.0" encoding="utf-8"?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><soapenv:Body><soapenv:Fault><faultcode>soapenv:Server</faultcode><faultstring>InvalidSiteAccountExceptionFaultMessage</faultstring><detail><ns4:InvalidSiteAccountExceptionFault xmlns:ns4="http://core.soap.yodlee.com"><faultText>com.yodlee.core.InvalidSiteAccountException: Argument value not found: 14616812</faultText></ns4:InvalidSiteAccountExceptionFault></detail></soapenv:Fault></soapenv:Body></soapenv:Envelope>
=======================================================
The soap server we're running these tests against is: https://eval.yodlee.com/yodsoap/services
So, 2 real questions:
1) what's the origin of this error type (InvalidSiteAccountExceptionFault)? I can see from this page that it means "The member site account identifier does not exist, does not belong to this user, or is a custom item.", but that language is not clear to me (maybe "member site account identifier" is application vocabulary for yodlee that doesn't make sense to an external developer?)
2) Is there a good documentation resource that specifically covers the proper process for interacting with an institution with MULTI_LEVEL MFA?
1) what's the origin of this error type (InvalidSiteAccountExceptionFault)? I can see from this page that it means "The member site account identifier does not exist, does not belong to this user, or is a custom item.", but that language is not clear to me (maybe "member site account identifier" is application vocabulary for yodlee that doesn't make sense to an external developer?)
Answer -
Yodlee has data model designed as per different types of banking products like bank accounts, credit card accounts, loan accounts, investment accounts and so on. In Yodlee's terminology all these different products are called as containers. Every site has multiple containers enabled and are assigned a content service id(CSID) for each containers. The hierarchy followed by Yodlee is like
Site(site ID)
|---->container 1(savings/checking (CSID 1))
|---->container 2(Credit card (CSID 2))
Now there are two ways of linking an account with Yodlee.
1) Container based addition - In this you link an account specific to one container and hence data will be available for only that specific product.
2) Site based addition - In this you link an account to a site which has different containers associated to it and hence data associated to all the containers are available.
Ex. - We have Chase site which has savings/checking account, card account etc. Now if you do a container based addition and link Chase credit card using the content service id(CSID) , you will only see credit card details and your saving/checking account details will not be grabbed. If you do a site based addition , all the containers associated to that site will be linked based on availability on the end site. Hence if you have both saving/checking account and credit card account associated to your login then both will be pulled.
Whenever an account is linked an ItemId is created as an unique identifier for that account. If site based addition is done then there will be a siteAccountId created and then under the siteAccountId ItemIds will be created. For site based aggregation the primary key is siteAccountId for any API call and for container based addition the primary key is ItemId.
You are doing a container based addition and then trying to use the site aggregation API(putMFARequestForSite) and hence you are getting exception.
Hence for MFA flow while doing container based addition use -
getMFAResponse (https://developer.yodlee.com/Indy_FinApp/Aggregation_Services_Guide/REST_API_Reference/getMFAResponse) for getting the MFA questions and then use putMFARequest API(https://developer.yodlee.com/Indy_FinApp/Aggregation_Services_Guide/REST_API_Reference/putMFARequest) for posting the answers back to Yodlee.
2) Is there a good documentation resource that specifically covers the proper process for interacting with an institution with MULTI_LEVEL MFA?
Answer -
The basic flow of any MFA is
1)call getMFAResponse API to get the MFA question/token/image
2)Call putMFARequest API to post the answer back to Yodlee
3)Again go to #1 to check if more questions/token/image is available. continue with these 3 steps till error_code in getMFAResponse has a value.
If value is 0(zero) then the MFA flow was successful or else there was an error.
Modifying the answer to add a sample putMFAResponse request XML
<?xml version="1.0" encoding="UTF-8"?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><soapenv:Body> <putMFARequest xmlns="http://refresh.refresh.core.soap.yodlee.com"><userContext xmlns=""><cobrandId>xxxxxxxxxxxxx</cobrandId><channelId>-1</channelId><locale> <country>US</country><language>en</language><variant /></locale> <tncVersion>2</tncVersion><applicationId>xxxxxxxxxxxxxxxxxx</applicationId> <cobrandConversationCredentials xmlns:ns1="http://login.ext.soap.yodlee.com" xsi:type="ns1:SessionCredentials"> <sessionToken>10122012_0:xxxxxxxxxxxxxxxxxxxxxxxxxxxx</sessionToken> </cobrandConversationCredentials><preferenceInfo><currencyCode>USD</currencyCode><timeZone>PST</timeZone><dateFormat>MM/dd/yyyy</dateFormat> <currencyNotationType>SYMBOL_NOTATION</currencyNotationType><numberFormat> <decimalSeparator>.</decimalSeparator><groupingSeparator>,</groupingSeparator> <groupPattern>###,##0.##</groupPattern></numberFormat></preferenceInfo> <fetchAllLocaleData>false</fetchAllLocaleData><conversationCredentials xmlns:ns2="http://login.ext.soap.yodlee.com" xsi:type="ns2:SessionCredentials"<sessionToken>10122012_0:xxxxxxxxxxxxxxxxxxxxx</sessionToken></conversationCredentials><valid>true</valid><isPasswordExpired>false</isPasswordExpired></userContext><userResponse xmlns="" xmlns:ns3="http://mfarefresh.core.soap.yodlee.com" xsi:type="ns3:MFATokenResponse"><token xsi:type="xsd:string">123456</token></userResponse><itemId xmlns="">14672972</itemId></putMFARequest></soapenv:Body></soapenv:Envelope>
Also you can get the JAVA sampleApp from https://developer.yodlee.com/Indy_FinApp/Sample_Apps/JAVA_Sample You can use the itemManagement menu to link the container based accounts and use it to check the flow of add account.The basic flow of MFA above will handle the multilevel as well.