--- title: Preparing Advanced Identity Cloud or PingAM for FIDO on Android description: PingOne Advanced Identity Cloud PingAM Android component: orchsdks page_id: orchsdks:journey:use-cases/fido/android/before-you-begin canonical_url: https://developer.pingidentity.com/orchsdks/journey/use-cases/fido/android/before-you-begin.html revdate: Fri, 13 May 2022 09:39:02 +0200 section_ids: android-fingerprints: Step 1. Generating Android signing key fingerprints sha256-fingerprint: Generating SHA-256 fingerprints of your Android signing certificates base64-sha256-fingerprint: Generating base64-encoded SHA-256 fingerprints of your Android signing certificates android-assetlinks: Step 2. Associating your Android app with your Advanced Identity Cloud or PingAM server creating_a_digital_asset_links_json_file: Creating a Digital Asset Links JSON file hosting_assetlinks_json_in_advanced_identity_cloud_or_pingam: Hosting assetlinks.json in Advanced Identity Cloud or PingAM android-fido-journeys: Step 3. Configuring authentication journeys for FIDO on Android next_steps: Next steps --- # Preparing Advanced Identity Cloud or PingAM for FIDO on Android [icon: circle-check, set=far]PingOne Advanced Identity Cloud [icon: circle-check, set=far]PingAM [icon: android, set=fab]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](#android-fingerprints) * [Step 2. Associating your Android app with your Advanced Identity Cloud or PingAM server](#android-assetlinks) * [Step 3. Configuring authentication journeys for FIDO on Android](#android-fido-journeys) ## 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: * [SHA-256 fingerprint](#sha256-fingerprint) For example, `E6:5A:5D:37:22:FC...22:99:20:03:E6:47` * [Base64-encoded SHA-256 fingerprint](#base64-sha256-fingerprint) For example, `android:apk-key-hash:jEFEYh80...S5Pj-ZKHHjwi0k` ### 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](https://developer.android.com/studio/publish/app-signing) in the Google Developer Documentation. 2. In the [Google Play Console](https://play.google.com/console): 1. Select the app that will be supporting mobile biometrics. 2. Navigate to Setup > App integrity > App signing. ![android signing certificates en](../../../../_images/android/android-signing-certificates-en.png)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 ```gradle 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: ```shell keytool -list -v -alias -keystore | grep SHA256 ``` | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Swap the *\* and *\* 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: ```shell 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](https://play.google.com/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: ```shell 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: ```shell jEFEYh80K55iHYkxsBRLGtAP6wvjOS5Pj-ZKHHjwi0k ``` 3. Add a prefix of `android:apk-key-hash:` to the base64-encode SHA-256 fingerprint. For example: ```shell 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 ```gradle 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: ```shell keytool -exportcert -alias -keystore | openssl sha256 -binary | openssl base64 | tr '/+' '_-' | tr -d '=' ``` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | Swap the *\* and *\* 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: ```shell Enter keystore password: android jEFEYh80K55iHYkxsBRLGtAP6wvjOS5Pj-ZKHHjwi0k ``` 4. Add a prefix of `android:apk-key-hash:` to the base64-encode SHA-256 fingerprint. For example: ```shell android:apk-key-hash:jEFEYh80K55iHYkxsBRLGtAP6wvjOS5Pj-ZKHHjwi0k ``` ## Step 2. Associating your Android app with your Advanced Identity Cloud or PingAM server 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. ### Creating a Digital Asset Links JSON file 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 ```json [ { "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](https://developers.google.com/digital-asset-links/v1/getting-started). ### Hosting assetlinks.json in Advanced Identity Cloud or PingAM * For **PingOne Advanced Identity Cloud** deployments, refer to [Upload an Android assetlinks.json file](https://docs.pingidentity.com/pingoneaic/latest/end-user/upload-android-assetlinks.html). * For self-managed **PingAM** deployments, host the file at `https:///.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](https://docs.pingidentity.com/pingoneaic/latest/am-authentication/authn-mfa-webauthn.html#authn-mfa-web-authn). 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](../../../../_images/android/android-webauthn-node-config-en.png)Figure 2. Example WebAuthn Registration node configuration ## Next steps You can now proceed to [Integrating FIDO auth journeys in Android](android-fido-auth-journey.html).