Set up Mobile FIDO SDK for Android

This section describes the necessary steps to set up and run the sample app provided. The sample codes provide the steps to execute the use cases.

Clone the source code

The source code of this sample app is available on GitHub.

Obtain the source code at https://github.com/ThalesGroup/fido2-sample-android and clone a copy of the source code to your desired location.

You can either clone the whole repository or choose the Download ZIP option.

Set up the Android Gradle project

The steps to set up this project are minimal.

1. Integrate the Mobile FIDO SDK using Maven and JFrog

This project requires the necessary SDK dependencies in order to compile. The Mobile FIDO SDK is integrated via Thales JFrog Artifactory.

1.1 Configure JFrog credentials

You need to provide your JFrog credentials via environment variables or Gradle properties.

On your system, set the following environment variables:

export JFROG_URL_MAVEN=https://thalescpliam.jfrog.io/artifactory/onegini-sdk
export JFROG_TOKEN={YOUR_ARTIFATORY_TOKEN}

Alternatively, you can add them to your gradle.properties file:

JFROG_URL_MAVEN=https://thalescpliam.jfrog.io/artifactory/onegini-sdk
JFROG_TOKEN={YOUR_ARTIFATORY_TOKEN}

1.2 Update build.gradle

Configure the repository in your project's build.gradle file:

repositories {
    google()
    mavenCentral()
    def jfrogUrl = System.getenv("JFROG_URL_MAVEN") ?: project.findProperty("JFROG_URL_MAVEN")
    def jfrogToken = System.getenv("JFROG_TOKEN") ?: project.findProperty("JFROG_TOKEN")

    if (!jfrogUrl || !jfrogToken) {
        throw new GradleException("Missing JFROG configuration! Please provide JFROG_URL_MAVEN and JFROG_TOKEN.")
    }

    maven {
        url = jfrogUrl
        credentials(HttpHeaderCredentials) {
            name = "Authorization"
            value = "Bearer " + jfrogToken
        }
        authentication {
            header(HttpHeaderAuthentication)
        }
    }
}

1.3 Add SDK dependencies

After you configure the repository, add the Mobile FIDO SDK dependencies to your module's build.gradle file:

dependencies {
    implementation "com.thalesgroup.gemalto.fido2:fido2:4.1.0@aar"
    // Optional: Only if you are using the Mobile FIDO UI SDK
    implementation "com.thalesgroup.gemalto.fido2:fido2ui:4.1.0@aar"
}

1.4 (Optional) Download the third-party licenses

The Mobile FIDO SDK is published with a companion bundle that contains the third-party open-source license attributions. It is delivered as a licenses-classifier .zip artifact alongside the SDK in JFrog Artifactory. The bundle is documentation only — it is not required to compile or run the SDK.

If you need it, download the artifact directly from the JFrog Maven repository using the credentials configured in step 1.1 (adjust the version as needed):

curl -H "Authorization: Bearer ${JFROG_TOKEN}" \
  -o fido2-4.1.0-licenses.zip \
  "${JFROG_URL_MAVEN}/com/thalesgroup/gemalto/fido2/fido2/4.1.0/fido2-4.1.0-licenses.zip"

2. Execute Gradle sync

You can either open the sample app in Android Studio, or execute any Gradle task to automatically synchronize and set up all the dependencies.

3. Set up certificate pinning

Place the certificate to pin in your app's resources, for example in the res/raw/ directory.

Load and parse the certificate, then pass it to Fido2Config.setTlsCertificates(...) during your app's initialization:

// Load the pinned certificate bundled with your app (for example, in res/raw)
CertificateFactory certificateFactory = CertificateFactory.getInstance("X.509");
X509Certificate certificate;
try (InputStream inputStream = getResources().openRawResource(R.raw.your_certificate)) {
    certificate = (X509Certificate) certificateFactory.generateCertificate(inputStream);
}

// Configure certificate pinning
Fido2Config.setTlsCertificates(new X509Certificate[]{ certificate });

For more details, refer to certificate-pinning.

4. Set up the configuration fields

Configure the following fields in your project:

• Your public key for the encryption of SDK secure logs: Refer to the instructions to generate this key. The key contains:

  • publicKeyModulus

  • publicKeyExponent

To configure the required information, refer to the Configuration.java file.

5. Build your project

The sample application prompts you to fill in the missing codes. To compile and run the app successfully, refer to the respective use cases to provide the necessary codes.

6. Insert the missing code snippets

Refer to the implementation of the Registration and Authentication class where the section describes the steps within the context of the aforementioned function.

1. Create the Registration and Authentication request providing the required credentials.

   ```java
   val fido2Request = Fido2Request.jsonText(jsonString)
   ```
   

2. Set up Fido2RespondArgs with UI callbacks:

   ```java
   val uiCallback: Fido2UiCallback = SampleFido2UiCallback(activity)
   val passcodeAuthenticatorCallback = SamplePinPadAuthenticatorCallback(activity)
   val biometricAuthenticatorCallback: BiometricAuthenticatorCallback = SampleBiometricAuthenticatorCallback()
   
   val args = Fido2RespondArgs.Builder()
                   .setFido2Request(fido2Request)
                   .setUiCallback(uiCallback)
                   .setPasscodeAuthenticatorCallback(passcodeAuthenticatorCallback)
                   .setBiometricAuthenticatorCallback(biometricAuthenticatorCallback)
                   .build()
   ```
   

3. Retrieve the FIDO2 Registration and Authentication response.

   ```java
       val client = Fido2ClientFactory.createFido2Client(activity.getApplicationContext())
       client.setActivity(activity)
       client.respondWithArgs(args, object : Fido2ResponseCallback {
           override fun onResponded(response: Fido2Response) { 
               passcodeAuthenticatorCallback.dismissPasscodeAuthenticatorDialog()
           listener?.onSuccess(response) 
           }
           override fun onError(exception: Fido2Exception) {
               passcodeAuthenticatorCallback.dismissPasscodeAuthenticatorDialog()
               listener?.onError(exception)
   }       
       })
   ```
   

7. Set up hybrid authentication

If your app supports hybrid authentication (cross-device authentication), you MUST configure the Credential Provider components in your AndroidManifest.xml and provide the necessary configuration files.

For detailed setup instructions, refer to the Android hybrid transport setup page.

For more information about implementing hybrid authentication, see the hybrid transport documentation.

8. Successful setup

You can run and explore the features of Mobile FIDO SDK now.