FIDO in native mobile apps

Airlock IAM supports FIDO/passkey authentication from native Android and iOS apps. This article explains how to configure this.

In FIDO, a website's origin, for example https://login.example.com, identifies the web context that initiated the authentication process. The relying party ID (RP ID) defines the relying party to which a FIDO credential belongs. For example, a website with the origin https://login.example.com may use example.com as its RP ID.

FIDO uses the origin to bind an authentication ceremony to the context that initiated it. For browser-based FIDO authentication, the browser derives the origin from the website URL.

Native apps do not have a browser-derived web origin. Android and iOS therefore use platform-specific mechanisms to associate a native app with the domain used as the FIDO relying party ID. This allows the platform to verify that the app is authorized to use passkeys for that domain.

The association between the native app and the domain specified by the RP ID is configured outside Airlock IAM:

  • Android uses Google Digital Asset Links and the assetlinks.json file.
  • iOS uses Apple Associated Domains and the apple-app-site-association file.

Android additionally uses an app-specific origin of the form android:apk-key-hash:<hash> when communicating with Airlock IAM. This origin identifies the app based on its signing certificate and must be added to the FIDO configuration in IAM.

For iOS, no app-specific origin configuration in IAM is required.

The sections below explain how to configure the native app and IAM to use FIDO. Configuring the native app must be done by the app developers, configuring IAM is done in the Config Editor.

 
Info

For further reading, see Futher information below.

Prerequisites

Before integrating FIDO into a native app:

  • FIDO must be configured in Airlock IAM, including a relying party ID.
    • In the Config Editor, the FIDO Settings plugin defines the global settings related to FIDO
      (Main Settings >> Authentication Settings >> FIDO Settings)
    • The FIDO relying party ID is configured in the plugin's Basic Settings section, Relying Party ID property
  • The native app must have implemented FIDO and support the IAM FIDO registration and authentication flows.
  • The app development team must provide the information required to associate the app with the relying party ID or the origin.
  • The domain corresponding to the relying party ID must provide the platform-specific association file over HTTPS:
    • Android: https://<RP-ID>/.well-known/assetlinks.json
    • iOS: https://<RP-ID>/.well-known/apple-app-site-association

  • <RP-ID> corresponds to the relying party ID as defined in your IAM configuration (FIDO Settings plugin >> Relying Party ID property).

  • The above association files are provided by the owner of the domain, not by Airlock IAM. They may also contain entries for functionality unrelated to IAM or FIDO.

Configure the native app and domain

Android:

  1. Configure the Android app for FIDO authentication using the relying party ID defined in IAM.
  2. Determine the SHA-256 fingerprint of the certificate used to sign the distributed app.
  3. Add the app's signing-certificate fingerprint to the assetlinks.json file:
  4.  
    Example
    "sha256_cert_fingerprints": [
   "74:E4:71:84:FF:47:9E:A1:25:E0:7B:96:E6:50:C2:5C:D0:0E:E0:65:04:82:36:08:98:7D:39:FE:3F:44:B5:07"
]
  5.  
    Notice

    When using Google Play App Signing, use the fingerprint of the app signing key, not the upload key.

iOS:

  1. Configure the app to use the IAM relying party ID as an associated domain.
  2. Add the app to the “webcredentials” section of the apple-app-site-association file.
    The “apps” entry consists of the Apple team ID and the application's bundle ID, for example:
  3.  
    Example
    "webcredentials": {   
 "apps": [     
  "ABCDE12345.com.example.myapp"  
 ] 
}

Configure IAM

No additional origin configuration in IAM is required for iOS.

For Android, an app-specific origin derived from the app's signing certificate must be registered as an additional allowed FIDO origin. Android identifies the native app using an origin of the following form:
android:apk-key-hash:<key-hash>

Airlock IAM must explicitly allow this origin.

Proceed as follows:

  1. Obtain the SHA-256 fingerprint of the certificate used to sign the Android app.
  2. Determine the APK key hash value out of the signing certificate fingerprint. You can obtain the APK key hash in either of the following ways:
    • Convert the hexadecimal SHA-256 fingerprint to its raw byte representation, then encode those bytes using Base64URL without padding. As a result, you get the APK key hash.
    • Alternatively, obtain the APK key hash from the Airlock IAM DEBUG logs. Before configuring the native app's Android origin in IAM, initiate a FIDO request from the app. Because the app-specific origin is not yet configured as an allowed origin, IAM logs the failed origin comparison at DEBUG level. Look for a message similar to:
      No match: android:apk-key-hash:<key-hash> != https://
      The value shown as <key-hash> is the APK key hash.
  4. In the Config Editor, go to:
    Main Settings >> Authentication Settings >> FIDO Settings
  5. In the Basic Settings section, in the Additional Origins field, add a FIDO Android App Origin plugin.
    In the APK Key Hash field of this plugin, enter the APK key hash value previously obtained from the signing certificate fingerprint.

  6. Example:

  7. Certificate fingerprint:
    74:E4:71:84:FF:47:9E:A1:25:E0:7B:96:E6:50:C2:5C:D0:0E:E0:65:04:82:36:08:98:7D:39:FE:3F:44:B5:07

  8. Obtained APK key hash after convertion:
    dORxhP9HnqEl4HuW5lDCXNAO4GUEgjYImH05_j9EtQc

  9. Enter the latter value in the APK Key Hash field.

  10.  
    Notice

    Only the variable <key-hash> value is required. Airlock IAM adds the android:apk-key-hash: prefix automatically.

Further considerations

  • FIDO registration and authentication must be configured both in IAM and the native app. Changes to the configured FIDO flows in IAM may therefore require corresponding changes in the app and should be tested together.
  • The Android certificate fingerprint normally remains unchanged between app releases as long as the same app signing key is used. If the signing key changes, both the assetlinks.json file and the corresponding configuration in IAM must be updated.
  • Apps distributed through multiple channels may use different signing certificates. Each Android app origin that is intended to work with FIDO must be represented by the appropriate certificate fingerprint and added as additional origin to the IAM configuration (see the instructions above).
    Debug signing keys should normally not be allowed in production configurations.
  • The association files assetlinks.json (Android) and apple-app-site-association (iOS) are owned by the relying party ID domain, and may contain entries for other applications and functionality. Their content and deployment must be coordinated between the app development team and the domain operators, not by IAM.

Futher information

IAM

Apple / iOS

Google / Android