Skip to main content
Version: 2.4.x.x

Out-of-Band Operations Using Push, QR Code, or Links

Introduction

The Nevis Access App offers different ways to receive information about an operation that the app did not initiate itself (this is referred to as out-of-band in technical terms). It depends on the scenario, the end user preferences, as well as technical limitations, such as which method of delivering the payload to the mobile device and Access App is offered or used. For example, one of the delivery methods is sending push notifications. However, there are scenarios where push notifications either

  • are not desired by the end user,
  • might not work (outage in the provider network, coverage problems), or
  • are not convenient for the specific use case.

In these situations, we offer alternative methods to be able to proceed with the operation.

Out-of-Band - Terminology and Additional Information

The term out-of-band refers to channels that are not part of the traditional request flow. A traditional request flow consists of a client initiating a conversation with a server, whereupon the server responds, and completes the flow.

For more information regarding the terminology and concept from the backend perspective in the Mobile Authentication Concept and Integration Guide, see the following:

You can find descriptions of client-focused use cases in the Nevis Mobile Authentication Client SDK, specifically in the use case chapters:

  • Registration
  • Authentication

Push Messages

In the context of out-of-band operations (registration, authentication, and transaction confirmation), push notifications are the most convenient way of delivering information by the backend system to the mobile client application. For this, the backend uses a messaging service to send push messages to the client mobile device.

Prerequisites

  • The end user accepted to receive push notifications.
  • The end user registered his Access App on the Nevis Mobile Authentication backend.
  • On Android devices, the Google Play Services app has to be installed. The Google Play Services app is preinstalled on Android devices but may be missing on some models, for example, Huawei devices. For such devices push is not supported.
info

As opposed to the two dispatching alternatives QR Code and Mobile Only, push notifications cannot be used for the registration operation. This is because the push identifier is not known to the backend before the registration is completed.

How it Works

Out-of-Band Operations with Push Messages

The example use case in the above figure shows how push notifications work during an authentication operation. Other operations behave very similar, apart from who or what initiates the operation. The numbers in the figure correspond with the numbers of the description below.

  1. The end user starts a login.
  2. The Nevis Mobile Authentication Backend initiates an authentication, and sends a push message payload to a push provider.
  3. The push provider sends an encrypted push notification to the mobile device. The mobile application has to deal with the notification.
  4. The mobile application triggers the out-of-band authentication process with the SDK by providing the encrypted push notification.
  5. Once the mobile application has completed the out-of-band authentication process, the user is granted access to the protected endpoint, for example, a web application in a desktop browser.

QR Code

A QR code is a convenient alternative to push messages if the end user has access to two different devices during operations. This is a prerequisite for using QR codes, because the code needs to be scanned by the mobile application. Besides displaying QR codes on your screen, you can also print them.

Prerequisites

The end user has access to a web application that displays the QR code generated by the Nevis backend or by a third-party system.

How it Works

Out-of-Band Operations with QR Codes

The example use case in the above figure shows how QR codes work. The numbers in the figure correspond with the numbers of the description below.

  1. The end user opens the web page on a desktop browser and initiates an out-of-band operation. As the end user does not have push notifications available (for any of the above mentioned reasons), the web application offers an alternative possibility in the form of a QR code.
  2. The end user opens the app and scans the displayed QR code.
  3. The desired operation starts.

This section focuses on dispatching out-of-band messages when there is only one mobile device (and no desktop) available. This method is referred to as the "mobile-only solution". It makes use of links.

Besides describing the mobile-only solution, the section also shows the limitations of the method.

Terminology

Both the iOS and the Android platform use their own terminology to describe the concept of links. Thus, the term link used in this document refers to the platform-independent functionality in general, not to any specific platform solution.

Introduction

The Access App supports two distinct types of links:

  • App links (Android) and universal links (iOS) - starting with the HTTPS scheme.
  • Custom URIs with x-callback-url support - starting with a custom non-HTTP/HTTPS scheme.
caution

Nevis recommends to use custom URIs with x-callback-url for overall better end-user experience and interoperability.

