What Is Data Access and What Can It Do For You?

Data Access is an open finance API platform designed to make it as easy as possible for you to share your institution’s financial data and access the data of other institutions using the latest FDX and OAuth standards.

In other words, you can stand up and manage your own financial data API in a fraction of the time it would take to build your own.

Data Access includes ready-made user interfaces for administration and authorization, as well as third-party management.

Data Access enables you to monitor and manage where customers are sharing your financial data and provides the tools to implement a more secure data-sharing experience with modern, token-based connectivity. It also empowers consumers to better understand, leverage, and benefit from their own financial data in a secure, reliable, and user-centric manner. Consumers gain visibility and control over which apps and institutions access their data by giving them the power to them to grant, modify, and revoke access at any time.

Data Access uses the Ruby on Rails and React frameworks.

Features

API

  • OAuth 2.0
  • OIDC
  • FDX 4.6-compliant endpoints for customers, accounts, and transactions.
    • Also includes capabilities endpoint for API information.
  • Dynamic data-recipient registration.
    • Quickly register and manage multiple apps at once with a streamlined endpoint rather than a UI.

User Interfaces

  • Data provider branding for all UIs.
  • Data provider administration dashboard.
    • Ability to manage intermediaries and apps.
    • Searchable logs.
    • Analytics reports.
    • Security.
  • Customer consent-granting widget.
  • Customer consent-management dashboard.
    • Embeddable in a data provider’s experience.
    • Ability to grant and revoke consent at any time.
  • Data recipient self-registration widget.
  • Data recipient administration dashboard.

Hosting

  • Hosted by MX.

Application Adapter

Data Access delivers FDX-compliant data to third parties. It does this by translating data from your backend systems into FDX data. Because all backend systems are a little bit different, this requires building an adapter specific to your systems to do the translation.

MX generally performs the work of building an adapter, but partners are welcome to do this themselves as well.

In order for MX to build this adapter, we need a few of things.

  1. Your existing backend API must be accessible from the outside and access must be given to MX so that Data Access can get your data and translate it with the adapter.
  2. Your existing backend API must be able to return the correct data for a given customer based on that customer’s OIDC token.
  3. You must provide documentation on your existing backend API.

Application Architecture

Data Access application architecture

Data Flow

Data Access data flow

How MX-hosted Implementations Work

In general, Data Access is hosted by MX using the Google Cloud Platform.

Settings and configurations specific to your needs can be made from within the Data Access administrator dashboard once MX has set up your environment. The sections that follow explain all the settings and configurations available to you, setup, and testing. We also cover how to embed the customer consent-management dashboard in your existing user interfaces.

Requirements

There are several requirements for an MX-hosted implementation of Data Access.

  1. You must have an OIDC provider (such as Okta) for both customer authentication and administrator authentication. You can use the same or separate providers for customers and administrators.
  2. Your existing backend API must be accessible from the outside. This is necessary for Data Access to get data from your systems.

Setup and Testing

MX will set up a generic development/testing environment for you using a temporary OIDC provider. This enables your admins and developers to log in and make changes to all settings (like host, branding, OIDC, etc) from within the administrator dashboard.

MX also provides a dummy data recipient called Centz for testing purposes. This will allow you to test workflows, sending and receiving data, etc.

Settings and Configuration

You can access these settings from within the Data Access data-provider administration widget, for example, at https://access.your-domain.com/admin/settings.

Setting Description Required?
Client auth method Currently only basic authorization is supported.

This must be configured separately for both admin and customer.		 Yes
Client ID The client ID issued by the authorization server.

This must be configured separately for both admin and customer.		 Yes
Client secret The client secret issued by the authorization server.

This must be configured separately for both admin and customer.		 Yes
Colors Your financial institution’s brand colors. These are used for link and button colors throughout Data Access UIs. Yes
Disable OAuth PKCE code challenge This may be useful for debugging. Defaults to false. No
Discovery URI OIDC configuration metadata endpoint.

This must be configured separately for both admin and customer.		 No
Honeybadger API key The API key provided by Honeybadger. Used to monitor system errors produced by the application. No
Institution name The human-readable name of your financial institution. Yes
Logo Your financial institution’s logo image. This image is shown in the end-user consent flow and the data recipient portal. Yes
OIDC debug This enables extra logging for debugging. Defaults to false. No
Provider authorize URI OAuth 2 authorization endpoint.

This must be configured separately for both admin and customer.		 Required when no discovery URI is set.
Provider token URI OAuth 2 token endpoint.

This must be configured separately for both admin and customer.		 Required when no discovery URI is set.
Provider user info URI OIDC user information endpoint.

