App Switch - kmd-identity/documentation GitHub Wiki

KMD Identity supports NemLog-in App Switch functionality which allows for a better user experience when a user authenticates through the MitID App. This is supported for both public and private Service Providers.

The following example will showcase the difference in user experience depending on whether the Android/iOS app supports App Switch or not:

  1. User opens the Android/iOS app
  2. User clicks log-in with MitID
  3. Log-in flow starts through KMD Identity (in a browser on the mobile phone)
  4. User enters Bruger ID (User ID) and then approves the log-in in the MitID app
    1. Without App Switch: User manually navigates back to the Android/iOS app
    2. With App Switch: User is automatically navigated back to Android/iOS app
      1. In some cases a user must still confirm the navigation back to the Android/iOS app. We experience this behavior on some devices and even in official Danish apps like Digital Post but not consistently. It is currently unknown as to why and when this happens. If you have any insight then please let us know.
  5. The log-in flow finishes in the browser and returns to the Android/iOS app

The following requirements must be met by the Android/iOS app to ensure proper App Switch support (they are explained in details further below):

  1. It must support the mobile platform requirements of NemLog-in App Switch
  2. It must be configured on KMD Identity to allow users to authenticate through NemLog-in
  3. It must be configured on KMD Identity with return URLs for Android/iOS app
  4. It must supply a query string parameter during log-in to indicate the platform of the app

1. Support the mobile platform requirements of NemLog-in App Switch

The NemLog-in integration document section 9.6 states the following:

NemLog-in is designed to target support for mobile app-switch using either App Links on Android [AndAppLinks] or Universal Links on iOS [UniLinks]. To this end the service provider must provide NemLog-in with the platform and return URL, where the return URL is the URL of the service provider app. The return URL is used as the return address for app-switch back to the service provider app when authentication finishes in third party apps like MitID. If no return URL is provided by the service provider, then the end-user will have to manually go back to the original app when using MitID. For local IdPs the behaviour will depend on the implementation of the local IdP, but NemLog-in will communicate the platform and return URL through the SAML AuthnRequest send to the local IdP.

Note: You can ignore section 9.6.1. This is handled by KMD Identity and not the Android/iOS application.

The NemLog-in app-switch document has additional information for Android/iOS developers. It's currently only available in Danish.

The latest NemLog-in documents can be found @ https://tu.nemlog-in.dk/oprettelse.og.administration.af.tjenester/log.in/dokumentation.og.guides/

Read more about Android App Links @ https://developer.android.com/training/app-links

Read more about iOS Universal Links @ https://developer.apple.com/ios/universal-links

2. Configured on KMD Identity to allow users to authenticate through NemLog-in

Ensure the Android/iOS application has a working integration with KMD Identity where users can authenticate and log-out through NemLog-in. New applications must follow our Get started guide.

3. Configured on KMD Identity with return URLs for Android/iOS app

The return url of the Android/iOS app must be configured on KMD Identity. The return URL is forwarded to NemLog-in during authentication flow which then allows the MitID app to navigate the user back to the Android/iOS app.

Contact KMD Identity and supply the following:

  • ClientID of the mobile application when using OpenID or EntityID of the SAML Relying Party
    • Note: SAML Relying Party as a mobile application is not recommended due to the difficulties of handling log-in and log-out in a browser
  • Return url of the Android app (if applicable)
  • Return url of the iOS app (if applicable)

4. Supply a query string parameter during log-in to indicate the platform of the app

The Android/iOS app must provide a new query string parameter named "platform" to the authorize endpoint of KMD Identity during log-in.

The query string parameter is used by KMD Identity to identify which return url to forward to NemLog-in during log-in.

The value of the query string parameter can either be "android" or "ios".

Example: https://identity.kmd.dk/adfs/oauth2/authorize/?client_id=[clientid]&redirect_uri=[redirecturi]&response_type=code&scope=[scope]&platform=android&...

You can test the entire flow with an Android app developed by KMD Identity. The app can be installed directly from https://github.com/kmd-identity/testapplications/releases/tag/v1.0 where an apk file is available. The Android app is not available on Google Play Store.

Ensure you have the MitID app installed and configured on the same device as the Android app. Several Identity Providers are enabled for the Android app, however App Switch only works when "NemLog-in (private)" has been selected.

The source code for the Android app can be found @ https://github.com/kmd-identity/testapplications/tree/master/KMD.Identity.TestApplications.OpenID.MAUI

Feel free to contact KMD Identity if you have questions.

Please note: We are not Android or iOS developers. We can only provide very limited support for questions related to Android and iOS platforms.