1. Yubico
  2. Business
  3. Guides

Getting Started on iOS

Avatar
Clay Degruchy
Created - Updated

Introduction

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 maintain setup documentation for 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: Yubico Authenticator does not support this option** if you're not running iPadOS 16.1 and the latest version of the Yubico Authenticator***

*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 13.3 and Safari are required to leverage native support for WebAuthn.

 

***iOS/iPadOS is only able to communicate with the YubiKey's OATH application (required for Yubico Authenticator functionality) via NFC and Lightning. Since the one-time passwords generated by Yubico Authenticator are time-based, and the YubiKey does not have the ability to track time (due to its lack of a battery), proper functionality requires iOS/iPadOS being able to both write to and read from the YubiKey (it sends the YubiKey the current time and receives the one-time password). Read/write is possible over NFC due to Apple's recent expansion, and via Lightning due to the YubiKey 5Ci's MFi certification, but not using other connection methods, namely USB-C, which has replaced the Lightning connector on third-generation and later iPad Pros. At this time, there is no way to use Yubico Authenticator on these iPads, as they do not support NFC.

 

For developers, the Yubico Mobile iOS SDK (software development kit) can be integrated into your apps to enable the YubiKey 5Ci and NFC-enabled YubiKeys to interact with iOS apps beyond the basic functionality covered in this document (e.g. OpenPGP, PIV, Challenge-Response, etc.).

Important note: 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 (via https://yubi.co/support) 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 Yubico OTP using YubiKey 5Ci on iOS/iPadOS

If you would like to test your YubiKey on iOS/iPadOS using Yubico OTP, 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/otp/verify.
  5. Tap on the text field just above the VALIDATE button. This should bring up the virtual keyboard.
  6. Touch the metal contact on your YubiKey. The YubiKey will type the 44-character OTP string into the text field and send it to the server.
  7. Verify it succeeded with "OTP is valid" message.

Note: If the One-Time Password verification fails and begins with a capital letter, check to be sure you have turned off auto-capitalization in the iOS/iPadOS preferences. This setting is turned on by default. To turn it off, go to Settings > General > Keyboards, and slide the setting to turn off Auto-Capitalization.

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:

Using Brave browser

  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 Brave 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 Safari browser

  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

Note: The Security Key NFC supports WebAuthn (e.g. "security key") functionality only. OTP and Yubico Authenticator are not supported with the Security Key NFC.

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 Yubico OTP over NFC on iOS

Using iPhone XS and newer

If you have an iPhone that supports background NFC NDEF tag reading (requires iPhone XS and later) and would like to test your NFC-enabled YubiKey (Security Key NFC not supported) on iOS, follow the steps below:

  1. Hold the YubiKey 5 NFC or YubiKey NEO to the top of your phone or near the camera (you may need to experiment with positioning depending on phone model).
  2. Tap the "WEBSITE NFC TAG" taking you to a shortcut URL in iOS Safari. You should see your Yubico OTP code pasted into the field. 
  3. Tap VALIDATE.
  4. The OTP code is passed to the YubiCloud OTP validation server. Verify that you see "Validation Successful".

Using iPhone 7 - iPhone X

The iPhone 7 - iPhone X model phones do not support background NFC NDEF tag reading (requires iPhone XS and later) so a third party companion application is required to use OTPs. (Security Key NFC not supported) Follow the steps below:

  1. Install AuthLite NFC, available in the App Store.
  2. Open the AuthLite NFC app.
    • If you see a "Ready to scan" pop-up, tap your YubiKey to your iPhone
    • If you do not see a "Ready to scan" pop-up, tap "Read OTP Again". The "Ready to scan" pop-up will appear, then tap your YubiKey to your iPhone.
  3. To test the OTP, tap "Validate OTP in Browser" (if you're intending to use the credential with a service, or you've programmed an alternative credential over NDEF, you can simply paste the output into the desired application).
  4. In your preferred mobile browser, go to https://demo.yubico.com/otp/verify
  5. Paste the OTP into the field above the VALIDATE button, and then tap VALIDATE.
  6. The OTP code is passed to the YubiCloud OTP validation server. Verify that you see "Validation Successful".

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

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 Yubico OTP using a YubiKey plugged directly into the USB port, or via an adapter

Note: Security Key models do not support this function.

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

  1. Connect your YubiKey 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 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 your preferred web browser and go to https://demo.yubico.com/otp/verify.
  5. Tap on the text field just above the VALIDATE button. This should bring up the virtual keyboard.
  6. Touch the metal contact on your YubiKey. The YubiKey will type the 44-character OTP string into the text field and send it to the server.
  7. Verify it succeeded with "OTP is valid" message.

Note: If the One-Time Password verification fails and begins with a capital letter, check to be sure you have turned off auto-capitalization in the iOS/iPadOS preferences. This setting is turned on by default. To turn it off, go to Settings > General > Keyboards, and slide the setting to turn off Auto-Capitalization.

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.