App switching on mobiles

MitID supports the concept of app switching from a native mobile app to the MitID app. This means, when the end-user attempts to log into your native app, they are automatically sent to the MitID app for authentication. After they have completed the MitID authentication, they are automatically sent back to your native app. This feature saves the end-user from manually switching between your native app and the MitID app.

Supported WebViews

To perform a MitID authentication from a native app, you MUST display the MitID login flow in Chrome Custom Tabs (Android) or SFSafariViewController (iOS). Other types of WebViews are not supported in MitID (see supported WebViews).

The following sequence diagram illustrates the backend communication with the app switching feature:

MitID app switching

Description of the steps involved:

1. Check if the MitID app is installed on this mobile device (see detailed section further down).
2. Make a request to your backend server to create a request URL.
3. Create a URL to start the MitID authentication. How you create the URL depends on the authentication protocol you are using:
   • OpenID Connect: The URL will be a normal OIDC authentication request URL (see the OpenID Connect guide for MitID).
   • Authentication REST API: The URL returned as authenticationUrl when creating the session (see the Authentication REST API guide for MitID).
4. The app gets back the URL for starting the authentication.
5. Open the authentication URL in Chrome Custom Tabs (Android) or SFSafariViewController (iOS) (see detailed section further down).
6. The end-user inputs their user ID in MitID's web interface.
7. The MitID web interface displays a button to launch the MitID app.

MitID app switching

8. The end-user clicks the launch button and the MitID app launches.
9. The end-user authenticates with PIN or biometrics in the MitID app.
10. The MitID app automatically triggers a launch of your native app. This is done using an app switch URL which your app reacts to (see detailed section further down).
11. Depending on the platform of your app, you might need to have some handling in the app to bring the already existing Chrome Custom Tabs / SFSafariViewController to the foreground again. It's crucial that the end-user returns to the same view as before the switch to the MitID app occurred. This is because the MitID transaction needs to continue there.
12. The MitID web interface continues the authentication, possibly asking for the CPR number if you are using this feature.
13. Upon success, the end-user will be sent back to the result URL according to the authentication protocol you use:

• OpenID Connect: The user will be sent to the redirect_uri you used when starting the authentication.
• Authentication REST API: The user will be sent to the callback URL you specified when creating the session.

14. Your backend server must get the authentication result from the authentication protocol and verify the result.
15. Return the page where you want the end-user to end up after the authentication.

For more details on how to set this up, see the following sub-sections.

Configuration of app switching

Prerequisites

Before you set up the integration with your mobile app, please provide Signicat with the Universal Link to your iOS app, and/or the App Link to your Android app by creating a support ticket in the Signicat Dashboard. Signicat will help you add this link to your configuration

You must specify the app type,android or ios, in your authentication requests. How you do this, depends on the authentication protocol you use:

• OpenID Connect: Specify the app type in the acr_values (see Control the MitID flow).
• Authentication REST API: Specify the app type in additionalParameters (see Control the user flow).

MitID app detection

Given the requirement that app switching can only be used when the initiating app is your native app, the options for presenting the MitID login page to the end-user is an SFSafariViewController on iOS or a Chrome Custom Tab on Android.

Important

Regardless of which mobile platform is used, your native app must check that the MitID app is installed on the end-user’s device before presenting the MitID login page. If the MitID app is not installed, the app switching will not work.

The approach for detecting the presence of the MitID app will depend on the technology used in your native app. The following are examples on how to do this in iOS and Android.

Android

Code example for checking if the MitID app is installed:

public boolean deviceHasMitIDApp() { 
  try { 
    getPackageManager().getPackageInfo("dk.mitid.codeapp.android", 0); 
    return true; 
  } catch (PackageManager.NameNotFoundException e) { 
    return false; 
  } 
}

Starting with Android 11, the following must also be included in AndroidManifest.xml:

<manifest ...>
  <queries> 
    <package android:name="dk.mitid.app.android" /> 
  </queries> 
  <application ... /> 
</manifest>

iOS

Code example for checking if the production MitID app is installed:

func canOpenMitIDApp() -> Bool {
  guard let url = URL(string: "https://appswitch.mitid.nets.eu/.well-known/apple-app-site-association”) else {
    return false
  }
  return UIApplication.shared.canOpenUrl(url)
}

In addition, the string mitid-app must be added to the plist with a key of LSApplicationQueriesSchemes.

In the test environment where the MitID app test version is used, you need to use the following URL in the check: https://appswitch-test.mitid.nets.eu/.well-known/apple-app-site-association.

Start the authentication in a supported WebView

Android

Chrome Custom Tabs can be implemented by following Android’s implementation guide. Below is a code snippet for how to open a URL in a Chrome Custom Tab.

CustomTabsIntent.Builder builder = new CustomTabsIntent.Builder();
CustomTabsIntent customTabsIntent = builder.build();
customTabsIntent.launchUrl(MainActivity.this, Uri.parse("AUTH_URL"));

iOS

Opening the SFSafariViewController is as simple as instantiating it with a URL and presenting it:

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

Returning from MitID app to your native app

In order for the MitID app to return to your app, your app needs to support App Links for Android and Universal Links for iOS.

Android

Add an intent filter to your main activity in Manifest.xml. Example:

<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="link.to.your.domain.with.an.app.links.file" />
</intent-filter>

In addition, you need to host an assetlinks.json file on your domain matching the host in the manifest file.

Read more about Android App Links in the developer documentation for Android.

iOS

Your iOS app needs to be set up with a Universal Link. This is done by hosting an apple-app-site-association file on your domain and register a matching domain in the app. Read about Universal Links in the developer documentation for iOS.

See also

Learn more about the recommended approach to designing your native mobile apps:

Native mobile apps