Support zero-tap sign-in restoration before April 2027

[TimoPtr]

Google has announced that apps supporting user sign-in must support zero-tap sign-in restoration from April 2027 https://support.google.com/googleplay/android-developer/answer/17492799?#zero-tap_sign-in_restoration. This requirement applies to mobile and tablet apps distributed through Google Play that support login, whether optional or mandatory.

They are clear about what happens if we don’t meet the requirements:

Caution

All of the requirements posted in this page are not optional. Not meeting a requirement can affect an app’s visibility and publishing capabilities on Google Play.

For now, they haven’t announced an exception specifically for self-hosted applications. We therefore assume that Home Assistant is affected. Their FAQ states:

Further guidance on exceptions will be provided at a later date.

Acceptance criteria

Google states:

Successful user sign in restoration is determined through the successful restore key retrieval. Apps we identify as not meeting this requirement will be notified.

Hopefully, they will notify us before the April 2027 deadline, although they don’t mention that timing. Let’s look into this before it potentially blocks further releases.

We need to support this flow so users remain signed in to Home Assistant when transferring to a new Android device through device-to-device transfer or cloud backup.

Note

Using Block Store could have helped us, but Google only accepts integrations already in production by September 30, 2026. Given the implementation time and the pace at which Google is reviewing our app, this is not a solution and it would have been only temporary.

Theoretical Simplified restoration flow

Old device

1. After login, or during a subsequent launch while already signed in, the app requests WebAuthn registration options from Home Assistant for a restore credential.
2. The app creates the restore credential through Credential Manager using these options.
3. Credential Manager returns a registration response, including the public key, which the app sends to the server for validation and storage. The private key stays managed by the credential provider.

The credential provider also verifies that the RP ID domain authorizes the app through Digital Asset Links https://web.dev/articles/webauthn-rp-id#android_digital_asset_links.

See Google’s Restore Credentials implementation guide.

Caution

Restore Credentials supports only one account per app https://developer.android.com/identity/sign-in/restore-credentials#apps-multiple, so it cannot restore authentication for all servers configured in the Companion app.

We will need to target the last default server and update the restore credential whenever the default server changes. Other servers would still require re-authentication.

Note

Restore Credentials currently requires Google Play services (GMS), through androidx.credentials:credentials-play-services-auth. This restoration flow would therefore be limited to the full flavor of the Companion app and devices with GMS; it would not be available in the minimal flavor. See Google’s compatibility requirements.

New device

1. The user gets a new phone and starts the migration flow, either from a cloud backup or directly from the old device.
2. The app and its eligible data are restored, including the Room database and shared preferences according to our backup rules. This does not automatically restore a usable authenticated session.
3. The restore credential is transferred separately and becomes available through Credential Manager.
4. On startup—or after background restoration—the app requests a fresh authentication challenge from the Home Assistant server (using the default server URL stored in room) and uses Credential Manager to obtain a signed response using the restore credential.
5. The app sends this response to the server. The server validates it against the public key previously registered for that user and issues a new authenticated session.

Relationship with passkey support

For Home Assistant in general, this restoration flow is very close to passkey support. Both use the same underlying WebAuthn registration and authentication mechanisms, so we should be able to share much of the server-side implementation.

We would still need to distinguish restore credentials from ordinary passkeys and apply the appropriate validation and lifecycle rules. A field such as purpose = restore could express that distinction in our API; it is not a standard WebAuthn field. This is more than simply giving an ordinary passkey a different label, since restoration happens without interactive user verification.

One main challenge we’ve identified for native passkeys is RP ID domain association. It requires an HTTPS verification endpoint on the RP ID domain that is accessible to the verifier. We cannot assume users’ Home Assistant instances have a publicly reachable domain or support HTTPS.

Browsers don’t require this native app association, but they do validate the RP ID against the website’s origin. Browser passkey usage also requires a secure context—normally HTTPS, apart from development exceptions such as localhost. These constraints matter if we want to support both restoration and ordinary passkey login.

This discussion tracks the required Android support and whether we can converge on shared foundations for passkey support in Home Assistant Core.

Open question

How do we achieve these requirements in Home Assistant?

[TimoPtr]

One option worth exploring for the app/domain validation is using my.home-assistant.io as a shared RP ID, hosting only the static association files there for all our users. Authentication would still happen directly between the app and the user’s Home Assistant instance: neither the server URL nor authentication data would need to be sent to My. We’d still need to validate this specifically for Restore Credentials and ensure credentials remain correctly bound to each instance.

However, this might not be a good fit for ordinary passkey login. A passkey scoped to my.home-assistant.io wouldn’t automatically work in a browser visiting the user’s own domain, such as ha.example.com, because browsers enforce the relationship between the website’s origin and the RP ID. So this could address the restoration use case without necessarily providing a suitable shared RP for browser login.

[zweckj]

using my.home-assistant.io as a shared RP ID

this is also a bit of a security concern. Usually PassKeys are clearly segmented per domain/ RP ID - a passkey for site-a.com is not accepted at site-b.com by design. This would allow me to try my passkey on every other instance. Less of a concern if it's restore only and authentication would still fail regardless, but something to keep in mind.

In the current state I would assume that would mean every user ends up with (at least) two separate PassKeys

• my.home-assistant.io - restore
• custom.tld - auth

[TimoPtr]

That is definitely an option, knowing that the restore passkey on Android won't show up other than for the restore scenario according to the Credential Manager.

[seadowg]

Something that's come up when discussing this for other apps is where Google are going to draw the line on "configuration" vs "sign-in". HA allows a user to configure connections to multiple servers (as an app I work on does as well): in this sort of world, the servers can be running different versions of the same product or might be completely different products that just adhere to the same API. Additionally, different devices with the same Play Store account might not actually be intended to have the same set of servers configured. Add to this the fact that CredentialManager/restore key flow only supports one "identity", and the whole thing starts to feel really inappropriate!

It to me seems like Google should make a distinction for apps where I "sign in as me" and ones where you configure it to connect to servers/services. Whether that will happen or not is unclear though, and I don't personally feel optimistic about it 🤷‍♂️.

[TimoPtr]

I cross-posted this topic on multiple open source project with Android apps to see how they are going to handle this new requirements too

• Android zero-tap sign-in restoration: comparing approaches for self-hosted apps immich-app/immich#31433
• Android zero-tap sign-in restoration: comparing approaches for self-hosted apps nextcloud/android#17613
• Android zero-tap sign-in restoration: comparing approaches for self-hosted apps jellyfin/jellyfin-android#2182

And also on Reddit
https://www.reddit.com/r/androiddev/s/6Lvsaz0Se3