Introduction

This collection of guides is intended to help service providers, organizations and individuals make good decisions about supporting, requiring, and using the protocols that the YubiKey supports. It includes frequently asked questions, best practices, and reference architectures.

Audiences

This collection of guides is made up of a variety of different kinds of articles, from conceptual articles that lay a foundation for understanding how a technology works to FAQs and prescriptive best practices guidance.

While we expect readers to be familiar with the kind of article they’re reading, there’s a lot of content in this Best Practices book that may seem inconsistent or even conflicting if the intended audience isn’t made very clear. We’ve made sure to label each article with its intended audiences and, when applicable, a short discussion of why the guidance applies to each of them.

We have identified four main audiences:

  • Service Providers (individual or customer identity)
  • Identity Providers (organization or workforce identity)
  • Organizations
  • Individuals

The main difference for what these audiences require generally comes down to what part of the authentication design and authenticator selection processes they have control over.

Service providers typically only control the design of the service or relying party, but they may be able to encourage use of a specific authenticator (by providing free authenticators to customers). They usually lack the authority to require a specific authenticator or even a specific authentication method. Individuals, on the other hand, typically only control the authenticator they use for personal use and what services they use it with.

Identity providers and organizations tend to have closer coordination, and together control all aspects of authentication, from the authenticator selection to the relying party or service configuration, and can enforce those decisions with either technology or policy controls. Organizations may even build their own relying parties for authentication - in which case they’ll act as the identity provider as well.

While there are some exceptions to these situations in the form of laws or regulations around certain industries or types of services, those exceptions tend to make the decision making process easier by removing some choice.

Not all types of guidance will be applicable to all audiences, and in some cases (like the Passkey Frequently Asked Questions), guidance may be applicable to all audiences.

Passkeys & FIDO2

Before the introduction of synced passkeys, the choices for modern phishing-resistant authentication were limited to two options: use a FIDO2 hardware security key or a platform authenticator (such as Windows Hello for Business or Touch ID for the Mac). Nowadays, there is a much broader spectrum of authenticator choice, and with it, a more challenging set of decisions to make.

For all audiences:

For Service Providers:

FIDO metadata & attestation

The FIDO specifications allow for various levels of privacy regarding individual FIDO authenticators. This guidance discusses the tradeoffs made between privacy and compliance for passkeys and contains specific recommendations for Identity providers processing attestation metadata and for organizations navigating the attestation ecosystem.

Concepts:

For identity providers:

Updates

This is a living document. The computer security landscape is constantly evolving. Changes in regulations, security needs, threat actor behavior, and the technology itself all have the potential to change how the YubiKey and the protocols it supports are best used. This document will be updated periodically and represents the current consensus within Yubico. Specific recommendations may change from time to time. Consider bookmarking this documentation and returning to it periodically to ensure you’re still following the most up-to-date guidance.