OAuth Migration Guide

ℹ️

This guide is relevant for customers of both our one-off or enduring account connectivity APIs.

Dedicated open banking APIs change the way that your users authorise access to their financial accounts.

This guide will help you to determine what (if any) changes are required to ensure that your users are able to complete authorisation with their bank and be returned to the right place in your application.

If you develop a mobile app that hosts the Akahu OAuth flow using an embedded browser, some changes are likely required (see Supporting redirect flows).

Authorisation flows

The API Center standards that the banks develop against define two methods for user authorisation. Different banks have chosen to implement different variations of these methods, so the authorisation experience for your users will vary depending on which bank they use.

The authorisation flows are broadly described as either redirect or decoupled. An API Center explainer on these flows can be found here (note: when they use the term “Third Party”, this refers to Akahu rather than you).

📘

You don’t have to understand how the different authorisation flows work in detail because Akahu handles this for you. However it will likely be helpful for you to know the differences between them to help you support your users.

The redirect authentication flow, which involves navigating the user from Akahu’s OAuth flow to their bank (and then back again), has two variants:

• Web redirect (authorisation occurs in the bank’s online banking portal).
• App redirect (authorisation occurs in the bank’s mobile app). This is only available when the user is using a mobile device with their bank’s mobile app installed.

The decoupled flow involves Akahu collecting the user’s mobile number and using that to trigger a request with their bank. The user will receive a push notification from their bank’s mobile app prompting them to complete the authorisation in-app. If the user started the process from the same mobile device that has their banking app installed (i.e. your app is a mobile app or a web app that the user is accessing from their mobile device) then they will need to manually navigate back to Akahu’s OAuth flow once authorisation has been completed with their bank.

Supporting decoupled flows

There are no changes anticipated for apps to support decoupled flows.

For mobile applications that use an embedded browser to host the Akahu OAuth flow, we recommend testing that your application works as expected when your app is sent to the background while the Akahu OAuth flow is open (i.e. the user has switched to their bank app to authorise). In particular, it is important to test that when the user returns to your app from the background, the embedded browser hosting the Akahu OAuth flow is still active, allowing the user to complete the Akahu OAuth process.

Supporting redirect flows

If your application is browser-based, then we don’t anticipate that any changes will be necessary to support banks that use redirect-based authorisation flows.

If your application has a native mobile app that implements the Akahu OAuth flow by opening an external browser (a pattern known as AppAuth), then we don’t anticipate that any changes will be necessary to support banks that use redirect-based authorisation flows.

If your application has a native mobile app that implements the Akahu OAuth flow in an embedded web browser (e.g. WebView), then some changes may be required to ensure that every redirect in the chain works as it should. Please continue reading for more information.

Recommended pattern for mobile apps

Using the AppAuth pattern will ensure that your users have a reliable, consistent authorisation experience.

This method involves your app opening Akahu’s OAuth flow using the user’s default mobile web browser. Once authorisation is complete, Akahu will navigate the user back to your app using a redirect URI (provided by you) that either uses a custom scheme such as app-name:// or an https:// URI that is registered to your mobile app using App Links (Android) / Universal Links (iOS).

Akahu OAuth in an embedded browser

If you prefer to embed the Akahu OAuth flow in your mobile app using an embedded browser rather than the recommended AppAuth pattern, there are some limitations on the types of embedded browsers that are supported.

Android

Android Custom Tabs must be used to host the Akahu OAuth flow in an embedded view.

An Android WebView cannot be used to host the Akahu OAuth flow if you wish to support banks that implement a redirect authorisation flow. Android WebViews do not handle app redirects, so the user will not be navigated correctly to their banking app.

iOS

It is recommended to use SFSafariViewController or ASWebAuthenticationSession to host the Akahu OAuth flow on iOS.

We are not presently aware of any technical limitations that preclude the use of WKWebView. However due to possibility of Javascript injection, WKWebView is not considered to be a secure environment and future support cannot be guaranteed.

Akahu OAuth as part of an embedded web application

If you use an embedded browser to host part of your web application inside your mobile app, and that embedded web application includes Akahu OAuth functionality, then it is likely that some changes will be required.

When your users authorise with a bank that uses an app redirect authorisation flow, they will be returned from their bank to Akahu OAuth in their device’s default mobile browser rather than your embedded browser. If the redirect URI that you supply to Akahu OAuth is a web redirect, then Akahu will not be able to navigate the user back to your mobile app on completion.

To resolve this, you will need to ensure that you provide Akahu OAuth with a redirect URI that redirects the user back to your app rather than your web application. Your mobile app will need to handle this event and navigate the embedded browser to the appropriate location in response.