The Do’s and Don’ts of Integrating Passkeys

Passkeys are quickly emerging as a secure and user-friendly alternative to passwords. However, implementing them effectively requires careful planning. Here are some key do's and don'ts we've learned along the way to ensure a smooth and secure passkey integration.

Do’s

Offer Passkeys as a First-Factor

Make passkeys a primary authentication method by placing a “Sign in with a passkey” button on your main login page. Additionally, enable passkey autofill on the username/email input field to streamline authentication.

‍

‍

‍

Note that you need to decide whether you want to perform the 'create passkey' or 'use passkey' action on a page. This means that you can either have a “Login with a passkey” or a “Create a passkey” button, but not something like a “Continue with a passkey” button, which would work a bit like social login buttons, where it doesn't really matter whether the user wants to log in or register.

In the future, the WebAuthn API may add a 'conditional create' option for passkeys, which would enable the combined passkey button, but it is not yet available.

For now, we recommend just placing a “Login with a passkey” button on your login page and handling the creation of the passkey in an additional step during account creation after the user has entered their email address or desired username. Which brings us to the next Do on our list.

Let Users Create a Passkey During Onboarding

Encourage new users to create a passkey right from the onboarding process. This ensures they adopt passkeys early, making their future logins seamless and secure.

‍

‍

Make Passwords Optional

If users can create a passkey, let them decide whether they want to set up a password at all. Reducing password dependency simplifies authentication and enhances security. However, making passwords optional has usability and privacy implications. For instance, displaying a password input by default may confuse users who never set one, but hiding it until after user identification could expose privacy risks like account enumeration. Consider these factors carefully when designing your authentication flow.

Provide Passkey Management in Security Settings

Give users control over their passkeys by allowing them to:

• View a list of their saved passkeys
• Create additional passkeys for different devices
• Rename passkeys for easy identification
• Delete passkeys they no longer need

Prompt Users to Create a Passkey (If They Haven’t Yet)

If a returning user logs in without a passkey, prompt them to create one. Highlight the benefits—faster logins and stronger security—while ensuring there’s a “Don’t show again” option for those who prefer other methods.

Use Human-Friendly Passkey Names

When creating new passkeys, use names that help users identify where they are stored, such as:

• iCloud Keychain
• Google Password Manager
• 1Password

‍You can use the passkey AAGUID to determine and assign a relevant name. Find out more about AAGUIDs here.

Prevent Overwriting Existing Passkeys

Use the excludeCredentials option to prevent users from unintentionally overwriting existing passkeys, which could lead to orphaned (zombie) passkeys stuck on their devices.

Don’ts

Don’t Capitalize “Passkey” Incorrectly

Avoid writing PassKey, Pass Key, or other variations. The word “passkey” should be treated as a common noun, like “password” or “email.”

Don’t Trigger Passkey Authentication Only After Username Input

You should avoid requiring users to enter their username before triggering passkey authentication. One of the advantages of passkeys is that they not only contain a secure and unphishable credential, but also the user ID, which enables one-click login without the user having to enter their username or email address at all. Ideally, you should therefore not hide the passkey flow behind the username entry and only trigger the passkeys afterwards, but instead offer the passkey login option on the main login page to take advantage of the “username-less” capabilities of passkeys.

Don’t Restrict Passkey Creation to Platform Authenticators

Some users prefer to store their passkeys on hardware security keys rather than cloud-based solutions. Avoid limiting passkey creation to platform authenticators unless you’re absolutely certain your users won’t need other options.

Don’t Use Cookies or Local Storage in an Attempt to Track Passkey Creation

Trying to determine if a user has a passkey based on cookies or local storage is flawed because:

• Passkeys sync across devices, meaning a passkey created on one device might not be detected on another.
• Some users switch between multiple browsers, but cookies don’t carry over across browsers.

There will 100% be situations where your cookie-based assumption is incorrect, so we've determined that it's better not to try this at all and simply offer the passkey login option to all users.

Final Thoughts

Integrating passkeys effectively requires thoughtful UX design and security considerations. By following these do's and don'ts, you can provide a seamless authentication experience while maintaining security and flexibility for your users.

Have any other lessons learned while integrating passkeys? Let us know in the Hanko Community!

‍