Body
Guidance for configuring a new YubiKey beyond out-of-the-box defaults: setting personal identification numbers (PINs), disabling unused applications, planning a backup key, and enrolling services. Intended for users who plan to use applications beyond standard FIDO2 passkeys.
Detailed Information
WARNING: These are advanced instructions that require knowledge of using command line tools. These instructions if used incorrectly could wipe all your passkeys on a Yubikey including any passkeys for non-UMS systems that you have stored on the Yubikey.
INFO: If you only plan to use your YubiKey for FIDO2 passkeys or WebAuthn sign-in, no setup steps below are required. The FIDO2 application self-provisions when you register the key with your first service, and you will be prompted to create a PIN at that time. Passkeys are the recommended use case for most users and are sufficient for the majority of UMS sign-in scenarios.
The steps below apply if you intend to use additional YubiKey applications — Personal Identity Verification (PIV), One-Time Password (OTP), OATH, or OpenPGP — or if you want to harden the default configuration before enrolling the key with services. Most steps use the YubiKey Manager command-line tool (ykman), which is available for Windows, macOS, and Linux.
Inventory the key
Run ykman info to confirm the model, firmware version, serial number, and which applications are currently enabled over Universal Serial Bus (USB) and Near Field Communication (NFC). Record the serial number in a secure location for inventory and recovery purposes.
ykman info
Disable unused applications
Reducing the number of enabled applications limits the attack surface and prevents accidental input from unused slots (for example, OTP slot 1 firing when the key is brushed).
Disable an application over USB:
ykman config usb --disable OTP
Disable an application over NFC:
ykman config nfc --disable OTP
Common applications and what they do:
FIDO2 — Passkeys and WebAuthn. Leave enabled.U2F — Legacy second-factor authentication. Leave enabled if any service still requires it.OTP — Yubico One-Time Password and static password slots. Disable if not in use.PIV — Smart card support for certificate-based authentication.OATH — Time-based One-Time Password (TOTP) and HMAC-based One-Time Password (HOTP) storage.OPENPGP — OpenPGP key storage for signing, encryption, and Secure Shell (SSH) authentication.
Set PINs on the applications you will use
WARNING: Each YubiKey application has its own PIN and its own factory default. Anyone with physical access to a YubiKey using factory defaults can reconfigure that application. Change the defaults on every application you plan to use.
FIDO2 PIN (no default — you set it):
ykman fido access change-pin
PIV PIN, PIV Unblock Key (PUK), and management key (defaults are 123456, 12345678, and a publicly documented hexadecimal value):
ykman piv access change-pin
ykman piv access change-puk
ykman piv access change-management-key --generate --protect
The --protect flag stores the new management key on the device, encrypted with the PIV PIN, so you do not need to track it separately.
OATH password (no default — optional but recommended if storing TOTP secrets):
ykman oath access change
OpenPGP user PIN and admin PIN (defaults are 123456 and 12345678):
ykman openpgp access change-pin
ykman openpgp access change-admin-pin
Lock down the OTP slots
New YubiKeys ship with the long-press OTP slot pre-programmed with a Yubico OTP credential. If you do not use Yubico OTP, delete the credential to prevent accidental input:
ykman otp delete 1
If you do use OTP, set an access code on the slot so it cannot be reprogrammed without the code:
ykman otp settings --new-access-code 1
Set PIV touch and PIN policies before generating keys
When you generate or import a PIV private key, the touch policy and PIN policy are fixed at generation time and cannot be changed afterward without regenerating the key.
- Touch policy — whether a physical tap is required for each cryptographic operation. Options are
never, always, or cached (touch is valid for ~15 seconds, allowing bursts of operations with a single tap).
- PIN policy — how often the PIN must be entered within a session. Options are
never, once, or always.
For most authentication and signing use cases, --touch-policy=cached --pin-policy=once is a reasonable balance between security and usability:
ykman piv keys generate --touch-policy=cached --pin-policy=once --algorithm=ECCP256 9a public.pem
Configure a backup key
IMPORTANT: Configure a second YubiKey at the same time as your primary and enroll both with every service. Without a backup key, losing your primary may lock you out of accounts that have no other second factor configured. Store the backup in a physically separate, secure location.
Repeat all configuration steps above on the backup key, using the same PINs or recorded distinct PINs in a password manager. Label the physical keys (for example, a small sticker reading "1" or "2") so the primary and backup are distinguishable.
Enroll services in a deliberate order
Register both keys with each service as you go. Recommended enrollment order:
- Primary identity provider (UMS Microsoft Entra account, personal Microsoft account, Google account, Apple Account).
- Code hosting and developer accounts (GitHub, GitLab).
- Password manager (1Password, Bitwarden, etc.).
- All remaining services that support security keys.
For each service, save the backup or recovery codes to a password manager during enrollment. Where the service offers both options, prefer FIDO2 or WebAuthn registration over the legacy Universal 2nd Factor (U2F) path.
Verify the configuration
After setup, confirm the state of the key:
ykman info
ykman fido info
ykman piv info
ykman fido info reports the PIN status and how many resident credential slots are in use. ykman piv info reports the PIN retry count and the configured slots.
Additional resources
Environment
- YubiKey 5 Series
- YubiKey Manager (
ykman) command-line tool
- Windows, macOS, and Linux