App Switching

App Switching

During Strong Customer Authentication, the end-user (PaymentServiceUser, PSU) must authenticate himself/herself using a two-factor approval. The first factor is the user logging in by providing a user name and a password to the authorization endpoint. The second factor is the user’s approval using an Approval App / Code App (mobile application). App switching requires MitID. App switching is not available for NemID.

This section describes how to enable app-switch in a ThirdPartyProvider (TPP) mobile application. By app-switch is meant:

  • Automatically navigating the End-user to an Approval App / Code App from a TPP mobile application where End-user is attempting to login
  • Navigating back to the TPP mobile application, when the user has approved or cancelled the transaction in the Approval App / Code App

In the TPP mobile application, Strong Customer Authentication (SCA) is started by opening the OAuth request in a Custom Tab (Android) or SFSafariViewController (iOS) using this URI (see Security section for details):

var redirectUri = $"{auth_endpoint}?response_type=code&client_id={yourClientId}&scope={scope}&state={request_state}&code_challenge_method=S256&code_challenge={code_challenge}&redirect_uri={yourRedirectUri}&return_app_url={returnAppUrl}";

The yourRedirectUri should be an App Link (Android) or Universal Link (iOS), which enables sending an authorization code to the TPP App from the Custom Tab / SFSafariViewController, once the end-user has been authenticated and the authorization completes.

The return_app_url parameter should only be set if the Approval App is installed on the device. It enables returning to the TPP App from the Approval App.
The value should be an app link in the case of Android and a universal link in the case of iOS.
The app link/universal link must have the same origin as yourRedirectUri.
Once the Custom Tab / SFSafariViewController is opened, a link is available to perform app-switch when using MitID login.

Sandbox Approval App

When pressing the link for app-switch in the sandbox environment the following url will be opened:

sandboxstub://auth_id={authId}&return_uri={returnUri}&update_uri={updateUri}

where:

  • authId is an id of the current authentication.
  • updateUri is the url to request once the user has selected an option (Ok, Cancel, Error).
    The query params ?auth_id={authId}&status=<ok|cancel|error> must be added to updateUri before request is made.

  • returnUri is the url to return to once the update request has been made.

An Approval App for sandbox testing can register for this url scheme.

We have made an Android version of a Sandbox Approval App which can be used as reference. You can either download our APK-file or build your own APK-file based on our sourcecode.
Link to Bankdata public GitHub  https://github.com/Bankdata/open-banking-sandbox-codeapp

Test for Approval App presence on device

Below are some code snippets showing how to check for app presence on a device.

Android

fun deviceHasApprovalApp(): Boolean {
    return try {
        packageManager.getPackageInfo("dk.bankdata.codeapp.android", 0)
        true
    } catch (e: PackageManager.NameNotFoundException) {
        false
    }
}

On Android 11+ you may need to add a package query to AndroidManifest.xml

iOS

func canOpenApp() -> Bool {
    guard let url = URL(string: “some-approval-app://”) else {
        return false
    }
    Return UIApplication.shared.canOpenUrl(url)
}

The TPP App must add “some-approval-app” to the plist file using key LSApplicationQueriesSchemes.
After that, it can check for app presence, as shown in the code snippet.

Opening Custom Tab / SFSafariViewController from TPP App

Below are some code snippets showing how to open a URL in a Custom Tab / SFSafariViewController:

Android

val customTabsIntent = CustomTabsIntent.Builder().build()
customTabsIntent.launchUrl(MainActivity.this, Uri.parse(redirectUri))

iOS

guard let url = URL(string: redirectUri) else {
    return
}
let safariVC = SFSafariViewController(url: url)
self.navigationController?.pushViewController(safariVC, animated: true)

Enable returning from Approval App to TPP App

Android

An intent filter must be added in AndroidManifest.xml to the Activity that should start when the Approval App returns to the TPP App:

<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="https"
        android:host="hostname"
        android:path="path" />
</intent-filter>

where hostname is the hostname of the return_app_url parameter in the OAuth request. Remember also to verify your app link by publishing a Digital Asset Links JSON file - see developer.android.com.

iOS

The TPP App needs to implement support for Universal Links for the Approval App to be able to return to the TPP App

For information on how to do this - see developer.apple.com.