Last updated on Nov. 9th 2024. from https://gist.github.com/FID02/48f5130c2151b6d10a04bdfda0cb1c90

This text summarises the usage and compatibility of FIDO security keys on GrapheneOS. It was written by a community member, and is not an official guide by the GrapheneOS project.

This text covers only the usage of physical security keys. Any reference to FIDO and passkeys in this text refers to FIDO in the context of security keys. The usage of passkeys with password managers and cloud services is not covered in this guide.

I have tested FIDO functionality on GrapheneOS and PixelOS over several weeks on multiple Yubikeys of the Security Key series, as well as keys by Token2. It's likely that other security keys will work fine. You can search this forum and the issue tracker for specific models to see if issues have been reported. If you can't find anything, you are also free to ask in the community forum or in the chat rooms.

I have not tested any OTP functionality of security keys. Only FIDO is covered here.

Prerequisites

Sandboxed Google Play is required for practically most FIDO functionality. This is because there is currently no native support for FIDO in the Android Open Source Project (AOSP), which GrapheneOS is based upon. Apps can provide FIDO functionality without Play services if they include a non-Play FIDO library for that, but very few apps do this.[¹] Most apps choose to use the Google Play FIDO library, which depends on Play services. Chromium also has no native FIDO support.[²]

Therefore, this text assumes that you are using Sandboxed Google Play.

To use Sandboxed Google Play, simply go to App Store and install Google Play services. You do not have to grant Play services the Network permission in order for security keys to work.

Passkeys

For passkeys, also called resident keys, your key needs to support the storage of these. The latest firmware (v. 5.7) for the Yubikey 5 and Yubikey Security Key series can store a total of 100 resident keys. The newest model of the Google Titan Security Key (launched Nov. 15, 2023[³]) can store up to 250 resident keys. These are probably the most popular keys on the market. Check with your vendor's customer support if you are unsure whether the key that you intend to obtain can store passkeys. Also, ask them if their key supports deletion and management of passkeys, as not all security keys do.[⁴]

Multi-factor authentication with FIDO2 and U2F

Registration and sign-in works seamlessly, both with USB and NFC, in Vanadium and in apps. No further steps are required.

If your security key functions fine with USB but not NFC, please see the section "PIN and NFC".

FIDO2 passkeys

Passkeys work fully on GrapheneOS, but note the following:

Compatibility with autofill services

On GrapheneOS, it currently does not seem possible to conveniently switch between passkey autofill with a "third-party" autofill service and passkey usage on a security key.

In contrast, when using passkeys on the stock PixelOS, Google Play services serves a dialog that allows you to choose between using passkeys in either a password manager or on an external device such as a security key. It's not clear why this option is currently not displayed with Sandboxed Google Play.

If you are only using passkeys with your security key, this should not pose a problem.

By an "autofill service", I am referring to the service(s) (usually a password manager) that you have configured in the Settings app → Passwords, passkeys & accounts.

By a "third-party" autofill service, I am referring to autofill services other than Vanadium's built-in password manager and Google's Password Manager. Bitwarden and Proton Pass are examples of third-party autofill services.

Note that this does not influence password autofill with these services, which works fine.

Signing in with passkeys

In Vanadium

The setup steps you need to follow here depend on whether or not you are using a third-party autofill service.

When no third-party autofill service is enabled:

Then signing in with passkeys should work without having to change any settings.

When a third-party autofill service is enabled:

You will have to disable the browser's support for passkeys with password managers. This is done by changing an experimental setting:

In the address bar, type chrome://flags and press enter
In the search bar, type passkeys
A setting called "Android Credential Management for passkeys" will appear. Change this setting to "Disabled"
Select "Relaunch"

Again, note that following those steps will disable passkey autofill with password managers. Password autofill should not be affected.

In other apps

A lot of apps simply redirect you to the web browser for passkey authentication, which should not pose any issues if your default browser is Vanadium and you have followed the steps in the previous section.

Other apps will directly call Play Services for authentication, and it's not clear if this generally works on GrapheneOS: There are very few apps that call Play Services directly instead of redirecting you to the default web browser, so right now there's not much opportunity to test this with more than a couple of apps.

Registering passkeys

In order to register passkeys using Vanadium, you will have to disable the browser's support for passkeys with password managers. If you already did this when following the steps in "Signing in with passkeys", there is no need to do it again.

