Orchestration SDKs

Preparing PingOne for FIDO on Android

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 FIDO implementations on Android, you need to upload your assetlinks.json file to a specific location on the web server that corresponds to your Relying Party (RP) ID.

Upload the file so your server makes it accessible at a URL similar to the following example:

https://<your-RP-domain>/.well-known/assetlinks.json

When you configure your server, follow these key requirements:

  • Ensure <your-RP-domain> in the URL exactly matches the RP ID you configure in your DaVinci flows in a later step.

  • Serve the file exclusively over an HTTPS connection.

  • Set the Content-Type HTTP header to application/json when serving the file.

  • Serve the file directly from the URL without any redirects. Android won’t follow redirects when it verifies the file.

Step 3. Configuring a FIDO policy in PingOne

A FIDO policy defines which FIDO devices are permitted and the desired behavior when registering and authenticating your users.

You can create a new FIDO policy, or update an existing FIDO policy to suit your requirements. The default Passkeys FIDO policy is a great starting point for use with the FIDO module:

p1 fido policy
Figure 2. The default Passkeys FIDO policy in PingOne

To create or edit a FIDO policy:

  1. In the PingOne admin console, go to Authentication > FIDO.

  2. Click the Plus icon () to create a new FIDO policy, or select an existing policy and then click the Pencil icon () to edit it.

  3. Configure the FIDO policy as required. Learn more about Adding a FIDO policy in the PingOne documentation.

  4. Save your changes.

  5. To set the policy as the default, click the More Options icon (), and then click Make Default.

    pingone fido policy make default
    Figure 3. Setting the default FIDO policy in PingOne

Make a note of your FIDO policy name, you’ll need it in Step 4. Adding a FIDO policy to an MFA policy in PingOne.

Step 4. Adding a FIDO policy to an MFA policy in PingOne

After configuring a FIDO policy you must include it in an MFA policy, alongside any other MFA methods you want to enable.

  1. In the PingOne admin console, go to Authentication > MFA.

  2. Click the Plus icon () to create a new MFA policy, or select an existing policy and then click the Pencil icon () to edit it.

  3. In Allowed Authentication Methods, enable FIDO2.

    Learn more about Configuring an MFA policy for strong authentication in the PingOne documentation.

  4. In FIDO Policy, select the name of the FIDO policy you created earlier. For example, Passkeys.

  5. Save your changes.

    The result resembles the following:

    p1 mfa policy
    Figure 4. An example MFA policy with selected Passkeys FIDO policy in PingOne

Make a note of your MFA policy name, and the policy ID. You will need these in Step 6. Configuring DaVinci flows for FIDO.

Step 5. Creating FIDO forms in PingOne

You need to create two sets of PingOne forms—​one set for FIDO registration, and one set for FIDO authentication.

Each set requires a form to list the device types available for the operation, and another form to handle the actual FIDO operation.

Creating forms to list MFA devices in PingOne

To configure a form to list the methods available for FIDO registration:

  1. In the PingOne admin console, go to User Experience > Forms.

  2. Click the Plus icon (), enter a Form Name and optionally a Form Description, and then click Add Form.

    A dialog containing a list of starter templates appears.

  3. In the list of templates, select MFA Device Selection - Registration.

  4. (Optional) Customize the form in the form builder.

  5. Click Save.

    The result resembles the following:

    p1 forms fido device list registration
    Figure 5. PingOne form to list MFA devices for registration

To configure a form to list the methods available for FIDO authentication:

  1. In the PingOne admin console, go to User Experience > Forms.

  2. Click the icon and select the MFA Device Selection - - Authentication template.

  3. (Optional) Customize the templated form in the form builder.

  4. Click Save.

    The result resembles the following:

    p1 forms fido device list authentication
    Figure 6. PingOne form to list MFA devices for authentication

Creating forms to initiate FIDO operations in PingOne

To create a form in PingOne to initiate FIDO operations for registration, complete the following steps:

  1. In the PingOne admin console, go to User Experience > Forms.

  2. Click the icon and select the FIDO2 - Registration template.

  3. (Optional) Customize the templated form in the form builder.

  4. Click Save.

    The result resembles the following:

    p1 forms fido registration
    Figure 7. PingOne form to initialize FIDO for registration

To create a form in PingOne to initiate FIDO operations for authentication, complete the following steps:

  1. In the PingOne admin console, go to User Experience > Forms.

  2. Click the icon and select the FIDO2 - Authentication template.

  3. (Optional) Customize the templated form in the form builder.

  4. Click Save.

    The result resembles the following:

    p1 forms fido authentication
    Figure 8. PingOne form to initialize FIDO for authentication

Step 6. Configuring DaVinci flows for FIDO

You’ll need a DaVinci flow for both registering a FIDO device, and authenticating with a FIDO device.

Each flow will need to display the appropriate device selection form you created earlier, as well as the FIDO initiation form.

Configuring a FIDO registration DaVinci flow

