App Switching

App switching is only supported for the MitID code app.
During Strong Customer Authentication, the end-user (PaymentServiceUser, PSU) must authenticate using a two-factor approval.
The first factor is the user logging in by providing a user name to the authorization endpoint.
The second factor is the user’s approval using an Approval App / Code App (mobile application).

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}&return_app_type={ios or android}";

The yourRedirectUri must 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.

IF your app is a native app (not a web browser application)
AND the MitID approval app is installed on the same device
THEN you must provide app switch parameters with the MitID login and signing.

If these criterias are not met, you must not provide app switch parameters with login and signing.

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.

Test for Approval App presence on device

Below are some code snippets showing how to check if the MitID code app is installed.

Android

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

On Android 11+ you must also add a package query to AndroidManifest.xml with the dk.mitid.app.android package name.

iOS

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

The TPP App must add “mitid-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.

Sandbox Approval App

We have developed an Approval App for Android, which can be used for testing of App Switching in the sandbox environment.
You can either download our APK-file or build your own APK-file based on our sourcecode.
The app is launched when an url with the custom scheme sandboxstub:// is opened.
This URL is opened, when pressing the link for app-switch in the sandbox environment:

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.

Bankdata example