Introduction

This guide explains how to use the PasskeyManager class to register a new passkey within your iOS application. We’ll cover the necessary configurations and provide code examples with detailed explanations.

Prerequisites

Before integrating passkey registration, ensure the following prerequisites are met. You may proceed to the Passkey Registration section if you have already configured the associated domains and the app site association file.

Associated Domains Entitlement

Your app must have the Associated Domains capability enabled. This allows your app to access passkeys stored in the user’s iCloud Keychain. Ensure that your domain supports HTTPS and is properly configured.

1. In Xcode, select your project and navigate to the Signing & Capabilities tab.
2. Click the + Capability button and add Associated Domains.
3. Add your domain to the Associated Domains section, prefixed with webcredentials:. For example:

webcredentials:your.domain.com

Reference: Apple Developer Documentation - Supporting Associated Domains

Apple App Site Association File

Your domain must host an apple-app-site-association file that specifies the app identifiers allowed to access credentials. The file should be available at:

https://your.domain.com/.well-known/apple-app-site-association

The content of the file should include the webcredentials service, as shown:

{
  "webcredentials": {
    "apps": ["<your-app-prefix>.<your-app-bundle-id>"]
  }
}

Replace <your-app-prefix> and <your-app-bundle-id> with your actual App ID prefix and bundle identifier.

Passkey Registration

Once the prerequisites are in place, you can proceed to implement passkey registration using PasskeyManager.

1. Import Required Modules

   At the top of your ViewController or relevant class, import the necessary modules:

   ViewController.swift

   import UIKit
   import AuthenticationServices
   import Shared  // Import Shared to use PasskeyManager
   import TurnkeySDK    // Import TurnkeySDK to use TurnkeyClient
   
2. Initialize PasskeyManager

   Create an instance of PasskeyManager, providing the Relying Party Identifier and the presentation anchor.

   ViewController.swift

   class ViewController: UIViewController {
       var passkeyManager: PasskeyManager?
       override func viewDidLoad() {
           super.viewDidLoad()
           // Additional setup if needed
       }
       // ... rest of the class
   }
   
3. Set Up User Interface

   Implement a method to initiate passkey registration, typically triggered by a user action such as tapping a button.

   The PasskeyManager requires two parameters:

   • rpId: The relying party identifier, typically your domain. This must match the domain configured in the Associated Domains entitlement and the apple-app-site-association file.
   • presentationAnchor: The window in which the authentication services will present UI, usually obtained from view.window.

   ViewController.swift

   ViewController.swift

   @IBAction func registerPasskeyTapped(_ sender: Any) {
       guard let window = view.window else {
           print("No window available")
           return
       }
   
       let rpId = "your.domain.com"  // Replace with your actual domain
       let email = "[e-mail]" // Replace with the user's email
   
       // Initialize PasskeyManager
       passkeyManager = PasskeyManager(rpId: rpId, presentationAnchor: window)
   
       // Register for passkey-related notifications
       // We'll define this method in the next step
       registerForPasskeyNotifications()
   
       // Start the passkey registration process
       passkeyManager?.registerPasskey(email: email)
   }
   
4. Register for Notifications

   To handle the results of the passkey registration process, register for the relevant notifications provided by PasskeyManager.

   ViewController.swift

   func registerForPasskeyNotifications() {
       NotificationCenter.default.addObserver(
           self,
           selector: #selector(passkeyRegistrationCompleted(_:)),
           name: .PasskeyRegistrationCompleted,
           object: nil
       )
       NotificationCenter.default.addObserver(
           self,
           selector: #selector(passkeyRegistrationFailed(_:)),
           name: .PasskeyRegistrationFailed,
           object: nil
       )
       NotificationCenter.default.addObserver(
           self,
           selector: #selector(passkeyRegistrationCanceled),
           name: .PasskeyRegistrationCanceled,
           object: nil
       )
   }
   
5. Cleanup

   Remove the observers when they are no longer needed to avoid memory leaks.

   ViewController.swift

   deinit {
       NotificationCenter.default.removeObserver(self)
   }
   
6. Implement Notification Handlers

   Define the methods that handle the passkey registration outcomes.

   ViewController.swift

   @objc func passkeyRegistrationCompleted(_ notification: Notification) {
       if let result = notification.userInfo?["result"] as? PasskeyRegistrationResult {
           // Handle successful registration
           print("Passkey registration completed.")
           print("Challenge: \(result.challenge)")
           print("Credential ID: \(result.attestation.credentialId)")
           // Send result to your server for verification and storage
       }
   }
   
   @objc func passkeyRegistrationFailed(_ notification: Notification) {
       if let error = notification.userInfo?["error"] as? PasskeyRegistrationError {
           // Handle registration failure
           print("Passkey registration failed with error: \(error.localizedDescription)")
           // Display an error message or take appropriate action
       }
   }
   
   @objc func passkeyRegistrationCanceled() {
       // Handle user cancellation
       print("Passkey registration was canceled by the user.")
       // Update UI or take appropriate action
   }
   