In DaVinci, create or edit a FIDO registration flow, and configure it as follows:

  1. In the DaVinci flow, add connectors to allow the user to select the MFA device type to register:

    1. Add a Form Connector, and configure it to display the form that lists MFA devices for registration as follows:

      1. Using the Show Form capability, in the Form field, select the form that lists MFA devices for registration that you created in a previous step.

      2. In Authentication Method Source, select the MFA policy that you added your FIDO2 policy to in a previous step.

      The result should resemble the following:

      p1 flow fido show device reg config
      Figure 9. Configuring a PingOne Forms connector for FIDO

    2. Add a Functions connector to handle the device selection, including a FIDO2 condition.

      The result should resemble the following:

      p1 flow fido2 device selection nodes
      Figure 10. Example connectors for selecting the FIDO device to register

  2. Connect the FIDO2 condition to a section of the flow with connectors to register a FIDO2 device:

    1. Add a PingOne MFA connector node and select the Create Device capability. (1)

      This connector supplies the Public Key Credential Creation field to the following Form connector.

    2. In a subsequent node, add a Form connector and select the Show Form capability, then select the FIDO2 registration form you created in a previous step. (2)

      Select the FIDO registration initiation form, not the form you created to list the MFA devices available for registration.

    3. In a subsequent node, add another PingOne MFA node and select the Activate Device capability. (3)

      The result should resemble the following:

      A DaVinci FIDO2 MFA flow. The first Form connector is set to Create Device Authentication, followed by a Form connector using Show Form with FIDO2 Authentication selected. The final Form connector is set to FIDO Assertion.
      Figure 11. Example FIDO registration DaVinci flow connectors.

  3. Add the signing key hash you generated earlier to the Origin property of the Activate Device capability:

    1. Select the PingOne MFA node with the Activate Device capability.

    2. On the General tab, in the Origin field, add the signing key hash you created earlier.

      For example, android:apk-key-hash:jEFEYh80K55iHYkxsBRLGtAP6wvjOS5Pj-ZKHHjwi0k

  4. Save and deploy your changes.

Configuring a FIDO authentication DaVinci flow

In DaVinci, create or edit a FIDO authentication flow, and configure it as follows:

  1. In the DaVinci flow, add connectors to allow the user to select the MFA device type to authenticate with:

    1. Add a Form Connector, and configure it to display the form that lists MFA devices for registration as follows:

      1. Using the Show Form capability, in the Form field, select the form that lists MFA devices for authentication that you created in a previous step.

      2. In Authentication Method Source, select the MFA policy that you added your FIDO2 policy to in a previous step.

      The result should resemble the following:

      p1 flow fido show device auth config
      Figure 12. Configuring a PingOne Forms connector for FIDO

    2. Add a Functions connector to handle the device selection, including a FIDO2 condition.

      The result should resemble the following:

      p1 flow fido2 device selection nodes
      Figure 13. Example connectors for selecting the FIDO device to authenticate with

  2. Connect the FIDO2 condition to a section of the flow with connectors to authenticate with a FIDO2 device:

    1. Add a PingOne MFA connector node and select the Create Device Authentication capability. (1)

      This connector supplies the Public Key Credential Request field to the following Form connector.

      1. Select the PingOne MFA connector node, and on the General tab, in the MFA Policy ID field, enter the ID of the MFA policy you added your FIDO2 policy to in a previous step.

        You must enter the ID of the MFA policy, for example 9db73f8f-eb79-0e60-032e-7ec026262af3, not the name of the policy.

        The result should resemble the following:

        p1 flow fido mfa connector mfa policy
        Figure 14. Adding the MFA Policy ID to a PingOne MFA node, with the Create Device Authentication capability.

    2. In a subsequent node, add a Form connector and select the Show Form capability, then select the FIDO2 authentication form you created in a previous step. (2)

      Select the FIDO authentication initiation form, not the form you created to list the MFA devices available for authentication.

    3. In a subsequent node, add another PingOne MFA connector node and select the FIDO Assertion capability. (3)

      The result should resemble the following:

      A DaVinci FIDO2 MFA flow. The first Form connector is set to Create Device Authentication, followed by a Form connector using Show Form with FIDO2 Authentication selected. The final Form connector is set to FIDO Assertion.
      Figure 15. Example FIDO authentication DaVinci flow connectors.

  3. Add the signing key hash you generated earlier to the Origin property of the FIDO Assertion capability:

    1. Select the PingOne MFA node with the FIDO Assertion capability.

    2. On the General tab, in the Origin field, add the signing key hash you created earlier.

      For example, android:apk-key-hash:jEFEYh80K55iHYkxsBRLGtAP6wvjOS5Pj-ZKHHjwi0k

  4. Save and deploy your changes.

Step 7. Configuring a DaVinci flow to be launched by your app

After configuring a DaVinci flow for use with the Orchestration SDKs you must configure PingOne so that you can launch the flow from the DaVinci module.

This involves performing the following high-level steps:

  1. Checking that your DaVinci flow uses only compatible connectors and fields.

  2. Creating an application in DaVinci to connect PingOne to the DaVinci flow.

  3. Creating an application in PingOne that the DaVinci module can connect to and access the DaVinci application and its PingOne Flow Policy.

To learn how to complete the steps, refer to Launching a flow with a Ping SDK in the DaVinci documentation.

Next steps

You can now proceed to Integrating FIDO DaVinci flows into Android apps.