Integration of the FIDO ASMs

The integration of the OneSpanFIDO Authentication Solution involves the configuration of the FIDO Server and the integration of the FIDO ASMs on Android and iOS

Configuration of the FIDO Server

Before you integrate the FIDO ASM with the Tutorial App Plus application on iOS and/or Android, you need to configure the FIDO Server. To do so, follow the instructions provided in the Nok Nok Labs documentation. Once the FIDO Server configuration is completed, configure the FIDO Server to use the OneSpan-specific configuration as outlined below.

To configure the FIDO Server to use the OneSpan Configuration Wizard

You can perform these steps either by using the nnl-mgmt.sh file, or by using the policy files available in the OneSpan FIDO Server package. When you choose to use the nnl-mgmt.sh, refer to the Nok Nok Labs documentation for more details.

1. Import the required ASM(s).

   You need to use the Authenticator Metadata and Import commands of the nnl-mgmt.sh script.

   If you use the policy files from the FIDO Server package, run the following command in the onespan-asm-json folder:

   ./nnl-mgmt.sh auth_metadata import -dir /path_to_folder/onespan-asm-json/

2. Import and activate the policies.

   You need to use the FIDO Policy and Import commands of the nnl-mgmt.sh script.

   If you use the policy files from the FIDO Server package, run the following commands in the onespan-policy-json folder:

   ./nnl-mgmt.sh policy import -file /path_to_folder/policy_you_want.json

   ./nnl-mgmt.sh policy activate -name "name of the imported policy"

3. Create and activate the rule set.

   You need to use the Adaptive Ruleset and Import commands of the nnl-mgmt.sh script.

   If you use the ruleset file from the FIDO Server package, run the following commands in the onespan-ruleset-json folder:

   ./nnl-mgmt.sh ruleset import -dir /path_to_folder/onespan-ruleset-json/ruleset_you_want.json

   ./nnl-mgmt.sh ruleset activate -name "name of the imported ruleset"

4. Authorize the OneSpan applications to communicate with the FIDO Server.

   You need to use the Properties and Set property commands of the nnl-mgmt.sh script.

   Examples how to authorize OneSpan FIDO Server Manager for Android and iOS:

   Android

   ./nnl-mgmt.sh properties set -name android:com.onespan.fido.uaf.passport##app.names -value "OneSpan FIDO Server Manager for Android" -uaffacetid android:apk-key-hash:QyzgKcO/5TmWhuRK3DLW2GYu5ZM

   ./nnl-mgmt.sh properties set -name android:com.onespan.fido.uaf.passport##ruleset.name -value default

   iOS

   ./nnl-mgmt.sh properties set -name ios:com.onespan.fido.uaf.passport##app.names -value "OneSpan FIDO Server Manager for iOS" -uaffacetid ios:bundle-id:com.onespan.fido.uaf.passport

   ./nnl-mgmt.sh properties set -name ios:com.onespan.fido.uaf.passport##ruleset.name -value default

5. Validate the global policy by modifying PolicyPlugin.

   You need to use the API Server Configuration and Import commands of the nnl-mgmt.sh script.

   If you use the PolicyPlugin file from the FIDO Server package, run the following command in the onespan-policyplugin-json folder:

   ./nnl-mgmt.sh apiserver import -type PolicyPlugin -file /path_to_folder/onespan-policyplugin-json/policyplugin_you_want.json -overwrite yes

For more information on any of these steps, refer to the Nok Nok Labs documentation.

Follow the steps below to integrate the ASMs on Android.

To integrate the OneSpanFIDO ASMs on Android with the Tutorial App Plus application

1. Make sure that the value for minSdkVersion (which you can find in the main build.gradle file) of the Tutorial App Plus is equal to or higher than the value for minSdkVersion of the ASMs—see Supported platforms.

2. Make the following changes to the gradle file:

   1. Navigate to project>root>build.gradle and change the classpath from 'com.android.tools.build:gradle:4.0.1' to 'com.android.tools.build:gradle:8.2.2'.

   2. Navigate to gradle.properties and change 'android.jetifier.blacklist = pass-1.2.2' to 'android.jetifier.ignorelist = pass-1.2.2'.

   3. Navigate to app>build.gradle and add the namespace' com.noknok.android.tutorialappplus' in android{}.

3. Change the gradle-wrapper.properties file to use gradle 6.1.1:

   distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-all.zip

4. Change the gradle to use Java 11:
   In Android Studio, go to File>Settings>Build, Execution, Deployment>Build Tools>Gradle and select Java 11 (or JDK 11).

5. Copy the ASM libraries (.aar files) and their dependencies to a directory in the Tutorial App, e.g. app/libs.

6. Integrate the Presence ASM in your app—see Integration of the Presence ASM for more detailed information.

7. Integrate the User Input ASM (PIN/password) in your app—see Integration of the User Input ASM for more detailed information.

8. Integrate the Native Biometric Authentication ASM—see Integration of the Native Biometric Authentication ASM for more detailed information.

9. (OPTIONAL) Embed an authenticator—see Embedding of an authenticator for more detailed information.

10. After the integration of the FIDO ASMs is completed, raw/asmdescriptors.json should look like this:

    { 					
      	"descriptorclass":[					
      "com.vasco.fido.uaf.asm.biometric.NativeBiometricAuthenticationASMDescriptor",
      "com.vasco.fido.uaf.asm.presence.PresenceASMDescriptor",  				
      "com.vasco.fido.uaf.asm.userinput.PinASMDescriptor",					
      "com.vasco.fido.uaf.asm.userinput.PasswordASMDescriptor" 					
      ] 					
    }  