Each type of link has an impact on the configuration complexity as well as the end user experience. To help you make a decision, the table below summarizes the benefits and drawbacks of each link type:

Benefits:

  • Allows redirecting the end user to a normal/fallback web page in case the app is not installed (as the link uses the universal HTTPS scheme).
  • (iOS) does not ask for permissions before opening the app.

Drawbacks:

  • Complex configuration:
  • Requires special asset JSON files served via the backend.
  • Requires a separate subdomain for the links.
  • Not usable with non-standard browsers that are usually installed on Chinese Android phones such as QQ,CC,360.
  • Not usable with Android devices that don't ship Google Play Services like Huawei EMUI OS.

Custom URIs (with x-callback-url)

Benefits:

  • Easy configuration
  • Allows redirecting the end user to an app or web page after successful, cancelled, or erroneous operations.

Drawbacks:

  • If the app is not installed on the mobile device, the mobile browser does not know how to handle the links; no specific action can be executed.
  • (iOS) asks for permission via pop-up.

Prerequisites

The mobile application is already installed on the phone of the user.

info

If the application is not yet installed, the browser is able to initiate the installation of the mobile application in a convenient way.

How it Works

Out-of-Band Operations with Mobile-Only Solution

The example use case in the above figure shows how linking works. The numbers in the figure correspond with the numbers of the description below.

  1. The end user opens the web page on his/her mobile phone and initiates an out-of-band operation. Because the end user has only one device at hand, and no push notifications are available, the web application offers an alternative possibility in the form of a link.
  2. The user clicks the link. This opens the mobile application and forwards the out-of-band payload.
  3. The user is authenticated.
  4. The desired operation starts.

The following sections describe the link structure for each link type.

Although the concepts slightly differ between the two platforms, the structure of a link is the same for both platforms:

https://<baseUrl>/<path>?dispatchTokenResponse=<base64url_payload>
  • <baseUrl>: Refers to the backend base URL. Usually this is the same URL as the one defined in the SDK instance configuration.
  • <path>: Refers to the path as defined by the backend. This path has to match the path defined in the backend App Association Files.
  • <base64url_payload>: Refers to the out-of-band encrypted payload. This payload matches the payload of the QR code or push message.
info

The nevisFIDO component offers a dispatcher to create the links. For more information, see the nevisFIDO Reference Guide.

info

The nevisFIDO component offers a dispatcher to render the links. For more information, see the nevisFIDO Reference Guide.

Although the concepts slightly differ between the two platforms, the structure of a link based on the custom URI scheme is the same for both platforms. An extension to the custom URI scheme is the use of x-callback-urls. x-callback-urls allow fine-granular control over where the app should navigate after the execution of an operation.

The x-callback-url feature controls the app navigation behavior in the following cases:

  • The operation is successfully completed.
  • The operation is cancelled by the end user.
  • The operation resulted in an error.

To use custom URIs with x-callback-urls, the custom URI has to adhere to the following scheme: <customerUriScheme>://x-callback-url/authenticate?<x-callback parameters>&dispatchTokenResponse=<base64url_payload>

  • <customerUriScheme>: Refers to the application. If there is an application configured with this scheme installed, the system opens the application.

  • x-callback-url: Instead of an arbitrary path or domain, the x-callback-url has to follow right after the custom URI scheme.

  • authenticate: The action is currently fixed to authenticate, however the custom URI link can also be used for registration.

  • <x-callback parameters>: (Optional) Provides the intended navigation target information. The Nevis Access App supports these main x-callback parameters:

  • x-success: Executed upon successful completion of the operation.

  • x-error: Executed upon erroneous completion of the operation.

  • x-cancel: Executed upon user cancellation of the operation.

  • The values of the x-callback parameters are either custom URIs for app-to-app navigation or (HTTPS) URLs for app-to-web navigation. For example: <customerUriScheme>://x-callback-url/register?x-success=otherapp://x-callback-url/success or <customerUriScheme>://x-callback-url/authenticate?x-success=https://example.com/success

  • <base64url_payload>: Refers to the out-of-band encrypted payload. This payload matches the payload of the QR code or push message.

