.. bio-specifics.rst .. _bio-specifics-label: =============================== YubiKey Bio Series Specifics =============================== .. _bio-how-it-works-label: How the YubiKey Bio Works ========================== For the full technical explanation of this from a developer perspective, start with the `Yubico's WebAuthn Developer Guide `_. .. Note:: In the following, the term *credentials* is referenced repeatedly. There are different kinds of credentials. To pursue all the distinctions, consult the `FIDO2 page on the Fido Alliance web site `_. Enrollment ------------ Before you can start using the YubiKey Bio with services and applications, you need to first set a :ref:`bio-fido2-pin-label` and then enroll at least one fingerprint. The YubiKey Bio needs to have the PIN as a fallback in case it cannot recognize your fingerprint. .. include:: includes/pin-behavior-label.rst The "working" of the fingerprint is described in the following. For information on how and why the fingerprint might not "work", see :ref:`bio-finger-tips-label`. Risk Mitigation ~~~~~~~~~~~~~~~~ To mitigate the risk of being shut out of your account or service, it is always advised to register a second YubiKey. For more information, see https://www.yubico.com/spare/. Fingerprints and Templates ~~~~~~~~~~~~~~~~~~~~~~~~~~~ An enrolled fingerprint is stored on the YubiKey Bio not as an image, but in the form of a template, similar to a one-way hash. It is not possible to recreate an image of a fingerprint from a template, nor does the template ever leave the YubiKey. After enrollment, each time you apply your fingertip to the fingerprint sensor, the key tries to match the fingerprint against the template stored on the key. Parties Involved in Registration and Authentication ---------------------------------------------------- Closely related to :ref:`bio-requirements-label`, registering and authenticating with a YubiKey Bio to an app or a service that supports WebAuthn or U2F involves several parties: * The user (with their fingerprints and knowledge of the PIN) * The YubiKey Bio * The FIDO2 application or the U2F application on the YubiKey Bio * The FIDO2/WebAuthn or U2F-supporting **browser** or **client** * The service or app All these work together. For example, if your YubiKey does not work as expected, you might be using a browser or an app that does not support FIDO2 security keys. Registration ~~~~~~~~~~~~~ Registering a YubiKey Bio with a site, service, or application is the same as for other YubiKeys. Authentication ~~~~~~~~~~~~~~~~ Depending on the protocol supported by the site or service, there are several possible user experiences (scenarios). These are described below. .. _bio-user-experience-label: User Experiences ----------------- The user experience with the YubiKey Bio is dictated by a combination of the site or service that the user is authenticating against and the browser or client. Different service and client combinations yield different results. The user experiences are determined by the different options for developers implementing FIDO2 with the WebAuthn and CTAP protocols. Please note that the following descriptions of user scenarios are only **high-level overviews**. The experiences change every time the various forms of support change. Passwordless ~~~~~~~~~~~~ This scenario provides the best user experience by enabling a passwordless flow backed by strong authentication. To achieve it, use `discoverable credentials `_. When the user authenticates to the site or service: 1. The client or browser prompts the user to insert the YubiKey. 2. The client makes a request to the YubiKey to see if any credentials on the key have been registered for use with this site or service. 3. If the correct credentials are found, the *client or browser* prompts the user to apply their fingertip to the YubiKey Bio's sensor. * If the fingerprint match is successful, the appropriate response is sent to the client or browser to complete authentication. * If the fingerprint match is unsuccessful three times in a row, the client or the browser prompts instead for the PIN. After correctly inputting the PIN, the user is then prompted to touch the key to prove presence (as opposed to verifying identity). In this situation, the YubiKey Bio behaves like any other key in the YubiKey 5 Series. .. _bio-uv-discouraged-label: Multifactor Authentication (MFA) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When a user authenticates to the site or service, 1. The client or browser prompts the user to insert their username and password. These are what the server uses to identify the user and determine whether they are registered. 2. If username and password match the server's records, the site or service prompts the user for an additional form of identification to prove their identity. This is called **multifactor** authentication. 3. The user proves their identity *to the key* either by providing a fingerprint that the key can match to its template, or by entering the PIN. * If the fingerprint match is successful, the appropriate response is sent to the client or browser to complete authentication. * If the key is unsuccessful at matching fingerprint to template three times in a row, the YubiKey Bio goes into the biometrics blocked state, signaling this by slow constant flashing of the amber LED. The client or the browser prompts instead for the PIN and for the user to touch the key (checking for user presence). In this situation, the YubiKey Bio behaves like any other key in the YubiKey 5 Series. U2F ~~~~ This scenario only works well if the fingerprint match is successful and the user flow is the same as the multifactor flow. If the fingerprint match is unsuccessful, any prompts from the site or service are unlikely to be clear and unambiguous. The user needs to unblock the Yubikey. To do this, see the `YubiKey Bio start page `_ or by use the Yubico Authenticator for Desktop. .. _bio-locking-blocking-label: Locking/Blocking ~~~~~~~~~~~~~~~~~ .. include:: includes/bio-locking-blocking.rst Managing Credentials --------------------- .. include:: includes/managing-credentials.rst ---- .. _bio-chrome-enrolling-label: Using Chrome to Enroll Fingerprints ==================================== Set a PIN and enroll the *first* fingerprint using the Chrome browser on a macOS, Linux or Chrome OS device. To enroll more fingerprints use the Chrome settings as described in :ref:`bio-chrome-add-label`. .. include:: includes/built-in-auth.rst .. include:: includes/pin-behavior-label.rst For information on the YubiKey Bio's sensor and tips on working with fingerprints see :ref:`bio-finger-tips-label`. For detailed information on FIDO2 PINs and their requirements, see `Understanding YubiKey PINs `_. Enrolling the First Fingerprint -------------------------------- :Step 1: Use an up-to-date Chrome browser to open the `YubiKey Bio Series setup `_ website. Insert your YubiKey Bio into your computer. :Step 2: Scroll down to the green button, **Enroll using Chrome**, and click it. The **Use your security key with Yubico.com** popup appears, this wizard walk you through the PIN setup (if no PIN is set) and fingerprint enrollment: .. image:: graphics/insert-key-ff.png :scale: 75 % :align: left :Step 3: If the amber LED flashes slowly, it means either no fingerprint is enrolled or biometrics is blocked. If you have reason to believe biometrics are blocked, go to the appropriate link on the `YubiKey Bio Series setup page `_ or to :ref:`bio-troubleshooting-tools-label`. Otherwise, *touch the key*: .. image:: graphics/PIN-required-ff.png :scale: 75 % :align: left :Step 4: If no PIN is set, set one by entering at least 4 digits, then confirm this PIN by re-entering it. If the YubiKey Bio already has a PIN set you are prompted to enter it. :Step 5: When prompted, touch the fingerprint sensor and the bezel. You are prompted to touch the sensor several times, as set out below. Change the angle of finger to sensor slightly each time. Continue lifting and re-applying the same finger until the gray circle is entirely blue, the fingerprint icon is replaced by a tick mark, and the message in the popup reads "Your fingerprint was captured." .. image:: graphics/fingerprint-captured-ff.png :scale: 50 % :align: left :Step 7: Click **Next**. The **Touch your security key again to complete the request** popup appears: .. image:: graphics/touch-again.png :scale: 50 % :align: left :Step 8: Touch the bezel and sensor one last time. The final popup announces that enrollment was successful. The YubiKey Bio now has a template for that fingerprint. .. _bio-chrome-add-label: Enrolling Additional Fingerprints ---------------------------------- If the YubiKey Bio already has fingerprint(s) enrolled on it, repeating the procedure for the first fingerprint does not work for subsequent fingerprints. Instead follow these steps. .. Note:: You can also use this method for setting a PIN for a new YubiKey Bio and enrolling all fingerprints. :Step 1: Either paste ``chrome://settings/securityKeys`` into the Chrome address field or click on the three vertical dots to the right of the URL field and navigate to **Settings->Security->Advanced->Manage security keys**. :Step 2: Click **Fingerprints** and follow the instructions in the popup. ---- .. _bio-microsoft-enrolling-label: Using Windows to Enroll Fingerprints ===================================== These are the instructions for setting a PIN on a YubiKey Bio and enrolling fingerprints on it using the Sign-in options on a Windows 10 or Windows 11 system. .. include:: includes/built-in-auth.rst .. Note:: To get to the popup (prompt) for the YubiKey, you might need to *cancel* out of the pop-up for the built-in authenticator. .. include:: includes/pin-behavior-label.rst For information on the YubiKey Bio's sensor and tips on working with fingerprints see :ref:`bio-finger-tips-label`. For detailed information on FIDO2 PINs and their requirements, see `Understanding YubiKey PINs `_. :Step 1: On *Windows 10*, click **Enroll using Windows** on the YubiKey Bio setup page `_. On *Windows 11*, click **Enroll using Windows** on the YubiKey Bio setup page `_. Then go to Step 3 below. :Step 2: On *Windows 10*, in the expanded **Security Key** field, click **Manage**. .. image:: graphics/win-manage-security-key.png :scale: 51 % :Step 3: On both *Windows 10* and *Windows 11*, follow the Windows setup directions. Insert the YubiKey Bio into your computer's USB port and set a PIN for your YubiKey Bio if the key does not already have a PIN. In the **Security Key PIN** field, click **Add**. Enter a security key PIN and click **OK**. :Step 4: To enroll your fingerprint, in the **Security Key Fingerprint** field, click **Set up** and follow the prompts. Touch the YubiKey Bio sensor while the green LED is still flashing, making sure to touch the ring-bezel as well. Vary the way you touch each time to include more of the fingerprint. If the fingerprint you enroll is smaller than the sensor, apply some pressure to help ensure a good image capture. Continue lifting and re-applying the same finger until you see the **All set!** message. Perform this step up to five times for a total number of 5 enrolled fingerprints. ---- .. _bio-finger-tips-label: Fingerprint Tips ================== .. _bio-led-label: LED Behavior ------------- The YubiKey Bio is not in a permanent state of readiness. It is therefore essential to wait for the key to signal its readiness by flashing the green LED before you touch it. * If the key reacts to your touch by flashing or blinking the green LED, you used the right touch. * If the amber LED flashes three times in quick succession, the attempt to match your fingerprint with the template was not successful. * If the amber LED flashes slowly and continuously, it is in the biometrics blocked state. * If the key does not react to your touch, you might not have touched both the bezel and the sensor. When you apply your fingerprint, always make sure you are touching the bezel at the same time. See :ref:`bio-touch-tip-label` below. Fingerprint Enrollment Progress Indicators ------------------------------------------- The progress of reading of your fingerprint is displayed on-screen. The way it is shown depends on the client platform and browser. It is generally not under the control of the site or the service. The screenshots below show enrollment using platform support: .. Figure:: graphics/half-fingerprint-ff.png :scale: 35 % Chrome on macOS, Linux, and Chrome OS: Capturing the Fingerprint .. Figure:: graphics/win-repeat-fingertip.png :scale: 58 % Windows: Capturing the Fingerprint Fingerprint Orientation ----------------------- The YubiKey Bio supports 360 degree fingerprint reading, meaning that a fingerprint can be read from any angle once successfully enrolled. .. _bio-touch-tip-label: Tips for the Touch -------------------- Because the fingerprint can be negatively affected by environmental conditions such as heat, cold, injury, etc., it is not always easy for the YubiKey Bio to interact with it. The following tips are helpful. .. include:: includes/bio-touching-the-biokey.rst :Fingerprint: For enrolling, when we say *fingertip*, we actually mean the pad on the tip of the finger where the whorls of the fingerprint are. The fingerprint could equally well be a thumbprint or a toeprint; the YubiKey Bio makes no distinction between fingers, thumbs, and toes. :Print quality: Dry or scarred skin can impede the key’s ability to perform a successful fingerprint match. If your hands are dry, use moisturizer or water to enable conduction. Do not apply wet fingertips. :Repeat reading: Enrolling your fingerprint requires pressing your fingertip against sensor (and bezel) several times, usually 5 to 8 times. If an attempt to capture is unsuccessful the YubiKey Bio needs you to repeat enrolling. :Vary the angle: When enrolling a new fingerprint, angle your finger so that different parts of the fingerprint come in contact with the sensor and bezel with each capture. This enables the YubiKey Bio sensor to collect a larger area of your finger. :Temperature: If the fingertip is too cold, the YubiKey Bio might not be able to read the fingerprint. If your hands are cold, rub them together to get the circulation going and warm them up. :Press firmly: Press the YubiKey Bio sensor and bezel with your fingertip gently but firmly and hold for a second or so. If you are using an adapter, it may be necessary to hold onto the adapter to prevent it from bending and interrupting the connection to the YubiKey. :Stable key: If the YubiKey Bio seems to wobble in the USB port, use your other hand to hold it steady in the port while you are applying your fingertip. :Stable dongle: If you are using a dongle as an adapter to your device's USB port, ensure the YubiKey Bio is stable enough for you to apply sufficient pressure with your fingertip. :Check the LEDs: When you start enrolling a fingerprint, the green LED on your YubiKey Bio starts to flash. Start enrolling the fingerprint before the green LED on the YubiKey Bio stops flashing. The amber LED might flash slowly, indicating that no fingerprint is enrolled or that biometrics is in the blocked state. :Clean sensor: If there is dust or oil residue on the YubiKey Bio sensor and bezel, clean it. See :ref:`cleaning-label`. :Change ports: Sometimes the USB port does not work well or the YubiKey Bio is loose in the port. Insert the YubiKey Bio in a different port on your device. ---- .. _bio-troubleshooting-tools-label: Troubleshooting and Tools ========================== Troubleshooting ---------------- The primary source for troubleshooting tips is the FAQ on the `YubiKey Bio Series setup page `_. .. include:: includes/bio-locking-blocking.rst If you run into any issues with a YubiKey Bio, you can also refer to the `Knowledge Base on Yubico's Support site `_ and search for your issue. If your issue is not listed in the Knowledge Base, or if you have any technical questions, you can `open a ticket with our Technical Support team `_. Unblocking/Unlocking ~~~~~~~~~~~~~~~~~~~~~ Use the appropriate link on the `YubiKey Bio Series setup page `_ or the Yubico Authenticator for Desktop. Other Issues ~~~~~~~~~~~~~ If you run into any issues with a key from the YubiKey Bio Series, refer to the `Knowledge Base `_ and search for your issue. If your issue is not listed in the Knowledge Base, or if you have any technical questions, you can get in touch with Yubico Support, http://yubi.co/support. .. _bio-tools-label: Tools ------ Yubico Authenticator for Desktop ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ `Yubico Authenticator for Desktop `_ can be used to manage the YubiKey Bio. It is open source and cross-platform, running on Windows, macOS, and Linux. The iOS and Android versions of Yubico Authenticator cannot be used to manage the YubiKey Bio. ---- .. _bio-requirements-label: Requirements: Platform and Browser Compatibility ================================================= Desktop -------- The YubiKey Bio Series works with the latest versions of most browsers and desktop operating systems. Currently, the best experience can be had on macOS, Chrome OS, and Linux, running up-to-date Chromium-based browsers. On **Windows 10**, browsers are not currently able to tell you when the YubiKey has failed to match the fingerprint, so you must watch for the YubiKey's blinking amber LED to indicate if an attempt has failed. **Windows 11** does not have this problem. On other platforms, browsers such as Firefox and Safari have not yet (at the time of writing) implemented CTAP 2.1 and therefore you are typically prompted to enter the PIN even if the key is not in the "biometrics blocked" state. Mobile ------- * The YubiKey Bio does not have NFC capabilities. * The YubiKey Bio can be used with mobile, but it is reliant on mobile operating system support as well as on browser support for the FIDO protocols. For more information, please refer to the relevant manufacturer's web sites for your mobile device. * When the YubiKey Bio has fallen back to requiring the PIN, you might need to resort to computers (and not the mobile devices) to unblock biometrics. ---- .. _bio-reset-label: Resetting Your YubiKey Bio with the Yubico Authenticator for Desktop ===================================================================== In this context, resetting means resetting the FIDO application. You can also perform a FIDO reset using the YubiKey Manager, Windows Sign-in options, or the Chrome browser settings. The main cause for the biometric function blocking is failure to match the fingerprint three times in a row. If the YubiKey Bio was locked because the biometric function was blocked, you can just unblock it instead of resetting it: see :ref:`bio-troubleshooting-tools-label`. **Resetting the key is not the same as unblocking it**. Because resetting the FIDO2 and FIDO U2F applications returns the key to the factory default state, which has neither fingerprints nor PIN nor credentials, you must enroll your fingerprints again after resetting it and register your key again to your apps and services. See the relevant Enrolling chapter, either :ref:`bio-chrome-enrolling-label` or :ref:`bio-microsoft-enrolling-label`. .. Note:: Resetting your YubiKey Bio deletes all credentials, the PIN, and stored fingerprint templates. To review your options for tools to reset the YubiKey Bio, see :ref:`bio-troubleshooting-tools-label`. ---- .. _bio-faq-label: Frequently Asked Questions =========================== See the FAQs on the `YubiKey Bio Start Page `_. ---- .. _bio-fido2-label: YubiKey Bio and FIDO2 ====================== The YubiKey Bio Series - FIDO Edition supports all FIDO2 scenarios supported by the YubiKey 5 Series and the Security Key Series. It can be used in both passwordless and second factor authentication scenarios. In both scenarios the fingerprint is used *in lieu of* the PIN, similar to the way biometrics are used on a smartphone. There are some scenarios in which the PIN is required. The PIN is required when enrolling or otherwise managing fingerprints, just as it is on a smartphone. The only opportunity to input the PIN is after 3 unsuccessful attempts at matching a fingerprint with an enrolled finger. Discoverable Credentials ------------------------- Like FIDO U2F, the `FIDO2 `_ standard offers the same high level of security, as it is based on public key cryptography. In addition to providing phishing-resistant two-factor authentication, the FIDO2 application on the YubiKey allows for the storage of discoverable credentials. (Fingerprint templates are not discoverable credentials.) Keys in the YubiKey Bio Series can hold up to 25 discoverable credentials. To manage them, see :ref:`cred-mgmt-label`. .. _bio-fido2-pin-label: FIDO2 PIN ~~~~~~~~~~ The FIDO2 PIN is necessary for: * Enrolling fingerprints * Managing enrolled fingerprints * Fallback after failure to match fingerprint with template. The FIDO2 PIN must be between 4 and 128 characters in length (for more information, see https://support.yubico.com/hc/en-us/articles/4402836718866-Understanding-YubiKey-PINs) * There is no PIN set by default * Once a FIDO2 PIN is set, it can be changed but it cannot be removed unless you reset the FIDO2 application. * If the FIDO2 PIN is entered incorrectly 3 times in a row, the key needs to be reinserted before it can accept additional PIN entry attempts. Reinserting "reboots" the key. * To see the number of retries remaining, use YubiKey Manager and navigate to Applications > FIDO2. * If the PIN is entered incorrectly a total of 8 times in a row (3+3+2), the FIDO2 application becomes locked, and FIDO2 authentication is not possible. * To restore the FIDO2 functionality, reset the FIDO2 application.  .. Note:: Resetting the FIDO2 application also resets the U2F application. No site you have registered the YubiKey with using U2F will work until the YubiKey is re-registered with that site. FIDO2 Credentials ~~~~~~~~~~~~~~~~~~ The discoverable credentials can be used for passwordless authentication, or they can be used for two-factor authentication. In both scenarios the credentials can be protected by the FIDO2 PIN and in the case of a YubiKey Bio, biometrics can be used in lieu of the PIN provided that fingerprints have been enrolled and that the key is not in biometrics blocked state. User Verification ------------------- The YubiKey Bio implements always-on user verification, or ``alwaysUV``. The user verification requirement asks for proof that the user logging in is the same user as the one who set the PIN, enrolled fingerprints, and registered the key with the app or service (Relying Party, or RP). For more information about user verification, see `User Presence vs User Verification `_. When ``userVerification`` is discouraged, the user experience is not optimal unless the platform has implemented CTAP 2.1. See :ref:`bio-uv-discouraged-label`. .. _cred-mgmt-label: Credential Management ---------------------- .. include:: includes/managing-credentials.rst Supported Extensions --------------------- .. include:: includes/supported-extensions.rst ---- .. _bio-u2f-label: YubiKey Bio and FIDO U2F ========================= The FIDO U2F protocol does not require any special drivers or configuration to use, just a compatible web browser. The U2F application on the YubiKey can be associated with an unlimited number of WebAuthn sites supporting FIDO U2F authentication. FIDO U2F on the YubiKey Bio Series requires that the touch be a successful biometric match with an already enrolled fingerprint. This is different from FIDO U2F on other YubiKeys. PIN + U2F ---------- As the concept of PIN does not exist in FIDO U2F, after three successive failures to match the fingerprint, the key goes into the "biometrics blocked" state without first prompting for the PIN. An amber LED blinks slowly and continuously to indicate this state. Biometrics can be unblocked with a FIDO2 operation using the PIN (that is, authentication). See :ref:`bio-troubleshooting-tools-label` for full instructions and more information. .. Note:: **Developers**: With regard to computer login tools that use FIDO U2F for second-factor authentication, some software might use a YubiKey and FIDO U2F as a second factor. Since FIDO U2F has no concept of fallback to PIN, the YubiKey Bio is not likely to be a good choice for this use case. For more information about software that falls into this category, visit Yubico's Support site and look for articles about the YubiKey Bio: https://support.yubico.com/hc/en-us/search?query=YubiKey+Bio FIDO U2F Succeeded by FIDO2 ---------------------------- FIDO2 is the umbrella term used to describe an amalgamation of two separate sets of specifications: WebAuthn and the Client-to-Authenticator Protocol, CTAP (currently version 2.1, and often referred to as CTAP2.1). The WebAuthn component provides a narrow scope of flexibility for developers on the service layer because it encompasses the logical interactions across a network. CTAP2.1, however, provides a much more open set of standards for the interaction between a security device and the user. CTAP2.1 is also where biometrics such as fingerprint enrollment, management, and use were first defined. To create a cohesive user experience, adherence to this specification is required from: * Authenticators such as the YubiKey Bio * Clients such as the Chrome or Edge browsers * Platforms such as Windows and macOS. See :ref:`bio-user-experience-label`. Supported Extensions --------------------- .. include:: includes/supported-extensions.rst ---- Click for `Yubico Support `_.