OAuth Authorisation Flow

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

Official 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 continue to 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). We encourage you to verify compatibility of your mobile app on both iOS and Android before enabling official connections in production.

Bank authorisation methods

The open banking standards define two methods for user authorisation. So far, different banks have chosen to implement different variations of these methods. The authorisation experience for your users will vary depending on which bank they use and whether they are using a desktop or mobile device.

The authorisation flows are broadly described as either redirect or decoupled. An explainer on these flows can be found here (note: the term “Third Party” 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 or banking customer number and using that to trigger an authorisation request with their bank. The user will then be able to open their mobile banking app and complete the authorisation there.

Considerations for decoupled flows

There are no changes anticipated for your application to support decoupled flows.

Considerations for redirect flows

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

If your application hosts the Akahu OAuth flow in an iframe, this will not be supported for official open banking connections due to security restrictions implemented by banks.

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. Android WebViews do not handle app redirects, so the user will not be navigated correctly to their banking app if triggered from within a webview.

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 does not officially support the use of WKWebView.

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.

Verifying compatibility

The best way to verify compatibility with the mobile app redirect flow is to test using a real mobile banking app.

While Akahu's Demo Bank supports a web redirect authorisation flow, we don't have a Demo Bank mobile app, so we can't provide a way to test the app redirect process end-to-end using Demo Bank.

Before you can verify compatibility, your app will need to be configured to enable official open banking connections. If you haven't already, get in touch and let us know that you'd like to start testing official open banking connections so we can get you set up (starting with your non-production environments).

We recommend repeating the following test on both iOS and Android:

Make sure that you have one of the following mobile banking apps installed and set up on your mobile device: Westpac One, ANZ goMoney, or ASB Mobile (BNZ does not currently support the mobile app redirect flow).
Launch your app and navigate to the Akahu OAuth authorisation flow.
When prompted, choose a relevant bank based on the mobile banking app(s) you have installed.
- If the bank app is launched your app is compatible (1/2) ✅
- If the bank app is not launched and you are presented with a bank login webpage (Westpac) or a fallback page suggesting that you need to install the bank's mobile app (ANZ and ASB), then your app is not compatible ❌ Please review the Considerations for redirect flows section above.
Complete consent authorisation using the banking app. You will be subsequently redirected back to the Akahu authorisation flow.
Confirm your connections in the Akahu authorisation flow (only required for enduring access). You will then be navigated back to your app using the redirect URI that your app supplied to Akahu:
- If you are navigated back to the correct place in your mobile app, your app is compatible (2/2) ✅
- If you are navigated to a web version of your application or your mobile app doesn't successfully handle the navigation and complete the OAuth token exchange with Akahu, your app is not compatible ❌ Please review the Considerations for redirect flows section above.