All x-callback parameters are optional. If a parameter for an operation is not defined, no action is executed by the app. It simply stays on the success or error screen of the operation.

info

The x-callback-url specification also mentions the x-source parameter. However, the Nevis Access App does not use this parameter.

Examples

x-callback navigation to web pages
myaccessapp://x-callback-url/register?x-success=https://mydomain.com/success&x-cancel=https://mydomain.com/usercancelled&x-error=https://mydomain.com/error&dispatchTokenResponse=<base64url_payload>
x-callback navigation app-to-app
myaccessapp://x-callback-url/register?x-success=mybusinessapp://x-callback-url/success&x-cancel=mybusinessapp://x-callback-url/usercancelled&x-error=mybusinessapp://x-callback-url/error&dispatchTokenResponse=<base64url_payload>
x-callback navigation mixed
myaccessapp://x-callback-url/register?x-success=mybusinessapp://x-callback-url/success&x-cancel=mybusinessapp://x-callback-url/usercancelled&x-error=https://mydomain.com/error&dispatchTokenResponse=<base64url_payload>
info

Use the custom URI scheme with x-callback-urls, for a more fine-granular end user navigation control.

caution

Using custom URIs with x-callback-url requires providing a whitelist of allowed target apps and/or URLs during the app order process. This is to prevent malicious manipulation of the link rendered in a web page and unintended navigation to an app or webpage.

For more details, see Access App Order Guide.

As both the iOS and Android platform implement their own linking concept, the mobile application implementation slightly differs between the platforms. The following sections describe the linking procedure per platform.

iOS

On iOS, universal links and x-callback-url are used to implement the mobile-only solution.

Prerequisites
  • The end user has to have access to a web application that displays the link generated by the Nevis backend or a third-party system.
  • The link has to refer to an HTTP domain endpoint that hosts an Apple App Association File in a well-known location.
  • The page with the link has to contain an HTML meta tag that allows the Safari browser on iOS to display a smart banner for the application.
How it Works

The end user opens the browser on the mobile device and navigates to the page containing the link. The end user taps on the link and the browser (Safari) displays a banner on the top of the page with a recommendation to open the mobile application if it is installed. If the user decides to open the mobile application, it receives the whole URL to process the data and execute the desired operation in the mobile application.

In case the mobile application is not installed, the aforementioned banner displays a button to install the application. Clicking the button opens the application's App Store entry on the phone. Once the end user completes the installation and navigates back to the browser, the banner changes and display a button to open the mobile application to continue the process as described in the last paragraph.

Once the user has performed the desired operation (either successfully or erroneously), additional text messages prompt her to close the application and return to the browser from where she opened the mobile application.

Platform-Specific Behavior

In iOS, you can navigate back to the previous application via the back-to-app button in the top-left corner of the screen. As the OS itself does not provide API to programmatically initiate this navigation, the user needs to tap the back-to-app button manually, or use the application drawer, to switch.

Custom URI with x-callback-url

Prerequisites

The end user has to have access to a web application that displays the link generated by the Nevis backend or a third-party system.

How it Works
  1. The end user opens the browser on the mobile device and navigates to the page containing the link.
  2. The end user taps on the link.
  • If the mobile application is installed, the browser opens the application. The application receives the whole URL to process the data and execute the desired operation.
  • If the mobile application is not installed, the browser displays a pop-up claiming that the URL is invalid.
  1. After performing the desired operation, the user is prompted to close the application and return to the browser from where they opened the mobile application. This is what exactly happens:
  • The user performed the desired operation successfully. In this case, additional text messages inform the user about an automatic application switch in a predefined time period. The Continue button on the screen shows a countdown indicating when the switch happens. The x-success URL defined in the URL used to open the mobile application determines the application to switch to. If the system cannot open the x-success link, the displayed Success screen does not show additional texts about the application switch nor the countdown timer, and the application switch does not take place.
  • The operation the user tried to perform resulted in an error. Also in this case, additional text messages inform the user about an application switch. But this switch does not happen automatically, so that the user has time to read the displayed error messages. The user has to push a button on the screen to switch to the next application. This application is determined by the x-error URL defined in the URL used to open the mobile application. If the system cannot open the x-error link, the displayed Error screen does not show additional texts about the application switch, and the application switch does not take place.
  • The user decided to cancel the desired operation. In this case, there is an automatic application switch to the application determined by the x-cancel URL in the URL used to open the mobile application. If the system cannot open the x-cancel link, no application switch happens. Instead, an Error screen appears.

