FIDO

1. Introduction

Overview

HUAWEI FIDO2 provides your app with FIDO2 based on the WebAuthn standard. It provides Android Java APIs for apps and browsers, and allows users to complete authentication through roaming authenticators (USB, NFC, and Bluetooth authenticators) and platform authenticators (fingerprint and 3D face authenticators).

What You Will Create

In this codelab, you will use the demo project that has been created for you to call HUAWEI FIDO2 client APIs. Through the demo project, you will:

Call the HUAWEI FIDO2 client API to complete registration.
Call the HUAWEI FIDO2 client API to complete authentication.

What You Will Learn

In this codelab, you will learn how to:

Create an app in AppGallery Connect.
Integrate the HUAWEI FIDO2 client into your app.

Other Features

FIDO (BioAuthn)

2. What You Will Need

Hardware Requirements

A computer (desktop or laptop) running Windows 7 or Windows 10
A Huawei phone (with a USB cable) for app debugging

Software Requirements

JDK 1.8.211 or later
Android Studio: 3.X or later
- minSdkVersion: 19 or later
- targetSdkVersion: 29 (recommended)
- compileSdkVersion: 29 (recommended)
- Gradle: 4.6 or later (recommended)
Test device: a Huawei phone running EMUI 4.0 or later
If you need to use multiple HMS Core kits, use the latest versions required for these kits.

3. Integration Preparations

To integrate FIDO2 client, you must complete the following preparations:

Create an app in AppGallery Connect.
Create an Android Studio project.
Generate a signing certificate.
Generate a signing certificate fingerprint.
Configure the signing certificate fingerprint.
Add the app package name and save the configuration file.
Add the AppGallery Connect plugin and the Maven repository in the project-level build.gradle file.
Configure the signing certificate in Android Studio.

For details, please refer to Preparations for Integrating HUAWEI HMS Core.

4. Enabling FIDO

Sign in to AppGallery Connect, click My projects, find your project, and click your desired app. Then, go to Project settings > Manage APIs.
Toggle on the FIDO switch.

5. Integrating the HMS Core SDK

If you are using Android Studio, you can integrate the HMS Core SDK via the Maven repository. Before you start developing an app, integrate the HMS Core SDK into your Android Studio project.

Adding the AppGallery Connect Configuration File of Your App

If you have enabled certain services in AppGallery Connect, add the agconnect-services.json file to your app.
步骤 1 - Sign in to AppGallery Connect and click My projects.
步骤 2 - Find your app project and click the app that needs to integrate the HMS Core SDK.
步骤 3 - Go to Project settings > General information. In the App information area, download the agconnect-services.json file.

步骤 4 - Copy the agconnect-services.json file to your app's root directory.

—-End

Configuring the Maven Repository Address for the HMS Core SDK

步骤 1 - Open the build.gradle file in the root directory of your Android Studio project.

步骤 2 - Add the AppGallery Connect plugin and the Maven repository.

Go to buildscript > repositories and configure the Maven repository address for the HMS Core SDK.
Go to allprojects > repositories and configure the Maven repository address for the HMS Core SDK.

If the agconnect-services.json file has been added to the app, go to buildscript > dependencies and add the AppGallery Connect plugin configuration.


buildscript { 
    repositories { 
        google() 
        jcenter() 
        // Configure the Maven repository address for the HMS Core SDK. 
        maven {url 'https://developer.huawei.com/repo/'} 
    } 
    dependencies { 
        ... 
        // Add the AppGallery Connect plugin configuration. You are advised to use the latest plugin version. 
        classpath 'com.huawei.agconnect:agcp:1.6.0.300' 
    } 
} 
 
allprojects { 
    repositories { 
        google() 
        jcenter() 
        // Configure the Maven repository address for the HMS Core SDK. 
        maven {url 'https://developer.huawei.com/repo/'} 
    } 
}

In Gradle 7.0 or later, configuration under allprojects > repositories is migrated to the project-level settings.gradle file.
The following is a configuration example of the settings.gradle file:


dependencyResolutionManagement { 
    ... 
    repositories { 
        google() 
        jcenter()  
        maven {url 'https://developer.huawei.com/repo/'} 
    } 
}

—-End

Adding Build Dependencies

步骤 1 - Open the app-level build.gradle file of your project.

步骤 2 - Add the AppGallery Connect plugin configuration in either of the following methods:

