Getting started on iOS


bulb-light-icon.svg Tip: If you are a developer looking to add YubiKey / Security Key support to your iOS / iPadOS application, refer to this site for more information.

Introduction

manual-icon.svg Note:  This article covers basic YubiKey / Security Key use on iOS and iPadOS. For information such as can I log into my service on iOS/iPadOS, consult the Works with YubiKey catalog or reach out to the service directly for more information. Yubico does not provide or maintain setup documentation for most third party products or services.

Depending on the iOS/iPadOS hardware as well as the YubiKey or Security Key model, there are three methods for using a YubiKey with iOS/iPadOS.

  • The YubiKey 5Ci can connect directly to an iOS/iPadOS device via a Lightning connector
  • The YubiKey 5 NFC, YubiKey NEO, and Security Key NFC can be used over NFC on NFC-enabled iPhones.**
  • Any YubiKey model can be plugged either directly into an iOS/iPadOS device or using an adapter* to take advantage of both the OTP functionality, as well as WebAuthn*. Note: If using Yubico Authenticator on iPadOS, version 16.1 of iPadOS must be installed to leverage this functionality.

*Please note that we do not recommend using adapters, but do understand that adapters are sometimes unavoidable. In any case, we would advise you to try an adapter from a reliable, trust-worthy brand.

**
iOS/iPadOS and Safari version 13.3 or newer is required to leverage native support for WebAuthn (e.g. iPhone 6s and iPhone 6s Plus or newer iPhones, and IPad Air 2 or newer, iPad 5th generation or newer, and any iPad Pro model are capable).

exclamation-triangle-icon.svg Warning: Depending on the service you're attempting to use, as well as the model and method of connecting your YubiKey to iOS/iPadOS, your desired use case may not be supported. The Works With YubiKey catalog is intended to list all known YubiKey integrations, including what devices the integration is supported on. Instructions for how to add and use the YubiKey with the service is also linked from every integration in the Works with YubiKey catalog. Please consult this list to determine if your use case is supported on iOS/iPadOS. If you discover that a service supports the YubiKey but isn't located in the catalog, reach out either by opening a support case here or by scrolling down to the bottom of this page and clicking Send us feedback on this article.

Using your YubiKey 5Ci on iOS/iPadOS

The YubiKey 5Ci allows for direct connection to iOS/iPadOS devices with a Lightning port. Some models that use this port include (but are not limited to) iPhone SE, iPhone 7, iPhone 8, iPhone X, and most modern iPads (not including the newest iPad Pro, which uses a USB-C port). The functionality of the 5Ci is limited to Yubico OTP and WebAuthn without an app that specifically supports the YubiKey 5Ci over Lightning, such as 1Password and LastPass. Here's a list of iOS/iPadOS integrations that are known to work with your YubiKey 5Ci. Yubico offers the Yubico Authenticator application for iOS/iPadOS to store and generate TOTP codes (compatible with the 5Ci, YubiKey 5 NFC, and YubiKey NEO).

When using the YubiKey 5Ci without one of the above mentioned apps, the key is a capable touch-triggered Yubico OTP device and security key. The touch-triggered experience on iOS/iPadOS is very similar to a desktop. After connecting the YubiKey 5Ci to your iOS/iPadOS device, you can short press (1 second) any metal contact to activate the credential, which then begins typing out the Yubico OTP 44-character string. WebAuthn (e.g. "security key") support is also provided in the Brave and Safari (beginning with iOS/iPadOS 13.3) browsers.

Testing WebAuthn using YubiKey 5Ci on iOS/iPadOS

If you would like to test your YubiKey on iOS/iPadOS using WebAuthn, follow the steps below:

  1. Connect your YubiKey to your iOS/iPadOS device via the Lightning connector.
  2. Wait until the green light in the touch button is blinking, indicating the iOS/iPadOS device has detected the YubiKey.
  3. If a dialog box appears with the message “The connected device is not supported” the first time the YubiKey is plugged into your device, simply tap OK to exit the dialog box.
  4. Open Safari and browse to https://demo.yubico.com/webauthn-technical/registration.
  5. Tap NEXT.
  6. Following the instructions in the prompt, touch the metal contact on your YubiKey.
  7. Verify it succeeded with "Registration successful" message.

Using Yubico Authenticator to add accounts and generate codes with a YubiKey 5Ci