Sign Up New User

After successful passkey registration, use the PasskeyRegistrationResult to sign up a new user by creating a sub-organization using the TurnkeyClient from the TurnkeySDK.

1. Initialize TurnkeyClient with Proxy

   When handling the completion of passkey registration, set up the TurnkeyClient with a proxy server URL using the ProxyMiddleware. This configuration is essential for situations where the parent organization’s API keys are required to authenticate requests for creating a sub-organization. Your backend should relay the request to the Turnkey API, ensuring it is authenticated with the parent organization’s API keys.

   ViewController.swift

   func signUpWithPasskey(with passkeyRegistrationResult: PasskeyRegistrationResult) {
       Task {
           do {
               // Initialize the TurnkeyClient with a proxy server URL
               let turnkeyClient = TurnkeyClient(proxyURL: "https://your-proxy-server.com/api/turnkey-proxy")
   
               // Proceed to the next substep...
   
           } catch {
               print("Error signing up new user: \(error)")
               // Handle error appropriately
           }
       }
   }
   

   The middleware adds an X-Turnkey-Request-Url header to each request, which contains the original request URL. For more details, see the Proxy Middleware guide.

2. Attestation Object

   Construct the attestation object using the PasskeyRegistrationResult.

   ViewController.swift

   let attestation = Components.Schemas.Attestation(
       credentialId: passkeyRegistrationResult.attestation.credentialId,
       clientDataJson: passkeyRegistrationResult.attestation.clientDataJson,
       attestationObject: passkeyRegistrationResult.attestation.attestationObject,
       transports: [.AUTHENTICATOR_TRANSPORT_BLE]  // Adjust transports as needed
   )
   
3. Define Parameters

   Set up the necessary parameters for the sub-organization and root user. We’ll use the passkeyRegistrationResult we received in the previous step to create a passkey authenticator for this new sub-organization.

   ViewController.swift

   let parentOrganizationId = "your-parent-organization-id"
   let subOrganizationName = "New Sub Organization"
   
   // This should come from the user's input
   let email = "[e-mail]"
   
   let rootUsers: [Components.Schemas.RootUserParamsV4] = [
       .init(
           userName: email,
           userEmail: email,
           apiKeys: [],
           authenticators: [
               .init(
                   // We use the passkey registration result to create the authenticator
                   authenticatorName: "Passkey",
                   challenge: passkeyRegistrationResult.challenge,
                   attestation: attestation
               )
           ],
           oauthProviders: []
       )
   ]
   
   let rootQuorumThreshold: Int32 = 1
   
   // Create an Ethereum wallet for the new sub-organization
   let wallet = Components.Schemas.WalletParams(
       walletName: "Default Wallet",
       accounts: [
           .init(
               curve: .CURVE_SECP256K1,
               pathFormat: .PATH_FORMAT_BIP32,
               path: "m/44'/60'/0'/0/0",
               addressFormat: .ADDRESS_FORMAT_ETHEREUM
           )
       ]
   )
   
   // Set optional parameters
   let disableEmailRecovery = false
   let disableEmailAuth = false
   let disableSmsAuth = false
   let disableOtpEmailAuth = false
   
4. Create Sub-Organization

   Use the TurnkeyClient to create the sub-organization with the provided parameters.

   ViewController.swift

   let output = try await turnkeyClient.createSubOrganization(
       organizationId: parentOrganizationId, // Organization ID can be empty when using proxy
       subOrganizationName: subOrganizationName,
       rootUsers: rootUsers,
       rootQuorumThreshold: rootQuorumThreshold,
       wallet: wallet,
       disableEmailRecovery: disableEmailRecovery,
       disableEmailAuth: disableEmailAuth,
       disableSmsAuth: disableSmsAuth,
       disableOtpEmailAuth: disableOtpEmailAuth
   )
   
5. Handle the Response

   Process the response from the createSubOrganization call to retrieve information about the new sub-organization and root users.

   ViewController.swift

   // Handle the response
   switch output {
   case let .ok(response):
       switch response.body {
       case let .json(activityResponse):
           if let result = activityResponse.activity.result.createSubOrganizationResultV7 {
               print("Created sub-organization: \(result.subOrganizationId ?? "Unknown ID")")
               if let rootUserIds = result.rootUserIds {
                   print("Created root users: \(rootUserIds)")
               }
               // Proceed with additional setup or navigation as needed
           }
       }
   case let .undocumented(statusCode, undocumentedPayload):
       if let body = undocumentedPayload.body {
           let bodyString = try await String(decoding: body, as: UTF8.self)
           print("Undocumented response body: \(bodyString)")
       }
       print("Undocumented response: \(statusCode)")
   }
   

References

• Apple Developer Documentation - Supporting Passkeys
• Apple Developer Documentation - ASAuthorizationController
• Apple Developer Documentation - ASAuthorizationPlatformPublicKeyCredentialProvider