Orchestration SDKs

Preparing Advanced Identity Cloud or PingAM for FIDO in React Native

PingOne Advanced Identity Cloud PingAM React Native

Before enabling FIDO authentication in your React Native apps you must configure your server and, depending on the platforms you support, prepare your Android or iOS apps.

Preparing your Android app for FIDO

Complete the following steps to prepare your Android app for FIDO authentication:

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.

Preparing your iOS app for FIDO

Complete the following step to prepare your iOS app for FIDO authentication:

Step 1. Associating your iOS app with your Advanced Identity Cloud or PingAM server

Create an apple-app-site-association file that establishes a secure association between your domain and your iOS app.

This allows you to share credentials and use universal links to open your app from your website.

To create the secure association, upload the apple-app-site-association file to your domain, and add matching Associated Domains Entitlement keys to your app.

Preparing a site association file

  1. Prepare a JSON-formatted file named apple-app-site-association, as shown below.

    Ensure you include the webcredentials entitlement

    {
  "applinks": {
    "details": [
      {
        "appIDs": [
          "XXXXXXXXXX.com.example.AppName"
        ],
        "components": [
          {
            "/": "/reset/*",
            "comment": "Success after reset password journey"
          }
        ]
      }
    ]
  },
  "webcredentials": {
    "apps": [
      "XXXXXXXXXX.com.example.AppName"
    ]
  }
}

  2. Replace XXXXXXXXXX.com.example.AppName with the app ID of your client iOS application.

Learn more in Supporting associated domains in the Apple Developer documentation.

Hosting apple-app-site-association files in Advanced Identity Cloud or PingAM

Configuring authentication journeys for FIDO

This step applies to both Android and iOS.

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 a React Native application, you need to configure each WebAuthn Registration node and WebAuthn Authentication node in your authentication journey to work with your React Native 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 URL where you host your React Native app.

    For example, https://app.example.com.

    If you leave Origin domains empty, the server uses the origin of incoming requests as an accepted origin.
Each 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.

Next steps

You can now proceed to Integrating FIDO auth journeys in React Native.