Android

On Android, app links and x-callback-url are used to implement the mobile-only solution.

Prerequisites
  • The application is already installed.
  • The end user has access to a web application that displays the link generated by the Nevis backend or a third-party system.
  • The link refers to an HTTP domain endpoint that hosts an App-Site association/link verification file in a well-known location.
How it Works

The end user opens the browser on the mobile device and navigates to the page containing the link. The end user taps on the link and Android opens the application chooser dialog. If the end user decides to open the application, they receive the whole URL to process the data and execute the desired operation in the mobile application.

When the application is not installed on the mobile device, and the link refers to an HTTP(S) domain, the browser follows the link and opens the particular web page. This page displays information that allows the user to install the application, for example by showing a Google Play Store badge.

In the Firefox browser for Android, the link feature does not redirect to the app automatically. The user has to press and hold the link, then choose the option Open link in external app. Alternatively, the user can enable this feature permanently in the browser settings. This behavior is specific for the Firefox browser.

Custom URI with x-callback-url

Once the desired operation is performed successfully, a notification message informs the user to close the application. If the user ignores this, the application closes automatically after a specific period of time. An interactive countdown timer displays the remaining time in seconds before the application shuts down automatically. After application closure, the system navigates to the specified target app or URL if x-callback-urls are used. URLs or app URIs used in x-callback-url have to be whitelisted.

Browser-Specific Behavior

The Custom URI solution works in most mobile browsers. It is successfully tested with the following browsers:

  • Edge
  • Firefox
  • Opera
  • Chrome
  • QQ
  • Mi Browser (from Xiaomi)
  • Baidu Browser (6.0.2)
  • UC Turbo
  • Samsung browser
  • Huawei browser

The feature does not work in the UC Browser and UC Lite Browser.

App to app navigation

In case x-callback-urls are used to navigate from the Nevis Access App to another Android app, the other app needs to have an intent filter specified similar to the following:

<intent-filter>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<data android:scheme="mybankingapp" />
</intent-filter>

Only with such a filter (replacing mybankingapp with an URI scheme for this specific app) allows the app to respond to the navigation request.

info

When planning app to app navigation, the developers of the custom app has to be informed to include the intent filter. Inquiries should be made whether the app supports deep links.

Android Terminology

The official Android documentation uses the terminology deep links for custom URIs. The other concept using domain verification and HTTPS-scheme based links is referred to as app links.

The linking functionality comes with some platform-specific limitations or restrictions.

iOS

  • The universal links are supported by the Safari browser only.
  • The user decision is saved on the device (iOS functionality). Later, the selected app opens immediately without requesting user action. You can change this behavior by pressing long on the link.
  • Universal links have to point to a different domain as they are served on, else the browser does not open the application even if all prerequisites are met. For further info, see here.

Android

  • For universal links, if the application is not installed, the browser attempts to navigate to the link within the browser itself (according to this and this). This makes it necessary to provide a link to the app store, but currently there is no reliable Android API to defer such an app link.

  • If the target app of an x-callback-url does not exist, the user is be sent back to the previously used application.

  • All link navigations have to be user-initiated, meaning that JavaScript cannot be used to open a link (via click or location.href event). This is desired behavior by Chrome itself: newer versions of Chrome block all JavaScript triggering of deep links completely. See here for details.

  • This means that custom URI or deep links have to be rendered in an HTML <a> tag and the end user has to tap the link themselves.

  • This is the process of the chrome browser calling an Android OS API, which our product has no control over.

  • A link cannot target an iFrame or a _new or _blank target.

You can find additional information regarding linking best practices in the Appendixes section.