Yubico Authenticator for iOS can be used to store TOTP and HOTP accounts, as well as to generate codes to authenticate to services that support "authenticator apps." Basic account adding and code generation is covered below. Note: Once an HOTP/TOTP account is stored on the YubiKey, it can be accessed on any version of Yubico Authenticator where the YubiKey is plugged in (e.g. you can store an account using Yubico Authenticator for iOS and then access the accounts code on an Android phone using Yubico Authenticator for Android, or on a Windows/MacOS/Linux desktop or laptop running Yubico Authenticator for Desktop). Since the secret is stored on the YubiKey, generating a code requires both the YubiKey and the Yubico Authenticator. Since the secret cannot be extracted once it is added to a YubiKey, it is important to consider account recovery and "backups" before you add an account to the YubiKey. Backups cannot be made after authenticator app setup for any given service is completed without going through the setup process again.

Adding accounts

To add accounts to your YubiKey using Yubico Authenticator for iOS, follow the process below

  1. Download and install Yubico Authenticator for iOS, available in the App Store for any iPhone/iPad with a Lightning port (not supported on iPads with USB-C ports).
  2. Open Yubico Authenticator for iOS.
  3. Plug in a YubiKey 5Ci
  4. On another device, set up the service you are trying to secure with an authenticator app. Continue until the service provides a QR code (if you need assistance with the authenticator app setup process for a service, please refer to the service's setup instructions.
  5. In Yubico Authenticator for iOS, tap the + button at the top right
  6. Tap Scan QR code. If a pop-up appears requesting permission to access the camera, tap Allow.
  7. Point the iPhone/iPad's camera at the QR code on the other device until the QR code is read. The iPhone/iPad should vibrate and a "New Account" screen should appear.
  8. Tap Save.
    • At this point, if you wish to store the same account on a second YubiKey in your possession, simply repeat steps 3-7 for each YubiKey. Alternatively, if you wish to add this account to another YubiKey but don't have one currently, you can save a copy of the QR code (or secret key) in a safe place to scan and add later.
  9. Use the current code displayed in Yubico Authenticator for iOS for this account to complete setup of the account on the other device.

Generating codes

To generate codes for accounts stored on your YubiKey using Yubico Authenticator for iOS, follow the process below:

  1. Open Yubico Authenticator for iOS.
  2. Plug in a YubiKey 5Ci. All current TOTP codes should be displayed. If an account you added uses HOTP, or if you set the TOTP account to "require touch", you will first have to tap the credential (and then tap the gold YubiKey contact, if prompted) to display the current code.

Using your YubiKey 5 NFC, YubiKey NEO, or Security Key NFC on iOS/iPadOS

exclamation-triangle-icon.svg Warning: The Security Key Series supports WebAuthn (e.g. "security key") functionality only. OTP and storing authenticator credentials in Yubico Authenticator are not supported with the Security Key Series.

Just like the YubiKey 5Ci over Lightning, any NFC-Enabled YubiKey can be used with iOS (not available in iPadOS, since iPads do not have NFC capabilities) for passing Yubico OTP codes via NFC on an iPhone 7 and above. In addition, native NFC support for WebAuthn was added to Safari browser in iOS version 13.3. Yubico Authenticator also supports storing TOTP accounts and generating codes using the YubiKey 5 NFC or YubiKey NEO over NFC. If you want to use an NFC-Enabled YubiKey on iOS for anything other than Yubico OTP or WebAuthn or with Yubico Authenticator, you'll need to use (or build) an app or browser that specifically supports NFC communication with a YubiKey. 

 

Testing WebAuthn using YubiKey 5 NFC, YubiKey NEO, or Security Key NFC on iOS

If you would like to test your NFC-capable Yubico device on iOS using WebAuthn, follow the steps below:

  1. Open Safari and browse to https://demo.yubico.com/webauthn-technical/registration.
  2. Tap NEXT.
  3. Following the prompt, tap and hold your NFC-capable Yubico device to the top of your phone.
  4. Verify it succeeded with "Registration successful" message.

Using Yubico Authenticator to add accounts and generate codes with a YubiKey 5 NFC or YubiKey NEO

Yubico Authenticator for iOS can be used to store TOTP and HOTP accounts, as well as to generate codes to authenticate to services that support "authenticator apps." Basic account adding and code generation is covered below. Note: Once an HOTP/TOTP account is stored on the YubiKey, it can be accessed on any version of Yubico Authenticator where the YubiKey is plugged in (e.g. you can store an account using Yubico Authenticator for iOS and then access the accounts code on an Android phone using Yubico Authenticator for Android, or on a Windows/MacOS/Linux desktop or laptop running Yubico Authenticator for Desktop). Since the secret is stored on the YubiKey, generating a code requires both the YubiKey and the Yubico Authenticator. Since the secret cannot be extracted once it is added to a YubiKey, it is important to consider account recovery and "backups" before you add an account to the YubiKey. Backups cannot be made after authenticator app setup for any given service is completed without going through the setup process again.

Adding accounts

To add accounts to your YubiKey using Yubico Authenticator for iOS, follow the process below

  1. Download and install Yubico Authenticator for iOS, available in the App Store for any iPhone/iPad with a Lightning port (not supported on iPads with USB-C ports).
  2. Open Yubico Authenticator for iOS.
  3. On another device, set up the service you are trying to secure with an authenticator app. Continue until the service provides a QR code (if you need assistance with the authenticator app setup process for a service, please refer to the service's setup instructions.
  4. In Yubico Authenticator for iOS, tap the + button at the top right
  5. Tap Scan QR code. If a pop-up appears requesting permission to access the camera, tap Allow.
  6. Point the iPhone/iPad's camera at the QR code on the other device until the QR code is read. The iPhone/iPad should vibrate and a "New Account" screen should appear.
  7. Tap Save. A "Ready to Scan" pop-up should appear.
  8. Tap and hold your NFC-capable YubiKey to your phone's NFC antenna (typically at the top-rear of the phone). A checkmark will appear if the account is securely added to the YubiKey
    • At this point, if you wish to store the same account on a second YubiKey in your possession, simply repeat steps 4-8 for each YubiKey. Alternatively, if you wish to add this account to another YubiKey but don't have one currently, you can save a copy of the QR code (or secret key) in a safe place to scan and add later.
  9. Use the current code displayed in Yubico Authenticator for iOS for this account to complete setup of the account on the other device. With an NFC capable YubiKey, only one set of codes will be generated each time you tap the YubiKey to your phone. If the service doesn't accepted the current code, try swiping down from the top of the Yubico Authenticator application which will prompt you to rescan your YubiKey (and provide a new code).

Generating codes

To generate codes for accounts stored on your YubiKey using Yubico Authenticator for iOS, follow the process below:

  1. Open Yubico Authenticator for iOS.
  2. Pull down from below the Quick Find search box (as if you are trying to "refresh"). This will initiate the prompt to scan an NFC-capable YubiKey. All current TOTP codes should be displayed. If an account you added uses HOTP, or if you set the TOTP account to "require touch", you will first have to tap the credential, and then you will be required to scan your YubiKey again to generate the code.

Using other YubiKey / Security Key models on iOS/iPadOS

manual-icon.svg Note: While the functions discussed below are now supported natively in iOS and iPadOS, the service you are authenticating to also needs to incorporate logic to make these features possible on these mobile operating systems. This native functionality also only applies to the functionality listed, so in cases where the YubiKey iOS SDK is used, support for the desired protocol may still not be supported using this connection method. (Example: Yubico Authenticator will ONLY work with the YubiKey 5Ci, YubiKey 5 NFC, and YubiKey NEO, as the OATH functionality of the YubiKey is only compatible with Apple's NFC and Lightning interfaces on iOS and iPadOS.)

Historically, USB security devices have had limited capabilities when plugged into iOS/iPadOS devices. Beginning in iOS/iPadOS version 13.3, some functions have been enabled that affect USB security devices when plugged into the iPhone/iPad's USB port (either directly, or in cases where the device plug doesn't match the USB port type, using an adapter):

(1) The WebAuthn protocol is now natively supported in iOS and iPadOS through the Safari browser

(2) The YubiKey's button-press one-time password functionality (where the YubiKey emulates a USB keyboard to type in a one-time password or static password, depending on the YubiKey's configuration.


Testing WebAuthn using a YubiKey or Security Key plugged directly into the USB port, or via an adapter

If you would like to test your YubiKey or Security Key on iOS/iPadOS using WebAuthn, follow the steps below:

  1. Connect your YubiKey or Security Key to your iOS/iPadOS device either directly (if the port and plug are compatible) or using an adapter.
  2. Wait until the LED on the YubiKey or Security Key appears, indicating the iOS/iPadOS device has detected the YubiKey.
  3. If a dialog box appears with the message “The connected device is not supported” the first time the YubiKey is plugged into your device, simply tap OK to exit the dialog box.
  4. Open Safari and browse to https://demo.yubico.com/webauthn-technical/registration.
  5. Tap NEXT.
  6. Following the instructions in the prompt, touch the metal contact on your YubiKey.
  7. Verify it succeeded with "Registration successful" message.