OAuth in the Connect Widget - MX Documentation

This guide helps you build a flow to connect users to their financial institutions using OAuth, an industry-standard authorization protocol that lets users connect their accounts without sharing credentials with your application. The OAuth implementation depends on how you embed the widget:

Website using an iFrame: See Browser
Mobile app using a WebView: See Mobile (WebView)
Mobile app using an iFrame inside a WebView: See Mobile (iFrame in a WebView)

NOT USING OUR CONNECT WIDGET?Instead, see OAuth in Browsers or OAuth in Mobile Apps.

Prerequisites

You must register for OAuth with the financial institution unless you’re using one of our test institutions. See Registration for more information.

Browser Workflow

For browser integrations, the widget handles most of the OAuth flow automatically. You only need to capture one widget event to know when to close it.

Widget loads and user selects an OAuth-supported institution.
User selects Go to log in.
Widget opens the financial institution’s OAuth window in the default browser.
User authenticates and selects data to share.
After authorization, users may see a brief redirect screen.
A connection status screen shows a loading indicator.
Once connected, and the user selects Done, Member Connected, Primary Action Selected widget event is sent.
You close the widget, unless you want the user to stay and connect more accounts.

To prevent issues, confirm that in your widget URL request:

is_mobile_webview is set to false or omitted
oauth_referral_source is set to "BROWSER" or omitted

Mobile (WebView) Workflow

When you embed the widget in a mobile app’s WebView, your app must handle redirects to the OAuth provider and back.

Do not open the OAuth window in a WebView. Some financial institutions have security restrictions for certain web containers or browsers. See OAuth WebView Limitations for more information.

You send a widget URL request and set is_mobile_webview to true (sends widget events to window.location instead of window.postMessage).
Widget loads and user selects an OAuth-supported institution.
User selects Go to log in.
Widget triggers the OAuth Requested widget event.
Your app opens the OAuth URL from that widget event in an ASWebAuthenticationSession (iOS) or Auth Tab (Android).
User authenticates and selects data to share.
User is redirected back to your app through a custom URL:
- The user is redirected to the URL in the client_redirect_url request parameter that your app can respond to when linked from a browser.
- oauth_referral_source must be set to "APP".
- Once OAuth is complete, MX sends the user to the client_redirect_url with additional query parameters that describe what happened.

Example WebView Message

mx://connect/oauthRequested?metadata={...JSON encoded payload ...}

Example Redirect URL

https://widgets.moneydesktop.com/oauth/predirect_to/MBR-f1e7a927-924f-4b31-a8da-61de02954d74/4wa...snip...02?referral_source=BROWSER&skip_aggregation=false&

Example - Redirect User to Custom URL

Set the client_redirect_url parameter to specify where users are redirected after OAuth. MX appends query string parameters to the supplied client_redirect_url to describe what happened during OAuth: https://example.com?status={success|error}&member_guid={member_guid}&error_reason={error_reason} For example, if you set client_redirect_url: "https://example.com", the user is sent to https://example.com?status=success&member_guid={MBR-XXX}. If you set client_redirect_url: "https://example.com?state=mystate", the user is sent to https://example.com?state=mystate&status=success&member_guid={MBR-XXX}.

Query string parameters

Name	Values	Type	Description
`status`	`success`: Continue showing the Connect Widget / `error`: Close the widget and show a generic error view	String	Indicates whether OAuth was successful
`member_guid`	`MBR-XXX`	String	Unique identifier for the created/updated member.
`error_reason`	`CANCELLED`: User cancelled the process / `DENIED`: User couldn’t authenticate with the provider / `IMPEDED`: User action required at provider website / `PROVIDER_ERROR`: Unknown provider error / `SERVER_ERROR`: Unknown error / `SESSION_ERROR`: Reauthentication failed using the existing session	String	Reason for OAuth error

Request

curl -i -X POST 'https://int-api.mx.com/users/{USR-guid}/widget_urls' \
-d '{
      "widget_url": {
        "widget_type": "connect_widget",
        "is_mobile_webview": true,
        "client_redirect_url": "{your_url_here}",
        "oauth_referral_source": "APP"
      }
    }'

Mobile (iFrame in a WebView) Workflow

If you embed the widget in an iFrame inside a mobile app’s WebView, follow Mobile (WebView), then consider the following:

After OAuth, do you need to redirect the user back to a native app? If so, you must set oauth_referral_source to APP, so after OAuth the widget redirects the user to the client_redirect_url or the ui_message_webview_url_scheme.
Do you want widget events to send to window.opener, a custom URL, or custom app scheme? To allow the Connect Widget to send widget events via postMessages:
1. Set is_mobile_webview to false.
2. Set oauth_referral_source to APP. This tells MX to redirect the user at the end of OAuth to the client_redirect_url you set, instead of using postMessages in a browser.
3. Listen for the OAuth Requested widget event in your web app, then message the URL to your mobile app, so it can redirect the user in an ASWebAuthenticationSession (iOS) or Auth Tab (Android). After OAuth, MX redirects the user back to your client_redirect_url.

If you set is_mobile_webview to true, the widget:

Sends widget events to the WebView via window.location = {scheme}://{event path}?metadata={json encoded metadata} instead of window.postMessage(eventObject).
Sets oauth_referral_source to APP, so the OAuth flow redirects back to a native app instead of sending a postMessage to the opening window.
Doesn’t automatically open an OAuth window. Instead, it sends the OAuth Requested widget event so your app can correctly open the OAuth window in the user agent.

curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/widget_urls' \
-d '{
      "widget_url": {
        "widget_type": "connect_widget",
        "ui_message_version": 4,
        "client_redirect_url": "{your_url_here}",
        "oauth_referral_source": "APP"
      }
    }'

{
  "widget_url": {
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxc...snip...Ay5",
    "user_id": "u-abc-789"
  }
}

​Prerequisites

​Browser Workflow

​Mobile (WebView) Workflow

​Example - Redirect User to Custom URL

​Mobile (iFrame in a WebView) Workflow

Prerequisites

Browser Workflow

Mobile (WebView) Workflow

Example - Redirect User to Custom URL

Mobile (iFrame in a WebView) Workflow