Orchestration SDKs

Integrating FIDO auth journeys in Android

PingOne Advanced Identity Cloud PingAM Android

The FIDO module offers a streamlined API for handling FIDO interactions, including registering and authenticating with passkeys.

It abstracts away the complexities of the underlying FIDO protocols, allowing you to quickly add strong authentication to your applications.

For an example of the journeys you can build with this module, see the sample passkey journey.

Before you begin

Ensure you have prepared your server for FIDO authentication in Android apps before attempting the steps on this page.

Step 1. Installing modules

To add FIDO to your Android apps you need this module:

  • fido

To install the module into your Android app:

  1. In the Project tree view of your Android Studio project, open the build.gradle.kts file.

  2. In the dependencies section, add the fido module as a dependency:

    dependencies {
  implementation("com.pingidentity.sdks:journey:2.1.0")
  implementation("com.pingidentity.sdks:fido:2.1.0")
}

  3. Optionally, if your application needs to support devices running Android API 33 (Android 13) and older, add the Credentials Play Services Auth dependency to ensure proper FIDO functionality:

    dependencies {
  implementation("com.pingidentity.sdks:journey:2.1.0")
  implementation("com.pingidentity.sdks:fido:2.1.0")
  implementation("androidx.credentials:credentials-play-services-auth:1.6.0")
}

    Adding this dependency ensures maximum backwards compatibility:

    • Android Credential Manager requires additional support libraries for API 33 and below

    • It provides backward compatibility for FIDO authentication on older Android versions

  4. Optionally, if your application needs to support non-discoverable FIDO credentials or physical security keys, add the Play Services FIDO dependency:

    dependencies {
  implementation("com.pingidentity.sdks:journey:2.1.0")
  implementation("com.pingidentity.sdks:fido:2.1.0")
  implementation("androidx.credentials:credentials-play-services-auth:1.6.0")
  implementation("com.google.android.gms:play-services-fido:XX.X.X")
}

    Adding this dependency ensures maximum compatibility with FIDO credentials:

    • Supports non-discoverable FIDO credentials

    • Compatible with legacy FIDO implementations that require Play Services

Remember to synchronize your Gradle project after adding dependencies.

Step 2. Registering FIDO authenticators

To register a FIDO authenticator, use the register() function. The function returns either Success or Failure.

The Orchestration SDK provides the FidoRegistrationCallback class for handling the FIDO registration requests.

Registering a FIDO authenticator in a Advanced Identity Cloud or PingAM journey
if (node is ContinueNode) {
  node.callbacks.forEach { callback ->
    if (callback is FidoRegistrationCallback) {
      when (val result = callback.register()) {
        is Success -> {
          // Registration successful, proceed to the next step in the journey
          node = node.next()
          // Process the next node
        }
        is Failure -> {
          // Registration failed, handle the error
          val error: Throwable = result.error
          // Log or display the error message
        }
      }
    }
  }
}

Step 3. Authenticating using a FIDO authenticator

To authenticate using a registered FIDO authenticator, use the authenticate() function. The function returns either Success or Failure.

The Orchestration SDK provides the FidoAuthenticationCallback class for handling the FIDO authentication requests:

Authenticating with a FIDO authenticator in a Advanced Identity Cloud or PingAM journey
if (node is ContinueNode) {
  node.callbacks.forEach { callback ->
    if (callback is FidoAuthenticationCallback) {
      when (val result = callback.authenticate()) {
        is Success -> {
          // Authentication successful, proceed to the next step in the journey
          node = node.next()
          // Process the next node
        }
        is Failure -> {
          // Authentication failed, handle the error
          val error: Throwable = result.error
          // Log or display the error message
        }
      }
    }
  }
}

Customizing credential requests

You can customize the credential request objects you receive during FIDO registration and authentication requests.

This allows you to configure specific options such as timeout values, preferred authenticator types, or immediate availability preferences.

Customizing registration credential requests

You can customize CreatePublicKeyCredentialRequest by providing a lambda to the register() method. Use this method to set preferences such as preferImmediatelyAvailableCredentials during authenticator registration:

Customizing registration credential requests
val result = callback.register {
  onCreatePublicKeyCredentialRequest { originalRequest ->
    // Customize and return a new request
    CreatePublicKeyCredentialRequest(
      requestJson = originalRequest.requestJson,
      preferImmediatelyAvailableCredentials = true
    )
  }
}

Customizing authentication credential requests

You can customize the authentication credential request for both the Credential Manager and Google Play Services FIDO2 API by providing a lambda to the authenticate() method.

The FIDO module automatically uses the appropriate customizer, based on which API you use.

Customizing authentication credential requests
val result = callback.authenticate {
  // Customizer for Android Credential Manager API
  onGetPublicKeyCredentialOption { originalOption ->
    GetPublicKeyCredentialOption(
      requestJson = originalOption.requestJson,
      preferImmediatelyAvailableCredentials = true
    )
  }

  // Customizer for Google Play Services FIDO2 API
  onPublicKeyCredentialRequestOptions { originalOptions ->
    originalOptions.toBuilder()
      .setTimeoutSeconds(30.0) // Example: change timeout
      .build()
  }
}

Selecting the FIDO2 API

Android provides two APIs for performing FIDO authentication, and the Orchestration SDK uses one of them for each authentication call:

The two APIs keep separate credential stores, so a passkey registered through one API is not visible to the other.

By default, the Orchestration SDK selects the API at runtime: it uses the FIDO2 API when Google Play Services is available on the device, and the Credential Manager API otherwise.

You can override the selection for each authentication call by setting useFido2ApiClient in the authenticate() method, as follows:

Selecting the FIDO2 API when using authentication journeys
val result = callback.authenticate {
  useFido2ApiClient = false // Route this call through Credential Manager
}

The following table compares the two APIs:

FIDO2 API Credential Manager

Selected when

useFido2ApiClient = true, or by default when Google Play Services is available

useFido2ApiClient = false, or by default when Google Play Services is unavailable

Credential store

Google Password Manager

The device’s default credential provider, for example Google Password Manager, Samsung Pass, or 1Password

Passkey autofill (conditional mediation)

Not supported

Supported

Non-discoverable, device-bound credentials

Supported

Not supported

Set useFido2ApiClient = false to route the call through Credential Manager when your app needs to support passkey autofill or to honor the device’s default credential provider, such as Samsung Pass.

Set useFido2ApiClient = true when your app uses non-discoverable, device-bound credentials, which only the FIDO2 API supports.