This must be configured separately for both admin and customer.		 Required when no discovery URI is set.
Public URL The public-facing URL of your Data Access instance without a trailing slash. This setting is used in the redirect URIs that must be registered for both admin and customer authorization services.

Example: https://access.your-domain.com
Admin authorization redirect URI: https://access.your-domain.com/admins/oidc_callback
Customer authorization redirect URI: https://access.your-domain.com/customers/oidc_callback		 Yes
Scope Space-separated list of scope(s) needed for admin token generation.

This must be configured separately for both admin and customer.		 Yes
Shared secret This is a symmetric key used in AES256 encryption for the customer consent-management flow. It must be a random 32 bytes represented as a Base64 string. For example, Jx2qSDdJy6BJfkjH7PPZ6OPnjbjd/qNI2vgbCRT30Qw=.

The example given here is valid and can be used in development and testing environments, but cannot be used in production. Production shared secrets can either be provided securely by MX or generated on your your end.		 Yes

The Customer Consent-Management Dashboard

Data Access includes a customer authorization dashboard which enables customers to manage the apps and intermediaries they have chosen to give permission to. This dashboard is designed to be embedded within your customer-facing web or mobile experience and accessible at https://access.your-domain.com/embed/authorizations.

Access to this endpoint is authenticated with nested JSON Web Tokens (JWTs) which are both signed and then encrypted. This allows you to authenticate customers and display the dashboard without the need to set a cookie.

The process is as follows:

  1. Generate an encrypted admin JWT on your own systems using your shared secret and the customer’s unique identifier; this will be used to authenticate in step 2.
  2. Use the admin JWT from step one to request an encrypted, expiring, one-time use customer JWT from Data Access; this will be used to authenticate in step 3.
  3. Use the customer JWT as a query parameter to load the dashboard into an iframe.

Diagram for Embedding Dashboard

Flow diagram for embedding customer consent-management dashboard.

Creating an admin JWT

Before creating a customer JWT, you’ll first need to prove that you’re authorized to do so. This step explains how to create an admin JWT using JSON Web Encryption (JWE).

You’ll need to use an appropriate encryption library to generate an admin JWT using your shared secret (for example, Jx2qSDdJy6BJfkjH7PPZ6OPnjbjd/qNI2vgbCRT30Qw=) and the unique identifier for the customer. MX strongly recommends using a Javascript Object Signing and Encryption (JOSE) library to handle JWE creation. There are many libraries and implementations available for different languages. Javascript and Ruby examples are shown here. Data Access uses AES256-GCM.

The encrypted object should contain the sub claim, for example {"sub": "sub-id-1234"}. This is the same as the subject identifier outlined in the OIDC spec. It is the unique identifier for that user in your system.

Example JWE Implementations
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

require "jose"

class JWE
 def self.encrypt(obj)
   ::JOSE::JWE.block_encrypt(key, obj.to_json, "alg" => "dir", "enc" => "A256GCM").compact
 end

 def self.decrypt(encrypted)
   ::JSON.parse(::JOSE::JWE.block_decrypt(key, encrypted).first)
 end

 def self.key
::JOSE::JWK.from_oct(Base64.decode64(SHARED_SECRET))
 end
 
end

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

const crypto = require('crypto');
const { CompactEncrypt } = require('jose/jwe/compact/encrypt');
const { compactDecrypt } = require('jose/jwe/compact/decrypt');
class SecureMessageService {
  constructor(key) {
    this.encoder = new TextEncoder();
    this.decoder = new TextDecoder();
    this.key = crypto.createSecretKey(Buffer.from(key, 'base64'));
}
  async encrypt(obj) {
    return await new CompactEncrypt(this.encoder.encode(JSON.stringify(obj)))
      .setProtectedHeader({ alg: 'dir', enc: 'A256GCM' })
      .encrypt(this.key);
  }
  async decrypt(encrypted) {
    const { plaintext } = await compactDecrypt(encrypted, this.key);
    return this.decoder.decode(plaintext);
} }
module.exports = SecureMessageService;

Creating a customer JWT

Use this endpoint to create a JWT for the specified customer based on their unique subject identifier included in the previous section.

If a customer with the given sub has not yet been created in Data Access, using this endpoint will create it.

Endpoint:

POST /admin/customers/jwt

1
2
3

curl -X POST https://access.your-domain.com/admin/customers/jwt \
-H 'Content-Type: application/json' \
-H 'token: {admin_jwt}'

1

{end user jwt}

Embedding the Dashboard Via iframe

Data Access has a specific route to be used when embedding the customer consent-management widget in an iframe. Passing in the jwt query parameter into the iframe route and setting the value to the customer JWT will authorize the view for the specified customer without needing to re-authenticate.

Endpoint:

GET /embed/authorizations?jwt=${customer_jwt}