Polaris Bank is an example application showcasing 'The next generation internet banking solution'. This example application shows customers how React Native and React can be combined to create highly cross-compatible applications over multiple channels.
A Polaris Bank demo is available at polarisbank.nearform.com.
This document is intended for developers who wish to experience Polaris Bank and describes how to install and run Polaris locally. It also includes a Polaris user journey, which in addition to the demo above, shows how users can experience Polaris Bank open banking. It consists of the following sections:
Polaris is easy to install, run and use. Before starting, let's ensure you have all the prerequisites installed.
Fork Polaris on GitHub. It is easier to maintain your own fork as we have designed Polaris to diverge.
After you have your fork, clone a copy of it locally using the command:
git clone https://github.com/<your-fork>/open-banking-reference-app.git
Change directory to the root folder of the project. Run the following command to install the dependencies for the frontend application:
npm install
To install server dependencies, run the command:
cd server && npm install
Polaris uses .env
files to configure Polaris packages. There are .sample.env
files for each Polaris package documenting sample values that you can use in each .env
file.
To generate a default set of .env files for all packages, run the following command in the root directory of the project:
npm run create:env
Polaris implements the Open Banking standard.
To enable Polaris to fetch bank account details from your bank, you need to register with a bank and identity platform that supports open banking.
The easiest way to set this up for demonstration purposes is to contact us for some IBM credentials. Edit the server.env
file to enter these credentials for the following variables:
Polaris includes a chatbot called IBM Watson Assistant to show how a conversation with your bank might look. This step is optional - if you skip this step, the assistant does not respond, but Polaris still works.
Configure Polaris with the IBM Watson Assistant as follows:
/server/.env
file to enter the displayed API key and URL value for the variables WATSON_ASSISTANT_URL and WATSON_API_KEY./server/.env
to enter the displayed Assistant ID value for the variable WATSON_ASSISTANT_ID.Polaris is now configured with the IBM Watson Assistant. However, the assistant's only response is 'I didn't understand. You can try rephrasing'. To build responses, edit the Skill section on the assistant overview page.
You are now all set to run Polaris. To start the server, run:
cd server && npm run build && npm start
To start the web version, open another terminal and from the project root directory run the command:
npm run start:web
This automatically opens an Expo console in your browser that displays the phase of the Polaris build process. When Expo finishes building Polaris, it automatically opens another tab running Polaris.
Congratulations! You are now running Polaris locally.
To run Polaris on native devices, install the Expo app (Expo Client on the App Store or Expo on the Play Store). Use the app to scan the QR code displayed in the left panel of the Expo console.
The home page uses mock data for demonstration purposes. Connection to a real open bank account is demonstrated in this video.
To enable Polaris to run locally while connecting to a real open banking app use the following steps.
Before running the application, configure your environment variables as described below.
.env
file set REACT_APP_UI_BASE
to http://polarisbank.com:3000
. This is an alias to your local machine that is used in the backend configuration as a callback URL. Use the default values provided in the sample file for all other variables.127.0.0.1 polarisbank.com
.Once you have both applications running, allow the service worker to run on an unsecured domain (the polarisbank.com alias) as follows:
In Chrome open the page chrome://flags/#unsafely-treat-insecure-origin-as-secure, add an entry for http://polarisbank.com:3000
, toggle the flag from disabled to enabled and restart Chrome, as shown below.
If you are using Firefox, open Settings. Set both dom.webnotifications.allowinsecure
and dom.serviceWorkers.testing.enabled
to true
. This way you'll be allowed to see notifications on a HTTP domain.
Open the application in Chrome http://polarisbank.com:3000. A message to enable notification is displayed. Click Allow to enable a web push notification flow further in the user journey. Don't forget to allow notifications when your browser asks for consent!
This process is difficult and error prone. It consists of the steps below. Please follow each step carefully.
Browse to ForgeRock Directory and create an account. Caution: Don't forget your username, as authentication doesn't work with your email.
On the dashboard, click Create a new software statement.
Select the Transport/Signing/Encryption keys tab and scroll to Keys section.
Click the download (cloud) button of your Transport key:
server/crt.crt
file.server/key.key
file.Log out. If you forget to log out, you'll have trouble completing the next step.
Browse to ForgeRock Bank and create an account. Caution: Don't forget your username, as authentication doesn't work with your email. We recommend using a different username from the Directory account above, to avoid confusion.
Log out.
Download Postman. Don't use the web extension; install the desktop app on your laptop.
Open the Postman app and import their collection and environment as follows:
Configure a certificate in Postman:
*.ob.forgerock.financial
in the Host field.server/crt.crt
as the CRT file.server/key.key
as the KEY file.Using the Collections tab on the left pane, open the ForgeRock ORBI Sample (Generated)
folder.
Set up your Postman variables by running queries from the following subfolders:
Setup your environment/Test MATLS
: run all queries in order. They should all succeed.Setup your environment/Discovery
: run all queries in order. They should all succeed and set the global variables.Onboard your TPP:
Dynamic Registration/Onboarding your TPP/Generate registration JWT - FR Tool API
query. Carefully set up your redirect_uris.Dynamic Registration/Onboarding your TPP
folder in order. They should all succeed.Your TPP is ready to use!
Tap Current Account.
Tap Add Open Banking Account.
Select ForgeRock Bank.
When redirected to https://bank.ob.forgerock.financial/login
, log in with the same username and password you used on ForgeRock Bank.
Caution: The imported account is hardcoded as a Santander account with no transactions.
The ForgeRock certificate and private key shipped for development were created with the directory account damien
/Password
.
The corresponding bank account is damien-customer
/Password
.
Refer to the ForgeRock Documentation for more details.
This section describes a user journey where a user invites someone to connect their account. It consists of both the inviter journey and invitee journey.
Tap Current Account on the Polaris Bank app overview page.
Tap Add Open Banking Account.
Tap Invite Open Banking Account.
Enter a name and invitation message in the fields provided. For simplicity, we share with a QR code which generates a URL that the invitee can use. When you've entered the required details, tap Share with QR code to generate a code.
This section describes the invitee journey to connect the accounts after they receive a connect invitation.
In the Chrome dev tools console paste the following code to access the connection ID, JSON.parse(localStorage.getItem("@PolarisBank:state")).connection.connections.pop().id
.
You could also scan the QR code and browse to the encoded URL.
Open a new tab and navigate to http://polarisbank.com:3000/connect/<id>
where <id>
is the ID from the previous step. This displays the invitation page to allow invitees to connect their open banking account.
Tap Add Open Banking Account.
Tap Cumberland Building Society Sandbox.
Confirm the connection by ticking the checkboxes and tapping the Connect with Cumberland Building Society Sandbox.
The Cumberland Open Banking Sandbox website is displayed. Log in using one of their test accounts. You can find details at: https://www.cumberland.co.uk/developers/neon/download/file/PDFs/sandbox-instructions.pdf.
When logged in, select an account to connect and tap Continue.
Once this process is complete you are redirected back to the Polaris application, indicating the invitee account was successfully connected.
In the Current Account section of the Polaris app, you now see the connected open banking app below the mock current account, with active Transfer and Actions buttons.