GrapheneOS does not [currently](https://github.com/GrapheneOS/Vanadium/issues/61) have native support for FIDO security keys. To use security keys on GrapheneOS, you can install third-party apps that add support for them.
There are two known apps that enable you to use security keys on GrapheneOS:
- HW Fido2 Provider ([website](https://codeberg.org/s1m/hw-fido2-provider))
- Sandboxed Google Play
HW Fido2 Provider provides support for passkeys* and partial support for non-passkeys** on security keys in Vanadium.
Sandboxed Google Play provides support for security keys in Vanadium, and support for non-passkey sign-in in other apps.
Passkey sign-in in apps other than web browsers is the only functionality known not to work on GrapheneOS.
Those two apps can co-exist: if there is functionality that HW Fido2 Provider does not provide, a Google Play dialog will be displayed instead.
While Google Play's support is slightly more extensive, it is known to exhibit some incompatibilities on GrapheneOS. This text exists to provide you with workarounds for these incompatibilities.
(The two apps provide support for web browsers other than Vanadium as well, but Vanadium is the reference browser in this text).
# How to use Google Play for security keys
You can install Google Play from *App Store* → *Google Play services*.
For security key functionality, there is ***no*** need to:
- sign in to Play Store
- grant battery usage exemptions for Play services or Play Store
- grant extra permissions to Play services or Play Store
- enable exploit protection compatibility mode
- do anything other than leave the default settings intact
## Challenge #1: password managers
With Google Play, password managers that support passkeys take precedence over security keys, and there is no choice in Google Play's dialogs to switch between them. This is an unresolved issue with sandboxed Google Play.
Therefore, when using security keys, in most cases you must temporarily disable autofill with your password manager. To do this, go to the *Settings* app → *Passwords, passkeys & accounts* and uncheck your password manager.
## Challenge #2: registering passkeys
With sandboxed Google Play, there is an issue with registering passkeys when using Vanadium. There is no known workaround for Vanadium, but it is known to work successfully with Brave.
Note that Play services and many other services refer to all FIDO credentials as "passkeys", even when they are not. Your best bet is to just try to register the passkey/credential with Vanadium, and if that doesn't work, then try with Brave (or in Vanadium with HW Fido2 Provider).
## Challenge #3: passkeys in non-browser apps
With sandboxed Google Play, there is an issue with signing in and registering passkeys in apps other than web browsers. There is no known workaround for this. Non-passkeys work fine.
In practice, this is often not an issue, as the tendency is for apps to redirect you to the default web browser, and then redirect you back to the app after successful security key usage.
# Troubleshooting
## NFC sometimes fails
Play services does not support PIN entry when using NFC. It occasionally displays the option to use NFC, but then silently fails when you use the key. If this occurs, then try to use the USB option instead.
## Network permission for Play services and Play Store
Some users have reported that Play services and Play Store require an internet connection during the first usage of their security key. If you have disabled the Network permission for Play services and Play Store, you may have to grant them the permission, then reboot your device and try again.
## General troubleshooting
If none of the above works, you can always try the following:
- re-insert your security key
- refresh the website / close and re-open the app
- reboot your device
- double-check that you have actually registered your security key against the service that you are attempting to sign in to
- check that GrapheneOS is up-to-date
- sign in to the service on a different device, remove the security key from your account, re-add it and try again
If you are still having issues with using your key, try to look for answers by [searching the GrapheneOS forum](https://discuss.grapheneos.org/) and [community chat rooms](https://grapheneos.org/contact#community-chat).
If you are using HW Fido2 Provider, check for [known issues on their website](https://codeberg.org/s1m/hw-fido2-provider).
If you can't find a solution by searching, you can always create a thread in the GrapheneOS forum or reach out to members in the community chat rooms. In order for people to be able to assist you, please try to include the following:
- the name/model of your security key
- which third-party app you are using for security key support
- GrapheneOS version (go to the *Settings* app → *About phone* → scroll down to *Build number*)
- how to replicate your issue – for example:
1. I am opening X app and performing Y action in the app
2. I plug in my security key
3. I receive the following error message
- what you have already tried (for example, "I have followed every step in this guide")
And if you are using sandboxed Google Play:
- Play services version (go to *App Store* → *Google Play services* → look at *Installed version*)
- GmsCompatConfig version (go to *App Store* → *Google Play services* → *GmsCompatConfig →* look at *Installed version*)
This might seem excessive, but providing this information makes it easier for people to provide relevant advice.
# Footnotes
*Otherwise known as "discoverable credentials"
**Registering non-passkeys work in some cases. Please see https://codeberg.org/s1m/hw-fido2-provider/issues/7#issuecomment-4438703
and https://github.com/GrapheneOS/Vanadium/issues/61#issuecomment-2833515385
for details.
Goodbye y'all 😉