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.

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

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.0.0")
  implementation("com.pingidentity.sdks:mfa:fido:2.0.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.0.0")
  implementation("com.pingidentity.sdks:fido:2.0.0")
  implementation("androidx.credentials:credentials-play-services-auth:1.5.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.0.0")
  implementation("com.pingidentity.sdks:fido:2.0.0")
  implementation("androidx.credentials:credentials-play-services-auth:1.5.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 DaVinci flow
          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 DaVinci flow
          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 FIDO 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 FIDO API
  onPublicKeyCredentialRequestOptions { originalOptions ->
    originalOptions.toBuilder()
      .setTimeoutSeconds(30.0) // Example: change timeout
      .build()
  }
}