Troubleshoot When the WebAuthn Ceremony Fails
This page offers troubleshooting tips for when a WebAuthn registration ceremony fails in relation to implementation of support for passkeys.
Failed WebAuthn ceremonies might create confusion
The WebAuthn registration ceremony is a process that starts when a relying party supplies passkey request options along with a challenge that is passed to the WebAuthn API in the browser. The user selects an available authenticator and authorizes the action. The process ends when the API responds with the public key and a signed challenge.
For the end user, this process is started when they select a Create Passkey button or initiate a sign in with a passkey. The process ends when the user sees the passkey created message or they are signed in.
When the WebAuthn registration ceremony is not successful, the relying party does not have visibility to know why. This aligns with the Privacy considerations for clients with regard to passkeys. However, it also means that the relying party cannot display specific error messages for the end user. There might be confusion for the user around what went wrong and how to successfully complete the process in the future.
Reasons the WebAuthn registration ceremony might fail:
- Time out
- Unsuccessful screen lock
- User cancels the ceremony
- Encryption is not set up on device and user does not want to enable it
Steps to reproduce
- Register a passkey or sign in.
- Use any of the reasons for WebAuthn registration ceremony failure to allow the ceremony to fail.
- Notice that after the failure the relying party does not provide an explanation of what went wrong or information on how to be successful with your next attempt.
Guidance
When passkey creation fails, most organizations show an error message similar to this:
A passkey couldn't be created for this device or you canceled creating a passkey.
When signing in with a passkey fails, most organizations simply redirect the end user back to the standard sign in screen and do not show an error message.
