Considerations
These are the issues that most commonly arise during the integration with the SSO. Because of how frequently they arise we have made a special section to bring developer's attention to them.
Ping URL
Activity inside the MoneyDesktop widget iframe may not be visible to the outside environment. This can cause the online banking session to time out even though the user is actively using MoneyDesktop.
To prevent this from happening, MoneyDesktop has a mechanism to send a ping (an https GET request) to a fixed URL to tell of activity within MoneyDesktop to keep the online banking session alive. Usually the URL is pointed to a 1x1 px transparent GIF image on our partner's website. The session cookie that comes with the GET request can be used to identify the session and mark it for activity. A session ID can also be provided by the partner to customize the ping URL for each session.
A timestamp is always added to the URL as a "_" parameter to guarantee uniqueness to prevent the GET from being cached.
The specified URL must be https so that we avoid the possibility of users getting a warning about loading insecure content onto a secure page. The timestamp parameter is added to the end of the URL that is specified. The format of the ping GET request will be similar to this: https://partnerWebsite.com/MD/server_ping?_=1335829071922.
A different base ping URL can be set for each Client if needed.
Ping based on session ID
'If a ping needs to be customized per session a session ID can be embedded into a data-options attribute in the div element that opens the HTML5 view. If a value is present for "ping_id" in the data-options attribute it will be reflected back in the ping URL as the ping_id parameter. The ping_id value can be set as either a string or an integer.
data-options is a JSON-formatted string. Some browsers are picky about the quotes so they need to be specified as in the example below. The JSON elements are each double-quoted and the attribute is surrounded with single quotes.
To the right is an example of using a session ID of "12345abc" in the data-options attribute of the div element using widget loader v2.
Keep session alive with a Javascript postMessage
MoneyDesktop 4.0 can publish a postMessage that will send a message to the main window from the iframe to keep the main session alive while a user interacts with MoneyDesktop. In your HTML page where your widget resides you need to implement an eventListener that will receive these messages. You insert a data-options="post_message_origin" attribute with "post_message_origin" being your endpoint for your page. Your eventListener that is listening for a message will pick up the postMessage. Your div will look something like the example to the right.
When you load the widget through the widget loader, MoneyDesktop will post a message to the post_message_origin URL with the four attributes in the example body to the right (timestamp will be current timestamp).
Widget loader required for data options parameters
The MoneyDesktop widget loader must be used if any data-options elements such as ping_id or post_message_origin are needed. The widget loader will create the proper URL with the data-options elements added. An implementation where the partner opens their own iframe and sets the iframe src directly to the URL obtained from the SSO User response cannot use data-options without altering the URL and this is not recommended.
Logout endpoint for widget sessions
You may want to explicitly log a user out from their MoneyDesktop session when they log out of their online banking session. An example of how this might be triggered would be to use Javascript with an "on-click" event on the Logout button or link.
The logout is accomplished by doing a GET request to the logout endpoint. The URL for this endpoint must match the environment that is being used (production or integration) as shown below:
- Production:
GET https://firefly.moneydesktop.com/logout - Integration:
GET https://int-firefly.moneydesktop.com/logout
Timeout of tokens and URLs
The user_token that the SSO API returns in the user read has a timeout length of 10 minutes. It is also a one use token. Some of our partners have integrated so that when a user logs into online banking it initiates the read at this point. This is an acceptable work flow, but it must also be ensured that when the user clicks on the link to enter MoneyDesktop's software that another read occurs to get a new user_token. The user_token (to ensure reliability and expiration issues) must be acquired directly before the launching MoneyDesktop. If the page is refreshed or the back button is pushed on the browser a new token must be obtained or there will be an authentication error with the token and an error page will be loaded.
Tracking users
If a Partner chooses to track which users have been created in the MX platform the Partner should still follow the full Basic SSO API workflow as outlined in the Guide. This workflow ensures that duplicate Users and Members are not created and automatically repairs issues that may arise if an error occurs during a User or Member create.
Terms and conditions
MoneyDesktop will display Terms & Conditions that are MoneyDesktop specific when a new user first logs into our software. The preferred way to handle this is that our Partner provides in their own Terms & Conditions the terms of using the MoneyDesktop software. If a partner has Terms & Conditions for the MoneyDesktop experience incorporated into their online banking experience MoneyDesktop will not show the Terms & Conditions to any users that log in.