Implementing authentication in your app

Use Implementing authentication in your web app as your primary reference for implementing FIDO functionality in your Cordova app.

As mentioned previously, there are differences between how the Web App SDK behaves in a web browser versus Cordova. As a result, you can ignore the following sections in the Web app developer guide because they do not apply to Cordova:

• Using FIDO in Cross-origin iframes

• App-less QR-OOB Support

• Sending the User Location Signal

• Uniquely Name Apps with the Same Web Origin

• Considerations for Integration

This section covers two areas where Cordova differs from what's documented in the Web app developer guide:

• Signal configuration
  Unlike a web app, a Cordova app has access to signals available on the mobile device. These can be sent from the App SDK to the Authentication Server to evaluate Adaptive Registration and Adaptive Authentication rules during registration and authentication, respectively.

• Using out-of-band authentication as the second device

A Cordova app can function as the second device in out-of-band authentication, allowing it to securely authenticate a user of a web app. Use functions in plugin_appsdk_oob to enable your Cordova app to respond to push notifications or scan a QR code.

Configuring the App SDK to send signals

If you define Authentication Rules or Registration Decision Rules that use signals, you need to ensure that this data is sent to the Authentication Server so it can use this information.

The App SDK automatically sends simpler signals, like the device model and manufacturer, to the Server. User location and WiFi network take more resources and time to process, so you must configure the App SDK to generate and send these signals. See section Configuring Signal Generation in either the Android or iOS Developer Guide.

Using out-of-band authentication as the second device

Securely authenticating users who are using a web app from your company can be challenging. You don't know if the user is the actual person or someone who has stolen your user's login credentials. Many desktop computers and laptops can't authenticate a user because they don't have a built-in fingerprint scanner or a hardware key store, like a TPM chip.

Out-of-band (OOB) authentication enables you to use a second device tied to the user, typically their cell phone, to authenticate. Your web app initiates authentication by either:

• Sending a push notification to your mobile app installed on the user's cell phone. When the user receives the notification, they authenticate with your mobile app using a registered FIDO authenticator, like fingerprint.

• Displaying a QR code on the device running your web app. The user scans the QR code with your mobile app, then authenticates with a registered FIDO authenticator.

Implementing OOB in a Cordova app requires using the PluginAppSDKOOBPromised class. This class enables your app to use the native layer without worrying about the differences between Android and iOS. Both plugin_appsdk_oob and plugin_appsdk are required for PluginAppSDKOOBPromised to work.

While a push notification can start authentication for a user, it cannot be used to trigger registration for an authenticator. Scanning a QR code can initiate both registration and authentication.

OOB requires configuring your app on the Authentication Server. For instructions see Out-of-band.

• If you use push notifications in iOS devices, use Apple Push Notification service.

• If you use push notifications in Android devices, you need to use Firebase Cloud Messaging (FCM) and/or Huawei Mobile Services (HMS).

Configuring for push notifications on Android devices

The App SDK supports OOB push notifications in Android devices using either Google Play Services or Huawei Mobile Services (HMS). You can implement your app to support both these services or just one of them.

To respond to push notifications in your Cordova app that runs on Android, perform the following steps. The documentation sections are in the Android Developer Guide.

1. If you are using FCM, follow the instructions in section Adding Firebase Configuration.

2. If you are using HMS, follow the instructions in section Adding Huawei Mobile Services Configuration.

3. Include FCM and/or HMS services for push notifications by using the instructions in section Editing the Manifest.

Configuring for push notification on iOS devices

No special configuration needed.

Implementing push notification processing and QR code scanning in Cordova

Cordova apps can support OOB by processing push notifications and/or by scanning QR codes. The following steps show how to implement this feature in Cordova.

1. Optional. By default, OOB uses the UAF protocol. To use FIDO2, call PluginAppSDKOOBPromised.setProtocol(AppSdk.PROTOCOL_FIDO2).

2. Implement the callback function that the system calls when your app receives a push notification or has scanned the QR code. In addition to implementing any logic required by your app, this callback function has the following requirements:

   • It must take two parameters called oobData (string) and isFromPush (boolean). When your callback function is called, the App SDK assigns the data from the push notification or QR code to the oobData object. Do not modify the contents of oobData. If the data is from a push notification, the App SDK assigns true to isFromPush.

   • Call appSdk.processOob(), passing in oobData to this method. processOOB() implements the Android and iOS-specific processing needed to start user authentication on the device.

   • After the call to appSdk.processOob() and if isFromPush is true, call PluginAppSDKOOBPromised.closeApp() to properly shut down OOB processing.

3. Set the callback function you created in Step 2 as a callback by passing the entire function definition to PluginAppSDKOOBPromised.setOobDataReceivedCallback().

PluginAppSDKOOBPromised.setOobDataReceivedCallback(function(oobData, isFromPush) { <your code> } );

4. Initialize OOB by calling PluginAppSDKOOBPromised.initializeOOB().

5. Your app must have a button or another mechanism to allow the end user to scan a QR code. Implement a function for that button click event. This function must call PluginAppSDKOOBPromised.createScannerFragment(). The function createScannerFragment() starts the QR code scanning process and then calls the callback function you created in Step 2 above.

Refer to the Client API Docs for more details on class PluginAppSDKOOBPromised and class AppSDK.

Working Examples in the Cordova Tutorial App

Refer to the following functions in file app_tutorial\www\js\Controller.js.

• The definition of function initializeOOB() shows how to call PluginAppSDKOOBPromised.setOobDataReceivedCallback() and PluginAppSDKOOBPromised.initializeOOB().

• The call to PluginAppSDKOOBPromised.setOobDataReceivedCallback() shows an example callback function definition that contains a call to processOOBData().

• The definition of function processOOBData() shows how to call appSdk.processOob() and PluginAppSDKOOBPromised.closeApp().