Ping SDKs

Configure biometric authentication journeys

To use mobile biometrics with the Ping SDK for Android configure the authentication nodes in your journeys as follows:

  1. In each WebAuthn Registration node and WebAuthn Authentication node:

    • Ensure the Return challenge as JavaScript option is not enabled

      The SDK expects a JSON response from these nodes, enabling this option would cause the journey to fail

    • Set the Relying party identifier option to be the domain hosting the assetlinks.json file

      For example, openam-docs.forgeblocks.com

      You do not need the protocol or the path.

  2. In each WebAuthn Registration node

    • Set the Authentication attachment option to either UNSPECIFIED or PLATFORM

    • Ensure the Accepted signing algorithms option includes either ES256 or RS256

    • Ensure the Limit registrations option is not enabled

Configure origin domains

To enable WebAuthn on Android devices, you must configure the nodes with the base64-encoded SHA-256 hash of the signing certificate as the origin domain.

The steps for obtaining the base64-encoded SHA-256 hash depend on the method you use to distribute your application.

  • Android App Bundles

  • Local debug keys

Follow these steps to download the app signing certificate, and then generate a base64-encoded SHA-256 hash:

  1. In the Google Play Console:

    1. Select the app that will be supporting mobile biometrics.

    2. Navigate to Setup > App integrity > App signing.

    3. In the App signing key certificate section, click Download certificate.

      This downloads a local copy of the signing certificate, named deployment_cert.der.

  2. In a terminal window, navigate to the location of the deployment_cert.der file, and then run the following command:

    cat deployment_cert.der | openssl sha256 -binary | openssl base64 | tr '/+' '_-' | tr -d '='

    The command prints the base64-encode SHA-256 fingerprint of the signing key:

    jEFEYh80K55iHYkxsBRLGtAP6wvjOS5Pj-ZKHHjwi0k
  3. Add a prefix of android:apk-key-hash: to the base64-encode SHA-256 fingerprint. For example:

    android:apk-key-hash:jEFEYh80K55iHYkxsBRLGtAP6wvjOS5Pj-ZKHHjwi0k
  4. In each WebAuthn Registration node and WebAuthn Authentication node, set the Origin domains option to the value created in the previous step:

    android webauthn node config en
    Figure 1. Example WebAuthn Registration node configuration

Follow these steps to extract the app signing certificate from the JKS and generate a base64-encoded SHA-256 hash:

  1. In the build.gradle file for your application, check the settings defined in the signingConfigs property:

    Example signingConfigs when using the default debug.jks
    signingConfigs {
        debug {
            storeFile file('../debug.jks')
            storePassword 'android'
            keyAlias 'androiddebugkey'
            keyPassword 'android'
        }
    }
  2. In a terminal window, navigate to the location of the JKS file, and then run the following command:

    keytool -exportcert -alias <keyAlias> -keystore <storeFile> | openssl sha256 -binary | openssl base64 | tr '/+' '_-' | tr -d '='

    Swap the <keyAlias> and <storeFile> placeholders with the values you obtained from your project. For example:

    keytool -exportcert -alias "androiddebugkey" -keystore "./debug.jks" | openssl sha256 -binary | openssl base64 | tr '/+' '_-' | tr -d '='

  3. When requested, enter the keystore password, as specified in the keyPassword property in the build.gradle file.

    The command prints the base64-encoded SHA-256 fingerprint of the signing key:

    Enter keystore password:  android
    jEFEYh80K55iHYkxsBRLGtAP6wvjOS5Pj-ZKHHjwi0k
  4. Add a prefix of android:apk-key-hash: to the base64-encode SHA-256 fingerprint. For example:

    android:apk-key-hash:jEFEYh80K55iHYkxsBRLGtAP6wvjOS5Pj-ZKHHjwi0k
  5. In each WebAuthn Registration node and WebAuthn Authentication node, set the Origin domains option to the value created in the previous step:

    android webauthn node config en
    Figure 2. Example WebAuthn Registration node configuration

Summary

You have now configured your WebAuthn journey for use with the Ping SDK for Android.

Copyright © 2010-2024 ForgeRock, all rights reserved.