Orchestration SDKs

Preparing Advanced Identity Cloud or PingAM for FIDO on Android

PingOne Advanced Identity Cloud PingAM Android

To use FIDO authentication in your Android apps when using Advanced Identity Cloud or PingAM you must complete the following tasks:

Step 1. Generating Android signing key fingerprints

You need to generate signing key fingerprints so that you can create a secure, verifiable link between your server and your native Android app.

This prevents malicious apps from impersonating your official app to register or use FIDO credentials.

You need two different formats of fingerprint:

Generating SHA-256 fingerprints of your Android signing certificates

You can use SHA-256 fingerprints of the certificates you use to sign your Android applications to ensure that FIDO only works with apps you’ve signed.

The steps for obtaining the fingerprint depend on the method you use to distribute your application.

  • Android App Bundles

  • Local debug keys

If you are using Android App Bundles to distribute your apps, then the hashes of the certificate used to sign your application are available in the Android Developer console.

Follow these steps to obtain the SHA-256 hash of your signing certificate:

  1. Configure your Android App Bundle for signing. Google has a number of methods for managing the signing certificates, including uploading your own or having Google manage them for you.

    For information on how to set up signing, refer to Sign your app in the Google Developer Documentation.

  2. In the Google Play Console:

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

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

      android signing certificates en
      Figure 1. App signing keys in the Google Play Console

    3. In the App signing key certificate section, copy the SHA-256 certificate fingerprint value.

      In the Digital Asset Links JSON section is a file that you can copy with the SHA-256 fingerprint already in place.

You must manually generate a SHA-256 fingerprint of your signing key in the following scenarios:

  • You are signing your APK with the default debug.jks that Android Studio created for the project

  • You are signing your APK with your own keys that you have generated that have not been uploaded to the Google Play Console

Follow these steps to obtain the SHA-256 hash of your signing certificate:

  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 -list -v -alias <keyAlias> -keystore <storeFile> | grep SHA256

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

    keytool -list -v -alias "androiddebugkey" -keystore "./debug.jks" | grep SHA256

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

    The default keystore password for certificates in the local debug JKS file is android.

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

    Enter keystore password:  android
SHA256: E6:5A:5D:37:22:FC...22:99:20:03:E6:47
Signature algorithm name: SHA256withRSA

Generating base64-encoded SHA-256 fingerprints of your Android signing certificates

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-encoded 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

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 default keystore password for certificates in the local debug JKS file is android.

    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

In this step you create a Digital Asset Links JSON file that allows your website to make a public, verifiable statement about its relationship with other assets, such as your Android app.

To associate your server with your Android app you need to make public, verifiable statements by using a Digital Asset Links JSON file (assetlinks.json).

Create or update an assetlinks.json with the SHA-256 fingerprint value you generated in the previous step:

Example assetlinks.json file
[
    {
        "relation": [
            "delegate_permission/common.handle_all_urls",
            "delegate_permission/common.get_login_creds"
        ],
        "target": {
            "namespace": "android_app",
            "package_name": "com.example.app",
            "sha256_cert_fingerprints": [
                "E6:5A:5D:37:22:FC...22:99:20:03:E6:47"
            ]
        }
    }
]

For more information on creating an assetlinks.json file, refer to Google Digital Asset Links.

  • For PingOne Advanced Identity Cloud deployments, refer to Upload an Android assetlinks.json file.

  • For self-managed PingAM deployments, host the file at https://<your domain>/.well-known/assetlinks.json.

Step 3. Configuring authentication journeys for FIDO on Android

Authentication journeys for FIDO primarily use these nodes:

WebAuthn Registration Node

Handles the creation and storage of new passkeys.

WebAuthn Authentication Node

Manages the sign-in process by issuing and verifying challenges.

Learn more about creating authentication journeys for FIDO in Journeys for WebAuthn.

To prepare your authentication journeys to use FIDO with an Android application, you need to configure each WebAuthn Registration node and WebAuthn Authentication node in your authentication journey to work with your Android app.

You must use the same configuration values in each WebAuthn Registration node and WebAuthn Authentication node in the journey.

Any mismatches in configuration between these nodes will cause authentication to fail.
Each WebAuthn Registration node and WebAuthn Authentication node

  1. In Origin domains, enter the base64-encoded SHA-256 fingerprint value you obtained previously.

    For example, android:apk-key-hash:jEFEYh80...S5Pj-ZKHHjwi0k.

  2. 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.

  3. In Relying party identifier, enter the domain hosting the assetlinks.json file you create and uploaded.

    For example, openam-docs.forgeblocks.com

    You do not need the protocol or the path.

Every WebAuthn Registration node

  1. In Accepted signing algorithms, include one or more of ES256 and RS256.

  2. Ensure the Limit registrations option is not enabled.

The result will resemble the following:

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

Next steps

You can now proceed to Integrating FIDO auth journeys in Android.