Method 1: Add the following information under the declaration in the file header:
```
apply plugin: 'com.huawei.agconnect'
```

Method 2: Add the plugin configuration in the plugins block.


plugins { 
    id 'com.android.application' 
    // Add the following configuration: 
    id 'com.huawei.agconnect' 
}

步骤 3 - Add build dependencies. (Do not add dependencies on both BioAuthn-AndroidX and BioAuthn.)

FIDO2


dependencies { 
    implementation 'com.huawei.hms:fido-fido2:{version}' 
}

BioAuthn-AndroidX


dependencies { 
    implementation 'com.huawei.hms:fido-bioauthn-androidx:{version}' 
}

BioAuthn
```
dependencies { 
    implementation 'com.huawei.hms:fido-bioauthn:{version}' 
}
```
Replace {version} with the actual SDK version number, for example, implementation ‘com.huawei.hms:fido-fido2:6.1.0.301'. For details about the version number, please refer to Version Change History.

—-End

Defining Multi-language Settings

By default, your app supports all languages provided by the HMS Core SDK. If your app uses all these languages, skip the operation procedure in this section.
If your app uses only some of these languages, follow the operation procedure in this section to complete the required configuration.
a) Open the app-level build.gradle file of your project.

b) Go to android > defaultConfig, add resConfigs, and configure the supported languages as follows:
```
android { 
    defaultConfig { 
        ... 
        resConfigs "en", "zh-rCN", "Other languages supported by your app" 
    } 
}        
```
For details about the languages supported by the HMS Core SDK, please refer to Languages Supported by the HMS Core SDK.

Synchronizing the Project

Open the modified build.gradle file again. Click Sync Now in the upper right corner and wait until synchronization is complete.

Configuring Metadata

In the following scenario, configure metadata to prompt users to download HMS Core (APK):
The app store (such as HUAWEI AppGallery) allows your app to download other apps in the background, and you call relevant APIs through an activity.
In the following scenario, skip steps in this section. Currently, no way is available for prompting users to download HMS Core (APK).
The app store (such as Google Play) does not allow your app to download other apps in the background, or you call relevant APIs through a context.
Add the following code to the application element in the AndroidManifest.xml file, prompting users to download HMS Core (APK):


<application ...> 
    <meta-data      
        android:name="com.huawei.hms.client.channel.androidMarket"   
        android:value="false" /> 
    ... 
</application>

After HMS Core (APK) is downloaded, the HMS Core SDK will automatically install or update HMS Core (APK).

Configuring the AndroidManifest.xml File

In Android 11, the way for an app to query other apps on the user device and interact with them has been changed. IftargetSdkVersionn is300 or later for your app, add the> element in themanifestt element inAndroidManifest.xmll to allow your app to access HMS Core (APK).


<manifest ...> 
    ... 
    <queries> 
        <intent> 
            <action android:name="com.huawei.hms.core.aidlservice" /> 
        </intent> 
    </queries> 
    ... 
</manifest>

6. Development Procedure

FIDO2 provides the WebAuthn-based FIDO2 client. This codelab only describes how to use FIDO2 client APIs. For details about operations related to the app server and FIDO server, please refer to related standards.
To integrate the FIDO2 client, perform the following steps:

Initialize a Fido2Client object using an activity instance. The object can be written in the onCreate method of the activity.


Java 
Fido2Client fido2Client = Fido2.getFido2Client(this);
Kotlin 
Fido2Client fido2Client = Fido2.getFido2Client(this)

Obtain a challenge value and the registration or authentication policy from the FIDO server, and initiate an authentication or registration request based on the obtained information.


Java 
// Obtain the challenge value and related policy from the FIDO server, and initiate a Fido2RegistrationRequest 
// request. 
ServerPublicKeyCredentialCreationOptionsResponse response = fidoServer.getAttestationOptions(request); 
if (!ServerStatus.OK.equals(response.getStatus())) { 
    Log.e(TAG, getString(R.string.reg_fail) + response.getErrorMessage()); 
    showError(getString(R.string.reg_fail) + response.getErrorMessage()); 
} 
PublicKeyCredentialCreationOptions publicKeyCredentialCreationOptions = 
        ServerUtils.convert2PublicKeyCredentialCreationOptions(fido2Client,response);