11. Configure your server endpoint in the TutorialApp class: modify the host variable:

    public static final String host = "https://<your endpoint>";

12. In build.gradle, add the following inside the android{} block:

    packagingOptions {
    exclude 'META-INF/lib_release.kotlin_module'
    }

13. In app/build.gradle, remove the line dependency 'api "com.noknok:asm_spass2:7.0.2-326"' and add the following lines inside dependencies{} block:

    constraints { 
      implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.8.0") { 
        because("kotlin-stdlib-jdk7 is now a part of kotlin-stdlib") 
      }  					
      implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.8.0") { 					
        because("kotlin-stdlib-jdk8 is now a part of kotlin-stdlib") 					
      }
    }  					
    api files('libs/FIDOUAFCommonASM.aar') 					
    api files('libs/FIDOUAFNativeBiometricAuthenticationASM.aar') 					
    api files('libs/FIDOUAFPresenceASM.aar') 					
    api files('libs/FIDOUAFUserInputASM.aar') 					
    api files('libs/BiometricSensorSDK.aar') 					
    api files('libs/DeviceBindingSDK.aar') 					
    api files('libs/SecureStorageSDK.aar') 					
    api files('libs/UtilitiesSDK.aar') 					
    api "androidx.biometric:biometric:1.1.0" 					
    api "androidx.constraintlayout:constraintlayout:2.0.4"
    implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])

14. Customize the transaction screen—Common ASM; see Integration of the Common ASM—Customization of the Transaction Screen for more detailed information.

15. Customize the anti-hammering protection; see Customization of the Anti-hammering Protection for more detailed information.

16. When working with Android version 14 (API level 34) and later, make the following changes in the application:

    1. Replace all instances of 'switch' with 'if else'.

    2. Navigate to TutorialPlusSuggestionUI.java class and change line 34: replace 'builder.setMessage(R.string.nnl_appsdk_plus_use_platform_authenticator);' with 'builder.setMessage(com.noknok.android.client.appsdk_plus.R.string.nnl_appsdk_plus_use_platform_authenticator);'.

    3. Add android:exported = 'true' where needed.

    4. In android>AndroidManifest, add '<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>'.

    5. Navigate to app build.gradle and change the api from 'net.openid:appauth:0.6.0' to 'net.openid:appauth:0.7.0'

    6. Navigate to android>AndroidManifest.xml and add the following:

       • <receiver android:name="com.huawei.hms.support.api.push.PushMsgReceiver" android:exported="true"/>

       • <receiver android:name="com.huawei.hms.support.api.push.PushReceiver" android:exported="true"/>

    7. In app build.gradle, remove 'com.noknok:asm_spass2:7.0.2-326'.

17. Run the Tutorial App Plus application.

Follow the steps below to integrate the ASMs on iOS.

To integrate the OneSpanFIDO ASMs on iOS with the Tutorial App Plus application

1. Copy all required ASM frameworks and their dependencies (libraries) to a directory in the Tutorial App Plus, e.g. TutorialAppPlus/.../Frameworks.

   If you chose a different directory than TutorialAppPlus/.../Frameworks, you need to configure search paths in the build settings for the frameworks and their dependencies.

2. Integrate the Presence ASM in your app—see Integration of the Presence ASM for more detailed information.

3. Integrate the User Input ASM (PIN/password) in your app—see Integration of the User Input ASM for more detailed information.

4. Integrate the Native Biometric Authentication ASM—see Integration of the Native Biometric Authentication ASM for more detailed information.

5. (OPTIONAL) Embed an authenticator—see Embedding of an authenticator for more detailed information.

The following examples illustrates how to add all OneSpanFIDO ASMs to the AppDelegate class:

C++

//Add presence authenticator to ASM
asmcore::ASMFactory::addAuthenticator(FIDOPresenceASMInstanceCreator::createInstance());
//Add Touch ID authenticator to ASM
asmcore::ASMFactory::addAuthenticator(FIDONativeBiometricAuthenticationASMInstanceCreator::createTouchIDInstance());
//Add Face ID authenticator to ASM
asmcore::ASMFactory::addAuthenticator(FIDONativeBiometricAuthenticationASMInstanceCreator::createFaceIDInstance());
//Add PIN/Password authenticator to ASM
asmcore::ASMFactory::addAuthenticator(FIDOUserInputASMInstanceCreator::createPinInstance());
asmcore::ASMFactory::addAuthenticator(FIDOUserInputASMInstanceCreator::createPasswordInstance());

Swift/Objective-C

// Add presence authenticator to ASM
FIDOPresenceASM.registerPresenceAuthenticator()
// Add Touch ID authenticator to ASM
FIDOBiometricASM.registerTouchIDAuthenticator()
// Add Face ID authenticator to ASM
FIDOBiometricASM.registerFaceIDAuthenticator()
// Add PIN/Password authenticator to ASM
FIDOUserInputASM.registerPinAuthenticator()
FIDOUserInputASM.registerPasswordAuthenticator()

6. Configure your server URLs in the Constant.h file.
   You need to modify the endpoints of the following constants:

   • LOGIN_SERVER_URL

   • REG_SERVER_URL

   • AUTH_SERVER_URL

   • WEBVIEW_URL

   • APPID

7. Customize the transaction screen—Common ASM; see Integration of the Common ASM—Customization of the Transaction Screen for more detailed information.

8. Customize the anti-hammering protection; see Customization of the Anti-hammering Protection for more detailed information.

9. Run the Tutorial App Plus application.