iOS hybrid transport

This page explains how to set up your iOS app to support hybrid authentication (cross-device authentication) using the Mobile FIDO SDK.

Prerequisites

Before you set up hybrid authentication, you must configure app groups for your application. App groups enable the SDK to share data between your main app and extensions.

Implement hybrid authentication

Configure app groups

First, configure the app groups for your application:

// Configure the app groups
TGFFido2Config.setAppGroup("group.com.example.appgroup")

Enable passkeys extension

Guide the end users to enable this setting when they first set up your app for hybrid authentication.

Users need to enable your passkeys extension in their iOS settings:

1. On iOS, open the Settings app.
2. Navigate to Apps.
3. Tap Passwords
4. Tap AutoFill Passwords.
5. In the list, enable your app's passkeys extension.

Set up the credential provider extension

In iOS 17 and above, the system camera automatically recognizes WebAuthn QR codes and prompts the end user to select an app to create or sign in with their passkey.

The Mobile FIDO SDK provides a ready-to-use Mobile FIDO UI SDK to simplify the implementation of a credential provider extension for hybrid authentication. You can leverage these components to quickly set up your extension.

Use the Mobile FIDO UI SDK

The Mobile FIDO UI SDK provides two key classes for handling hybrid authentication:

1. TGFCredentialProviderViewController is a base class that inherits from ASCredentialProviderViewController to handle the Credential Provider hybrid authentication flow.

2. TGFFido2AutofillViewController manages the FIDO2 operations and UI for authentication and registration.

To implement your credential provider extension:

1. In your Xcode project, create a new AutoFill Credential Provider extension target.

   

2. In your extension's view controller, use subclass TGFCredentialProviderViewController.

3. Configure the Mobile FIDO SDK with your app groups identifier. Ensure that the same identifier reflected on the app's entitlements file.

import AuthenticationServices
import Fido2
import Fido2Ui

class CredentialProviderViewController: TGFCredentialProviderViewController {

    required init?(coder: NSCoder) {
        super.init(coder: coder)
        setupConfigurations()
    }

    // MARK: - Fido2 Configuration
    private func setupConfigurations() {
        TGFFido2Config.setupSecureLog(nil)
        TGFFido2Config.setAppGroup("group.com.example.appgroup")
    }
}

With this implementation, the app extension automatically supports the hybrid authentication flow with minimal additional code.

To test hybrid authentication:

1. Set up a test website that supports WebAuthn and hybrid authentication (for example, webauthn.io).

2. On a desktop browser, initiate registration or authentication.

3. Select the option to use another device.

   A QR code is displayed in the browser.

4. On your iOS 17+ device, open the camera app and scan the QR code.

5. When iOS recognizes the WebAuthn QR code and prompts you, select where to save or use a passkey.

   Your extension launches and handles the WebAuthn request using the Mobile FIDO UI SDK.

6. When prompted, complete the user verification process.

7. Verify that the authentication and registration completes successfully on the browser.

Hybrid flow overview

The hybrid flow observed on iOS is as follows:

1. Enable passkeys: Users need to turn on passkeys for the app in their iOS settings.

2. Scan the QR code: Users scan the authentication QR code with their device camera.

3. Choose your app: The system prompts users to select the app to save or use the passkey.

4. Authenticate: Users complete authentication using biometric or passcode verification.

Troubleshooting

• Passkey extension not appearing: Ensure that the app extension is properly enabled in the iOS settings and that the correct entitlements are provided.

• QR code not recognized: Ensure that the device is running on iOS 17 or later and that the QR code is a valid WebAuthn request.

• Data migration failures: If data migration fails, it might be necessary to reset the SDK state using TGFFido2Client.reset() and guide users through re-registering their credentials.

• App groups configuration: Verify that the app groups identifier matches exactly between the app's entitlements, app extension's entitlements, and SDK configuration.