Why do we need the client certificate's SHA-256 for Passkey to work?

Technical Background: Digital Asset Links (DAL)

Passkey on Android uses the Digital Asset Links protocol to establish a verifiable and secure association between the client's native application and Unico's web domain. This link is mandatory by the Android operating system's design for authentication with passkeys in Google mobile applications.

How Security Verification Works

Before generating a key pair for a passkey, the Android authenticator verifies the Relying Party ID (RP ID) present in the server's response against the domain name specified in the Digital Asset Links file. Without this successful verification, Passkey simply will not work.

What is SHA-256 and why is it necessary?

The SHA-256 fingerprint is a unique hash generated from the application's signing certificate, used to identify the app's authenticity and integrity.

This certificate corresponds to the key used to sign the APK/AAB before distribution on the Google Play Store.

It is necessary to register this fingerprint in the assetlinks.json file hosted on Unico's domain under the path /.well-known/assetlinks.json

Structure of the assetlinks.json file

The file must include two specific permissions: delegate_permission/common.handle_all_urls (for Android App Links) and delegate_permission/common.get_login_creds (for sharing credentials between the website and the Android app), along with the client's package name and SHA-256 fingerprint.

Why do we request this information?

• Different data for debug vs. production: The fingerprints associated with the signing and upload keys are different. It is important to have this clear distinction, especially considering that apps can have multiple versions (debug, release, different product flavors).

• Total blockage: The server needs to know about the client's app in two different places: in the publicly available file (assetlinks.json) and in the server configuration (expected origin). Without the correct SHA-256, no passkey operation will work.

How to obtain the SHA-256

It is possible to extract the SHA-256 fingerprint using the Java Development Kit (JDK) keytool tool or find it directly in the Google Play Console in the "App Signing" section under "Setup > App integrity".

Conclusion

The SHA-256 is not just a technical requirement—it is a fundamental Android security mechanism to ensure that only the legitimate client application can create and use passkeys associated with Unico's domain. Without it, there is no way to establish the necessary trust between the app and the server, making it impossible to activate the Passkey functionality for that client.