Kotlin 
// Obtain the challenge value and related policy from the FIDO server, and initiate a Fido2RegistrationRequest 
// request. 
val response = fidoServer.getAttestationOptions(request) 
if (ServerStatus.OK != response.status) { 
    Log.e(TAG, getString(R.string.reg_fail) + response.errorMessage) 
    showError(getString(R.string.reg_fail) + response.errorMessage) 
} 
val fido2ClientTmp = fido2Client; 
if (fido2ClientTmp != null) { 
    val publicKeyCredentialCreationOptions = ServerUtils.convert2PublicKeyCredentialCreationOptions(fido2ClientTmp, response) 
    reg2Fido2Client(publicKeyCredentialCreationOptions) 
}

Call getRegistrationIntent() or getAuthenticationIntent() to initiate registration or authentication.

Call launchFido2Activity in Fido2IntentCallback to launch the registration or authentication page.


Java 
fido2Client.getRegistrationIntent(registrationRequest, registrationOptions, new Fido2IntentCallback() { 
    @Override 
    public void onSuccess(Fido2Intent fido2Intent) { 
        fido2Intent.launchFido2Activity(Fido2DemoMainActivity.this, Fido2Client.REGISTRATION_REQUEST); 
    } 
    @Override 
    public void onFailure(int errorCode, CharSequence errString) { 
        showError(getString(R.string.reg_fail) + errorCode + "=" + errString); 
    } 
});
Kotlin 
fido2Client!!.getRegistrationIntent(registrationRequest, registrationOptions, object : Fido2IntentCallback { 
    override fun onSuccess(fido2Intent: Fido2Intent) { 
        fido2Intent.launchFido2Activity(this@Fido2DemoMainActivity, Fido2Client.REGISTRATION_REQUEST) 
    } 
    override fun onFailure(errorCode: Int, errString: CharSequence) { 
        showError(getString(R.string.reg_fail) + errorCode + "=" + errString) 
    } 
})

Call getFido2RegistrationResponse or getFido2AuthenticationResponse in activity.onActivityResult to obtain the registration or authentication response.


Java 
switch (requestCode) { 
    // Receive the registration response. 
    case Fido2Client.REGISTRATION_REQUEST: 
        Fido2RegistrationResponse fido2RegistrationResponse = fido2Client.getFido2RegistrationResponse(data); 
        reg2Server(fido2RegistrationResponse); 
        break; 
    // Receive the authentication response. 
    case Fido2Client.AUTHENTICATION_REQUEST: 
        Fido2AuthenticationResponse fido2AuthenticationResponse = 
                fido2Client.getFido2AuthenticationResponse(data); 
        auth2Server(fido2AuthenticationResponse); 
        break; 
    default: 
        break; 
}
Kotlin 
when (requestCode) { 
     // Receive the registration response. 
     Fido2Client.REGISTRATION_REQUEST -> { 
         val fido2RegistrationResponse = fido2Client!!.getFido2RegistrationResponse(data) 
         reg2Server(fido2RegistrationResponse) 
     } 
     // Receive the authentication response. 
     Fido2Client.AUTHENTICATION_REQUEST -> { 
         val fido2AuthenticationResponse = fido2Client!!.getFido2AuthenticationResponse(data) 
         auth2Server(fido2AuthenticationResponse) 
     } 
     else -> { 
     } 
 }

Only Huawei phones running EMUI 4.0 or later support FIDO2.
To use a specific platform authenticator, call Fido2Client.hasPlatformAuthenticators() to check for available platform authenticators, call Fido2Client.getPlatformAuthenticators() to obtain information about these authenticators, select the specific platform authenticator as needed, and set the extension item Fido2Extension.HMS_RA_C_PACL_01. If a platform authenticator is specified, you also need to set the first input parameter of the constructor AuthenticatorSelectionCriteria in PublicKeyCredentialCreationOptions.Builder.setAuthenticatorSelection(new AuthenticatorSelectionCriteria(Attachment.PLATFORM, null, null)) to Attachment.PLATFORM. If no platform authenticator is specified, you can set the first input parameter of the constructor to null.

7. Testing Your App

Install the test APK, launch the app, and tap Register or Authenticate.

8. Congratulations

Well done. You have successfully completed this codelab and learned how to:

Create an app in AppGallery Connect.
Integrate the HUAWEI FIDO2 client in your app.

9. Reference

For more information, please click the following link:

Related documents
To download the sample code, click the link below:

Download

Back