fix(experience): invoke webauthn on iOS devices (#4770)

packages/experience/src/hooks/use-webauthn-operation.ts

@@ -10,7 +10,7 @@ import type {
   RegistrationResponseJSON,
   AuthenticationResponseJSON,
 } from '@simplewebauthn/typescript-types';
-import { useCallback } from 'react';
+import { useCallback, useEffect, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 
 import {
@@ -33,6 +33,9 @@ const isAuthenticationResponseJSON = (
 const useWebAuthnOperation = (flow: UserMfaFlow) => {
   const { t } = useTranslation();
   const { setToast } = useToast();
+  const [webAuthnOptions, setWebAuthnOptions] = useState<
+    WebAuthnRegistrationOptions | WebAuthnAuthenticationOptions
+  >();
 
   const asyncCreateRegistrationOptions = useApi(createWebAuthnRegistrationOptions);
   const asyncGenerateAuthnOptions = useApi(generateWebAuthnAuthnOptions);
@@ -52,6 +55,45 @@ const useWebAuthnOperation = (flow: UserMfaFlow) => {
     [setToast, t]
   );
 
+  /**
+   * Note:
+   * Due to limitations in the iOS system, user interaction is required for the use of the WebAuthn API.
+   * Therefore, we should avoid asynchronous operations before invoking the WebAuthn API.
+   * Otherwise, the operating system may consider the WebAuthn authorization is not initiated by the user.
+   * So, we need to prepare the necessary WebAuthn options before calling the WebAuthn API.
+   */
+  const prepareWebAuthnOptions = useCallback(async () => {
+    if (webAuthnOptions) {
+      return;
+    }
+
+    const [error, options] =
+      flow === UserMfaFlow.MfaBinding
+        ? await asyncCreateRegistrationOptions()
+        : await asyncGenerateAuthnOptions();
+
+    if (error) {
+      await handleError(error);
+      return;
+    }
+
+    setWebAuthnOptions(options);
+  }, [
+    asyncCreateRegistrationOptions,
+    asyncGenerateAuthnOptions,
+    flow,
+    handleError,
+    webAuthnOptions,
+  ]);
+
+  useEffect(() => {
+    if (webAuthnOptions) {
+      return;
+    }
+
+    void prepareWebAuthnOptions();
+  }, [prepareWebAuthnOptions, webAuthnOptions]);
+
   const handleWebAuthnProcess = useCallback(
     async (options: WebAuthnRegistrationOptions | WebAuthnAuthenticationOptions) => {
       const parsedOptions = webAuthnRegistrationOptionsGuard.safeParse(options);
@@ -68,21 +110,17 @@ const useWebAuthnOperation = (flow: UserMfaFlow) => {
   );
 
   return useCallback(async () => {
-    const [error, options] =
-      flow === UserMfaFlow.MfaBinding
-        ? await asyncCreateRegistrationOptions()
-        : await asyncGenerateAuthnOptions();
+    if (!webAuthnOptions) {
+      /**
+       * This error message is just for program robustness; in practice, this issue is unlikely to occur.
+       */
+      setToast(t('mfa.webauthn_not_ready'));
+      void prepareWebAuthnOptions();
 
-    if (error) {
-      await handleError(error);
       return;
     }
 
-    if (!options) {
-      return;
-    }
-
-    const response = await handleWebAuthnProcess(options);
+    const response = await handleWebAuthnProcess(webAuthnOptions);
 
     if (!response) {
       return;
@@ -96,14 +134,7 @@ const useWebAuthnOperation = (flow: UserMfaFlow) => {
         ? { flow: UserMfaFlow.MfaVerification, payload: { ...response, type: MfaFactor.WebAuthn } }
         : { flow: UserMfaFlow.MfaBinding, payload: { ...response, type: MfaFactor.WebAuthn } }
     );
-  }, [
-    asyncCreateRegistrationOptions,
-    asyncGenerateAuthnOptions,
-    flow,
-    handleError,
-    handleWebAuthnProcess,
-    sendMfaPayload,
-  ]);
+  }, [handleWebAuthnProcess, prepareWebAuthnOptions, sendMfaPayload, setToast, t, webAuthnOptions]);
 };
 
 export default useWebAuthnOperation;

packages/integration-tests/src/tests/experience/mfa/backup-code/index.test.ts

@@ -50,7 +50,7 @@ describe('MFA - Backup Code', () => {
     experience.toBeAt('register/password');
     await experience.toFillNewPasswords(password);
     experience.toBeAt('mfa-binding/WebAuthn');
-    await experience.toClick('button', 'Create a passkey');
+    await experience.toCreatePasskey();
 
     // Backup codes page
     const backupCodes = await experience.retrieveBackupCodes();

packages/integration-tests/src/tests/experience/mfa/webauthn/index.test.ts

@@ -50,8 +50,7 @@ describe('MFA - WebAuthn', () => {
     await experience.toFillInput('identifier', username, { submit: true });
     experience.toBeAt('register/password');
     await experience.toFillNewPasswords(password);
-    experience.toBeAt('mfa-binding/WebAuthn');
-    await experience.toClick('button', 'Create a passkey');
+    await experience.toCreatePasskey();
     await experience.verifyThenEnd(false);
 
     await experience.startWith(demoAppUrl, 'sign-in');
@@ -64,8 +63,7 @@ describe('MFA - WebAuthn', () => {
     );
     // Wait for the page to process submitting request.
     await waitFor(500);
-    experience.toBeAt('mfa-verification/WebAuthn');
-    await experience.toClick('button', 'Verify via passkey');
+    await experience.toVerifyViaPasskey();
 
     await experience.clearVirtualAuthenticator();
     const userId = await experience.getUserIdFromDemoAppPage();
@@ -88,8 +86,7 @@ describe('MFA - WebAuthn', () => {
     );
     // Wait for the page to process submitting request.
     await waitFor(500);
-    experience.toBeAt('mfa-binding/WebAuthn');
-    await experience.toClick('button', 'Create a passkey');
+    await experience.toCreatePasskey();
 
     await experience.clearVirtualAuthenticator();
     await experience.verifyThenEnd();

packages/integration-tests/src/ui-helpers/expect-webauthn-experience.ts

@@ -49,6 +49,20 @@ export default class ExpectWebAuthnExperience extends ExpectExperience {
     });
   }
 
+  async toCreatePasskey() {
+    this.toBeAt('mfa-binding/WebAuthn');
+    // Wait for the WebAuthn options have been prepared.
+    await this.page.waitForNetworkIdle();
+    await this.toClick('button', 'Create a passkey');
+  }
+
+  async toVerifyViaPasskey() {
+    this.toBeAt('mfa-verification/WebAuthn');
+    // Wait for the WebAuthn options have been prepared.
+    await this.page.waitForNetworkIdle();
+    await this.toClick('button', 'Verify via passkey');
+  }
+
   private async getCdpClient() {
     if (!this._cdpClient) {
       this._cdpClient = await this.page.target().createCDPSession();

packages/phrases-experience/src/locales/de/mfa.ts

@@ -50,6 +50,8 @@ const mfa = {
     'Verwenden Sie den Passwort-Schlüssel zur Verifizierung über Ihr Gerätepasswort oder Biometrie, scannen Sie den QR-Code oder verwenden Sie eine USB-Sicherheitsschlüssel wie YubiKey.',
   secret_key_copied: 'Geheimer Schlüssel kopiert.',
   backup_code_copied: 'Sicherungscode kopiert.',
+  /** UNTRANSLATED */
+  webauthn_not_ready: 'WebAuthn is not ready yet. Please try again later.',
 };
 
 export default Object.freeze(mfa);

packages/phrases-experience/src/locales/en/mfa.ts

@@ -49,6 +49,7 @@ const mfa = {
     'Use passkey to verify by your device password or biometrics, scanning QR code, or using USB security key like YubiKey.',
   secret_key_copied: 'Secret key copied.',
   backup_code_copied: 'Backup code copied.',
+  webauthn_not_ready: 'WebAuthn is not ready yet. Please try again later.',
 };
 
 export default Object.freeze(mfa);

packages/phrases-experience/src/locales/es/mfa.ts

@@ -49,6 +49,8 @@ const mfa = {
     'Use la clave de acceso para verificar mediante la contraseña de su dispositivo o biometría, escanee el código QR o use una llave de seguridad USB como YubiKey.',
   secret_key_copied: 'Clave secreta copiada.',
   backup_code_copied: 'Código de respaldo copiado.',
+  /** UNTRANSLATED */
+  webauthn_not_ready: 'WebAuthn is not ready yet. Please try again later.',
 };
 
 export default Object.freeze(mfa);

packages/phrases-experience/src/locales/fr/mfa.ts

@@ -49,6 +49,8 @@ const mfa = {
     "Utilisez la clé d'accès pour vérifier votre mot de passe de l'appareil ou la biométrie, numérisez le code QR ou utilisez une clé de sécurité USB telle que YubiKey.",
   secret_key_copied: 'Clé secrète copiée.',
   backup_code_copied: 'Code de sauvegarde copié.',
+  /** UNTRANSLATED */
+  webauthn_not_ready: 'WebAuthn is not ready yet. Please try again later.',
 };
 
 export default Object.freeze(mfa);

packages/phrases-experience/src/locales/it/mfa.ts

@@ -49,6 +49,8 @@ const mfa = {
     "Usa la chiave di accesso per verificarti tramite la password del dispositivo o la biometria, la scansione del codice QR o l'uso di una chiave di sicurezza USB come YubiKey.",
   secret_key_copied: 'Chiave segreta copiata.',
   backup_code_copied: 'Codice di backup copiato.',
+  /** UNTRANSLATED */
+  webauthn_not_ready: 'WebAuthn is not ready yet. Please try again later.',
 };
 
 export default Object.freeze(mfa);

packages/phrases-experience/src/locales/ja/mfa.ts

@@ -49,6 +49,8 @@ const mfa = {
     'デバイスのパスワードまたはバイオメトリック、QRコードのスキャン、YubiKeyなどのUSBセキュリティキーを使用して確認するためにパスキーを使用します。',
   secret_key_copied: 'シークレットキーがコピーされました。',
   backup_code_copied: 'バックアップコードがコピーされました。',
+  /** UNTRANSLATED */
+  webauthn_not_ready: 'WebAuthn is not ready yet. Please try again later.',
 };
 
 export default Object.freeze(mfa);

packages/phrases-experience/src/locales/ko/mfa.ts

@@ -47,6 +47,8 @@ const mfa = {
     '디바이스 비밀번호 또는 생체 인증, QR 코드 스캔 또는 YubiKey와 같은 USB 보안 키를 사용하여 확인하기 위해 패스키를 사용하세요.',
   secret_key_copied: '비밀 키 복사됨.',
   backup_code_copied: '백업 코드 복사됨.',
+  /** UNTRANSLATED */
+  webauthn_not_ready: 'WebAuthn is not ready yet. Please try again later.',
 };
 
 export default Object.freeze(mfa);

packages/phrases-experience/src/locales/pl-pl/mfa.ts

@@ -49,6 +49,8 @@ const mfa = {
     'Użyj klucza dostępu do weryfikacji za pomocą hasła urządzenia lub biometrii, skanowania kodu QR lub użycia klucza bezpieczeństwa USB, takiego jak YubiKey.',
   secret_key_copied: 'Skopiowano klucz prywatny.',
   backup_code_copied: 'Skopiowano kod zapasowy.',
+  /** UNTRANSLATED */
+  webauthn_not_ready: 'WebAuthn is not ready yet. Please try again later.',
 };
 
 export default Object.freeze(mfa);

packages/phrases-experience/src/locales/pt-br/mfa.ts

@@ -49,6 +49,8 @@ const mfa = {
     'Use a chave de acesso para verificar por meio da senha do seu dispositivo ou biometria, escaneando o código QR ou usando uma chave de segurança USB como a YubiKey.',
   secret_key_copied: 'Chave secreta copiada.',
   backup_code_copied: 'Código de backup copiado.',
+  /** UNTRANSLATED */
+  webauthn_not_ready: 'WebAuthn is not ready yet. Please try again later.',
 };
 
 export default Object.freeze(mfa);

packages/phrases-experience/src/locales/pt-pt/mfa.ts

@@ -49,6 +49,8 @@ const mfa = {
     'Utilize a chave de acesso para verificar através da senha do seu dispositivo ou biometria, digitalizando o código QR ou utilizando uma chave de segurança USB como a YubiKey.',
   secret_key_copied: 'Chave secreta copiada.',
   backup_code_copied: 'Código de backup copiado.',
+  /** UNTRANSLATED */
+  webauthn_not_ready: 'WebAuthn is not ready yet. Please try again later.',
 };
 
 export default Object.freeze(mfa);

packages/phrases-experience/src/locales/ru/mfa.ts

@@ -49,6 +49,8 @@ const mfa = {
     'Используйте ключ доступа для верификации с помощью пароля вашего устройства или биометрии, сканирования QR-кода или использования USB-ключа безопасности, такого как YubiKey.',
   secret_key_copied: 'Секретный ключ скопирован.',
   backup_code_copied: 'Резервный код скопирован.',
+  /** UNTRANSLATED */
+  webauthn_not_ready: 'WebAuthn is not ready yet. Please try again later.',
 };
 
 export default Object.freeze(mfa);

packages/phrases-experience/src/locales/tr-tr/mfa.ts

@@ -49,6 +49,8 @@ const mfa = {
     'Cihazınızın şifresi veya biyometrisi, QR kodunu tarayarak veya YubiKey gibi bir USB güvenlik anahtarı kullanarak doğrulama için anahtar kodunu kullanın.',
   secret_key_copied: 'Gizli anahtar kopyalandı.',
   backup_code_copied: 'Yedek kodu kopyalandı.',
+  /** UNTRANSLATED */
+  webauthn_not_ready: 'WebAuthn is not ready yet. Please try again later.',
 };
 
 export default Object.freeze(mfa);

packages/phrases-experience/src/locales/zh-cn/mfa.ts

@@ -44,6 +44,8 @@ const mfa = {
     '使用 Passkey 通过设备密码或生物识别、扫描 QR 码或使用类似 YubiKey 的 USB 安全密钥进行验证。',
   secret_key_copied: '已复制秘钥。',
   backup_code_copied: '已复制备用码。',
+  /** UNTRANSLATED */
+  webauthn_not_ready: 'WebAuthn is not ready yet. Please try again later.',
 };
 
 export default Object.freeze(mfa);

packages/phrases-experience/src/locales/zh-hk/mfa.ts

@@ -44,6 +44,8 @@ const mfa = {
     '使用 Passkey 通過設備密碼或生物識別、掃描 QR 碼或使用類似 YubiKey 的 USB 安全金鑰進行驗證。',
   secret_key_copied: '已複製秘密金鑰。',
   backup_code_copied: '已複製備用碼。',
+  /** UNTRANSLATED */
+  webauthn_not_ready: 'WebAuthn is not ready yet. Please try again later.',
 };
 
 export default Object.freeze(mfa);

packages/phrases-experience/src/locales/zh-tw/mfa.ts

@@ -44,6 +44,8 @@ const mfa = {
     '使用 Passkey 進行驗證，以通過您的設備密碼或生物辨識、掃描 QR 碼或使用 USB 安全金鑰（例如 YubiKey）進行驗證。',
   secret_key_copied: '已複製秘密金鑰。',
   backup_code_copied: '已複製備用碼。',
+  /** UNTRANSLATED */
+  webauthn_not_ready: 'WebAuthn is not ready yet. Please try again later.',
 };
 
 export default Object.freeze(mfa);