Managing Google Play App Signing Key Upgrades in TWAs

When publishing a Trusted Web Activity (TWA) on the Google Play Store, managing cryptographic keys is a critical task. Google Play App Signing is a service where Google manages and protects your app signing key, using it to sign your Android App Bundle (AAB) for distribution. While this system offers security benefits and allows for seamless delivery optimisations, it introduces specific complexities for TWA developers. Because a TWA relies on Digital Asset Links to establish a secure handshake between the web origin and the Android wrapper, any change to your application signing keys can instantly break this verification, resulting in the fallback Chrome URL bar appearing inside your installed app.

Understanding the Key Architecture in Google Play

Before initiating a key upgrade, it is vital to understand the difference between the keys used in the Google Play Console. When Google Play App Signing is enabled, your app development workflow involves two distinct cryptographic keys: the upload key and the app signing key. The following table highlights the distinct roles of these two keys:

Historically, many developers used legacy keys with weaker cryptographic strength, such as 1024-bit RSA keys, or keys generated using outdated signature schemes. Google Play allows developers to upgrade their app signing keys to modern, cryptographically stronger keys (such as 2048-bit or stronger RSA keys with updated signature algorithms). However, because the app signing key is the exact certificate that defines your app identity on user devices, upgrading it changes the SHA-256 fingerprint of your distributed app.

The Core TWA Challenge with Key Upgrades

The security model of a Trusted Web Activity is binary: either the digital relationship between the app package and the website is verified, or it is not. When a user launches your TWA, the underlying rendering engine (typically Google Chrome) downloads the assetlinks.json file located at your web origin under the .well-known/ directory. The browser extracts the package name and the SHA-256 fingerprint of the signature from the installed application on the device and compares it to the array of allowed signatures in your online JSON file.

If you upgrade your app signing key in the Google Play Console, Google will begin signing your updates with a new key. Users who receive this update will have an app signed with the new fingerprint. If your web server only lists the old fingerprint, the browser will fail the Digital Asset Links validation. Consequently, your users will suddenly see a standard web browser address bar at the top of their application, ruining the immersive native-like experience.

Step-by-Step Guide to Upgrading Your Key Safely

To perform a key upgrade without causing service interruptions or displaying the URL bar to your active user base, you must follow a precise sequence of actions. This ensures that both legacy and upgraded installations remain verified simultaneously during the transition period.

Step 1: Retrieve the New App Signing Key Fingerprint

Before committing to the upgrade in the Google Play Console, you must obtain the new SHA-256 fingerprint that Google will use. Navigate to your Google Play Console, select your application, and head to the Setup section, then click on App Signing. When you request a key upgrade, Google will present you with the new certificate details. Copy the new SHA-256 fingerprint precisely. It consists of a long string of hexadecimal characters separated by colons.

Step 2: Update Your Asset Links File on the Web Server

Do not wait for the app update to release before modifying your server configuration. The assetlinks.json file must be updated first. Because the Asset Links specification allows you to list multiple valid signatures for a single package name, you can support both your old and new keys at the exact same time. Update the file at https://yourdomain.com/.well-known/assetlinks.json to include both statements. The file structure should look like this:

[ { "relation": ["delegate_permission/common.handle_all_urls"], "target": { "namespace": "android_app", "package_name": "com.example.twa", "sha256_cert_fingerprints": [ "ORIGINAL_SHA256_FINGERPRINT_HERE", "NEW_UPGRADED_SHA256_FINGERPRINT_HERE" ] } } ]

By declaring both fingerprints inside the sha256_cert_fingerprints array, you ensure that existing users running older versions of your app (signed with the old key) and new users running the upgraded version (signed with the new key) will pass validation without issue.

Step 3: Confirm Server Caching and Deployment

Ensure that your web server does not serve old cached versions of the assetlinks.json file. Set the HTTP caching headers for this file to a very low max-age, or disable caching for it entirely (e.g., using Cache-Control: no-cache). You can verify that your server is serving the correct, updated JSON by querying it directly in a browser or using command-line tools like curl. Verify that both SHA-256 fingerprints are visible to external networks.

Step 4: Execute the Key Upgrade in the Google Play Console

Once you have confirmed that your web server is successfully serving both fingerprints, return to the Google Play Console and complete the key upgrade process. Google will register the upgrade. The next time you build and upload an Android App Bundle (AAB) to Google Play, Google will sign the delivered APKs with the new, cryptographically secure key.

Managing Upload Key Rotations

While an app signing key upgrade is a deliberate security decision, you might also find yourself needing to reset or rotate your upload key. This usually happens if you lose your local keystore file, forget the keystore password, or suspect that your private developer key has been compromised. Fortunately, because Google Play App Signing is active, rotating an upload key is straightforward and does not affect your Digital Asset Links validation.

To reset your upload key, you must generate a new upload key locally using standard command-line tools like keytool, export the certificate to a PEM file, and contact Google Play support through the Console request form. Once Google registers your new upload key, you will use it to sign your AABs locally. Because Google still signs the distributed APKs with your primary app signing key, your users are completely unaffected, and you do not need to make any changes to your assetlinks.json file for an upload key reset.

Verifying the Migration

To guarantee that your key upgrade was successful, monitor your app performance and user interface closely. You can deploy the newly signed AAB to an internal testing track in the Google Play Console first. Install the app on a test device from the Play Store and verify that the application launches smoothly in full-screen mode without the Chrome URL bar. Additionally, you can inspect the device logs using ADB (Android Debug Bridge) to confirm that the verification status returns a success code from the local browser engine.