Introduction
This provides developer-focused technical details on incorporating strong authentication using the Digipass S3 App SDK for Android (referred to as the “App SDK”) and the FIDO Alliance’s Universal Authentication Framework specification. By reading this document, a developer will learn how to:
Integrate a mobile app with the Digipass S3 Authentication Server
Deliver strong authentication on FIDO Ready™ and FIDO Certified™ devices
Support non-FIDO Ready and non-FIDO Certified devices
This is intended for an intermediate Android developer with strong working knowledge of Java, Android Studio, Gradle, and the Android APIs.
Overview
The major topics covered in this category fall into the following areas:
Getting Started - List of App SDK modules, and information on Google Play and Huawei Mobile Services.
Setting Up the App SDK - Covers how to specify library versions and import dependencies.
Using the App SDK - Discusses important points about the synchronous nature of the App SDK, the SessionData object, and error handling. Also lists the supported authenticators.
Implementing Authentication in Your App - Describes how to use the App SDK to implement the Authentication Lifecycle, out-of-band authentication, and registering for Quick Authentication. You can find other useful topics like device blessing support, embedding a WebView, and more.
Packaging Options - Provides instructions on how to embed a local FIDO client, embed an authenticator, and more.
Getting started
To fully understand the materials presented here, we strongly urge you to read many of the pages on the Start menu first.
By using the App SDK for Android, your app can take advantage of FIDO-enabled devices to perform strong authentication without relying on passwords. The App SDK performs authentication by using the adaptive policies, FIDO policies, authentication methods, and data lists configured on the Digipass S3 Authentication Server.
The App SDK supports Android mobile and Wear OS watch devices. Digipass S3 recommends the following development approach:
Incorporate the App SDK into your mobile app and get Adaptive Authentication working.
Incorporate the App SDK into your watch app.
Sample applications that you can build are described in Exploring Tutorial App and Exploring the Wear OS Tutorial App.
Prerequisites and supported platforms
See the App SDK for Android Release Notes for details.
What’s in the SDK?
The App SDK package contains the following folders and files:
Folder Name / File Name | Description |
|---|---|
AppSDK | Folder containing all required Android libraries and Client API Docs for building fully functional FIDO enabled mobile applications. This includes Tutorial App, an Android Studio project for a simple mobile application that demonstrates how to use the App SDK to perform FIDO operations. |
asm_keyguard_service-release.apk | The apk file of a Keyguard-based authenticator used with Tutorial App |
asm_native_fps_service-release.apk | The apk file of the Native biometric authenticator used with Tutorial App |
asm_pin_service-release.apk | The apk file of the PIN-based authenticator used with Tutorial App |
asm_presence_service-release.apk | The apk file of the Yes/No authenticator used with Tutorial App |
asm_silent_service-release.apk | The apk file of the silent authenticator for use with Tutorial App |
licenses | Folder containing license files of 3rd party software used in the App SDK |
metadata | Folder containing Authenticator Attestation ID (AAID) .json metadata files required for using Android-specific Authenticators. |
values | Folder containing localization strings |
App SDK modules
Add the App SDK modules to the build.gradle file depending on the functionality you want in your app. Here is an example of how to add the dependencies.
dependencies {
// Dependency for core App SDK APIs
api "com.noknok:appsdk_plus"
// Dependency for the Adaptive APIs
api "com.noknok:appsdk_adaptive"
// Dependency for the FIDO2 using Google Play Services
api "com.noknok:appsdk_fido2"
// Dependency for FIDO2 using HMS
api "com.noknok:appsdk_hms_fido2"
// Dependency for UAF with embedded client
api "com.noknok:mfac_uaf"
api "com.noknok:appsdk_uaf"
// Use the Native Fingerprint ASM
api "com.noknok:asm_native_fps"
// Add more to this list if needed
}Modules in the App SDK:
Module Name | Description | Category |
|---|---|---|
com.noknok:appsdk_plus | Module for main APIs for FIDO registration, authentication, transaction confirmation, and deregistration. | Mandatory |
com.noknok:appsdk_adaptive | Module for using authentication that adapts to contextual information. Supports both FIDO and non-FIDO authentication methods. Non-FIDO authentication methods include SMS OTP, email OTP, and Photo ID. | Mandatory |
com.noknok:appsdk_uaf | Module for UAF protocol. Note that the UAF and FIDO2 protocols can be used independently, so a dependency could be added for one protocol or both together. | Strongly recommended |
com.noknok:mfac_uaf | Module for UAF for the embedded FIDO Client. A FIDO client is required to process FIDO UAF messages. The most common configuration is to embed the client into your app. | Strongly recommended |
com.noknok:appsdk_fido2 | Module for FIDO2 protocol. Note that the UAF and FIDO2 protocols can be used independently, so a dependency could be added for one protocol or add dependencies for both together. For devices supporting Google Play Services. | Strongly recommended |
com.noknok:appsdk_hms_fido2 | Include to support FIDO2 on devices using Huawei Mobile Services. | Optional |
com.noknok:appsdk_fcm_push | Include to support push notifications on devices using Google’s Firebase Messaging Services. | Optional |
com.noknok:appsdk_hms_push | Include to support push notifications on devices using Huawei Mobile Services. Use only for Huawei devices that do not support Google Play Services. | Optional |
com.noknok:asmsdk_ble | Module for supporting CTAP over BLE. | Optional |
com.noknok.asmsdk_ctap | Module to allow an app to expose an authenticator using CTAP. | Optional |
com.noknok:appsdk_passport | Module for using the Passport API. | Optional |
com.noknok:appsdk_vision | Module for scanning a QR code for OOB authentication. For devices that support Google Play Services. | Optional |
com.noknok:appsdk_hms_scan | Include to support scanning a QR code for OOB authentication on devices that support Huawei Mobile Services. Use only for Huawei devices that do not support Google Play Services. | Optional |
com.noknok:appsdk_hms_location | Include to support get location on devices that support Huawei Mobile Services. Use only for Huawei devices that do not support Google Play Services. | Optional |
com.noknok:common_okhttp | Include to support async functionality and HTTP/2 protocol. This component requires Android 5.0 (API level 21) and above | Strongly recommended |
com.noknok:asm_keyguard | The embedded fKeyguard Authenticator Specific Module (ASM) | Optional |
com.noknok:asm_native_fps | The embedded Native Biometric ASM | Optional |
com.noknok:asm_pin | The embedded PIN ASM | Optional |
com.noknok:asm_presence | The embedded Yes/No ASM | Optional |
com.noknok:asm_silent | The embedded Silent ASM | Optional |
com.noknok:asm_watch | The embedded Wear OS watch ASM | Optional |
Below are other modules that can get included automatically based on the dependencies that you add from the above table. Do not add these to your build.gradle.
Module Name | Description |
|---|---|
com.noknok:appsdk | Common module for the App SDK, including AppSDK2 |
com.noknok:asmsdk | Common module for ASM SDK |
com.noknok:asmsdk_pin_mgt | The PIN Management Library |
com.noknok:asmsdk_uaf | UAF-specific code for ASM SDK |
com.noknok:common | Code common across all libraries |
com.noknok:common_uaf | UAF code common across all libraries |
com.noknok:mfac | Common code for the local FIDO Client |
Android Studio-specific modules are located in the <APP_SDK_HOME>/android-studio/m2repository folder.
Setting up for Google Play Services
The App SDK features listed in the following table depend on Google Play Services libraries. You can include libraries for both HMS and Google Play Services in your app. The versions listed below are the minimum versions needed.
App SDK Feature | Google Play Services Library |
|---|---|
Out-of-band Authentication using push notification | firebase-messaging:24.0.1 |
Out-of-band Authentication by scanning a QR code | play-services-vision: 20.1.3 |
FIDO2 Authentication | play-services-fido:21.1.0 |
Google’s Multi-device Passkey Authentication | play-services-auth:21.2.0 |
Google’s Multi-device Passkey Authentication using CredentialManager APIs | credentials-play-services-auth:1.2.2, credentials:1.2.2 |
play-services-location:21.0.1 | |
Play Integrity API (replaces SafetyNet) | com.google.android.play:integrity:1.3.0 |
Using the Wear OS watch authenticator | play-services-wearable:18.2.0 |
In order for push notification to work, you must register your app with Firebase. See Google's Add Firebase using the Firebase console.
Restricting Google API keys
Your app's Google API key needs to be restricted if you use push notifications for OOB authentication. See Restrict Your App's Google API Key.
Setting up for Huawei Mobile Services
The App SDK features listed in the following table depend on Huawei Mobile Services libraries. You can include libraries for both HMS and Google Play Services in your app. The versions listed below are the minimum versions needed.
App SDK Feature | Huawei Mobile Services |
|---|---|
Out-of-band authentication using push notification | com.huawei.hms:push:6.11.0.300 |
Out-of-band authentication by scanning a QR code | com.huawei.hms:scan:2.12.0.301 |
FIDO2 Authentication | com.huawei.hms:fido-fido2:6.7.0.301 |
com.huawei.hms:location:6.12.0.300 |
For an end user to take advantage of platform authentication, their device must use HMS Core version 6.15.0.312 or above.
In order for FIDO2 or push notifications to work, you need to use Huawei's AppGallery Connect. See Configure your app information in AppGallery Connect. Follow the steps below.
Enable the desired service from “Manage APIs”. For example, FIDO service for FIDO2 authentication or Push Kit for push notifications.
Set your SHA-256 certificate fingerprint in the AppGallery Console for the registered app. Refer to Creating an App in AppGallery Connect from Huawei's code lab example.
Download the configuration file agconnect-services.json and put in your project. See section Integrating the AppGallery Connect SDK in Android Studio in Huawei's Getting Started with Android.
Restricting HMS API keys
Your app's HMS API key needs to be restricted to only use FIDO and/or push notifications. See Restricting Your App's HMS API Key.