In the address bar, type chrome://flags and press enter
In the search bar, type passkeys
A setting called "Android Credential Management for passkeys" will appear. Change this setting to "Disabled"
Select "Relaunch"

The next time you opt to register a passkey for a website you visit in Vanadium, you will be shown the option "Use a different device".

Other notes

PIN creation and entry

This works fine.

PIN and NFC

Play services does not support PIN functionality over NFC. As such, if a service requests you to use a PIN (or if your key is set to require a PIN for all authentication) you will have to use USB. Play services might display the NFC option regardless, even when it will not work for you.

This is especially relevant for passkeys, where a PIN or other user verification is often set to be required or preferred by the service. Notably, and perhaps slightly ridiculously, Play Store allows you to sign in with a passkey using NFC without having to enter a PIN at all.[⁵]

Google accounts

It does not appear to be possible to register a passkey from within the Play Store app, as the button "Create passkey" does nothing. I am observing the same behaviour on stock PixelOS. You will have to register the passkey by signing in to your Google account in a web browser.

Signing in to the Play Store with a passkey seems to work fine.

Network access for Play services

In the past, Play services needed occasional network access in order for FIDO authentication to function. As of the latest update to this guide, security keys now work fine even if the Network permission has never been granted to Play services.

Error messages from Play services

When FIDO authentication fails, Play services will not provide you with any useful error messages. For instance, if your security key is not actually registered against the service you are attempting to sign in to, a generic error will be displayed. One might contrast this to Windows, which in such a case will display the slightly more useful message "this security key does not look familiar". Hence, until you start troubleshooting, you usually can't know immediately why an authentication fails.

I am no expert in this field, so please comment any corrections regarding this text, or inaccurate usage of terms.

[¹]: Some services implements – or implemented – a custom FIDO library because of Android's lack of native support for authentication with CTAP2 and FIDO2 passkeys on security keys. Buypass is one example of a service utilizing an API to overcome this.
Since Play services now has support for CTAP2 and FIDO2 passkeys, it's likely that more services will phase out their use of custom FIDO libraries.

[²]: On the status of native FIDO support in AOSP and GrapheneOS, here is some information given by the GrapheneOS project: https://x.com/GrapheneOS/status/1847994282994458682#m

Quote from the tweets:

User: @GrapheneOS please make passkeys work on GrapheneOS! Crypto people need this

GrapheneOS: "FIDO2 and passkeys work on GrapheneOS. Many apps implement it via the Google Play FIDO library which requires sandboxed Google Play. We plan to provide an alternative implementation for Vanadium. Google engineers told us they were going to add a standalone implementation to AOSP."

GrapheneOS: "We don't know if and when they're actually going to add a standalone FIDO2/passkey implementation to AOSP and it's not a priority for them because they work fine via Google Play already. They're fine with it so they're in no rush to fix this, but they did claim they would."

Other user: "When they follow up on that promise is irrelevant. You don't need passkeys."

GrapheneOS: "Passkeys work fine on GrapheneOS. We want to have an implementation not depending on the Google Play SDK and Google Play services. We were told that it would be added to the Android Open Source Project but that has yet to materialize in any form years later."

GrapheneOS: "This is not only about passkeys but also more traditional FIDO2 security key usage too. Most apps implement both using the Google Play SDK. We could make our own independent implementation of course but they told us they'd be adding it to AOSP which discouraged us from doing it."

[³]: As far as I know, older models of the Google Titan Key cannot store passkeys. I am unable to test the newest model, as Google does not ship to where I reside.

[⁴]: Keys that support the CTAP2.1 standard ought to be able to support passkey management – perhaps the most useful aspect of this being the ability to delete passkeys from the device, which is especially welcome if your security key has a limited number of passkey slots.

[⁵]: You can set a flag on your security key in order to make all authentication require a PIN. Your key needs to support CTAP2.1. When the flag is enabled, all sign-in attempts, including when using multi-factor with a password, will require a PIN. Naturally this adds a slight inconvenience, at the benefit of some extra protection against an attacker physically stealing your key and using it to sign in to a service that does not require (or discourages) user verification. I will not make a recommendation on which option to choose; make up your own mind about your security requirements and risks.