WebAuthn Transports: Internal and Hybrid Transport

Passkeys for Super Funds and Financial Institutions
Join our Webinar on 7th November to learn how Super Funds and Financial Institutions can implement passkeys

Join now

Note: Per WebAuthn specification, empty transports means all transports are supported.

When implementing passkeys across platforms, developers face an important decision:

• How should you handle WebAuthn transports, especially internal and hybrid transports, to ensure optimal cross-device authentication experiences?

The answer lies in understanding WebAuthn transports-a technical detail that determines how authenticators communicate with relying parties. While transports seem straightforward in theory, their implementation varies significantly across web browsers, native iOS, and native Android applications, particularly for internal and hybrid transport handling.

This article examines how WebAuthn transports work across different platforms and presents two distinct approaches to handling internal and hybrid transports-each with its own trade-offs.

This article covers:

1. WebAuthn transports: internal, hybrid, and platform authenticators across web, iOS, and Android
2. Two approaches: spec-compliant vs. optimized internal and hybrid transport handling
3. Cross-device authentication implementation best practices and recommendations

WebAuthn transports define the communication methods between authenticators and client devices. The WebAuthn Level 3 specification defines six transport types:

usb: Used by hardware security keys that connect via USB ports, such as YubiKeys or other FIDO2 security tokens.

nfc: Enables communication with authenticators through Near Field Communication, allowing users to tap their security keys or NFC-enabled devices.

ble: Facilitates authentication via Bluetooth Low Energy, enabling wireless communication with external authenticators.

smart-card: Used for smart card readers, allowing authentication via smart cards.

hybrid: Enables cross-device authentication, typically where a user scans a QR code to authenticate across devices-such as using a phone to authenticate on a desktop browser, or vice versa. This transport can trigger QR code prompts on both desktop and mobile devices, which may not always be desirable depending on the context. Note: hybrid was added in WebAuthn Level 3.

internal: The authenticator is embedded within the device itself-like iCloud Keychain (verified via Face ID or Touch ID) on iPhones, Windows Hello on PCs, or Google Password Manager on Android devices. These are platform authenticators.

When a passkey is created, the authenticator signals which transports it supports. This information gets sent to the relying party (your backend), which should persist it alongside the credential. During authentication, the relying party sends these transports back to the client in the allowCredentials list, helping the browser or platform determine which authentication methods to offer the user.

Transport handling differs significantly across platforms, creating the compatibility challenges developers face.

Browsers receive transport information from authenticators and honor it during authentication flows. When you create a passkey in Chrome, Safari, or Edge, the browser's credential manager provides transport data that varies based on the underlying authenticator:

Platform authenticators: Windows Hello provides ["internal"] only, reflecting its device-bound nature. However, when Chrome uses Google Password Manager as the authenticator, it provides ["internal", "hybrid"] because Google Password Manager supports cross-device authentication via Android Phones.

Hardware security keys: Provide specific transports like ["usb", "nfc"] based on their actual capabilities.

Cloud-synced credential managers: iCloud Keychain in Safari and Google Password Manager in Chrome typically provide ["internal", "hybrid"] to support both local and cross-device authentication flows.

This information flows reliably in web contexts, though the specific transports depend on which authenticator the browser selects for credential storage.

Documentation: W3C WebAuthn Specification

Android's Credential Manager API behaves similarly to web browsers. When creating passkeys in native Android apps, the Credential Manager provides transport information that mirrors web behavior-platform authenticators report their capabilities accurately, and the system handles transport data consistently. Android developers can rely on this information without special handling.

Documentation: Android Credential Manager

iOS presents a more complex situation. Apple's AuthenticationServices framework handles transports differently depending on the authenticator type:

Platform authenticators (iCloud Keychain, verified via Face ID or Touch ID): Often return empty transport arrays during passkey creation. This doesn't mean the passkey lacks transport capabilities-it simply means iOS doesn't report them explicitly. According to the WebAuthn standard, leaving out transports means any transport is acceptable, so hybrid authentication will still work.

Security keys: Do provide transport information (e.g., ["usb"], ["nfc"]) when used with iOS devices, following the expected pattern.

Documentation: Apple AuthenticationServices

Developers face a choice: follow the specification strictly, or optimize internal and hybrid transports for user experience. Each approach has merits and drawbacks.

This approach aligns with the WebAuthn specification: use transports exactly as provided by the authenticator during credential registration, and send them back unchanged during authentication.

Implementation: When a passkey is created, persist the transports array from the authenticator response. During authentication, include these exact transports in the allowCredentials list:

{
  "allowCredentials": [
    {
      "id": "credential-id-base64",
      "type": "public-key",
      "transports": ["internal", "hybrid"]
    }
  ]
}

Advantages:

• Specification compliance: Follows WebAuthn standards precisely, ensuring compatibility with future platform updates
• Security key reliability: Works perfectly for hardware security keys (YubiKeys, etc.) which always provide accurate transport information
• Prevents invalid options: Avoids offering authentication methods that genuinely aren't supported-for example, won't trigger QR codes for Windows Hello credentials

Disadvantages:

• iOS empty array behavior: Platform authenticators on iOS return empty transports, which per spec means "any transport"-this may show all authentication options including security keys
• May show unwanted options: Could present security key options (USB, NFC) in consumer applications where they're not expected
• Inconsistent user experience: Different platforms offer different authentication options for the same account

Best for: Applications prioritizing standards compliance, enterprise environments with diverse authenticator types.

This approach prioritizes user experience by selectively modifying internal and hybrid transports based on specific optimization goals. Rather than a blanket rule, consider these common optimization scenarios:

Problem: iOS platform authenticators return empty transport arrays. When left empty or filled by backends, users might see security key prompts (USB, NFC) alongside platform options, creating confusion in consumer applications.

Solution: Explicitly set transports to ["hybrid", "internal"] for iOS platform authenticators. This ensures only platform authentication and cross-device flows are offered, hiding security key options.

// When persisting iOS platform authenticator credentials
if (platform === "iOS" && authenticatorAttachment === "platform") {
  transports = ["hybrid", "internal"];
}

Result: Clean authentication UI without security key prompts for iOS-created passkeys.

Problem: When authenticating on mobile devices, showing QR codes for cross-device authentication creates poor UX-users are already on a mobile device with their passkeys available.

Solution: Remove hybrid transport when the user is authenticating from a mobile device, leaving only ["internal"].

// When building allowCredentials for authentication
const transports = isMobileDevice 
  ? credentials.transports.filter(t => t !== "hybrid")
  : credentials.transports;

Result: Mobile users see only direct authentication options without unnecessary QR code prompts.

⚠️ Caution: Transport manipulation doesn't always produce consistent results across platforms. Extensive testing shows that browser and OS combinations handle transports differently:

• Some platforms show QR codes even when hybrid is excluded from transports
• Others hide QR codes even when hybrid is included
• Behavior varies significantly between Chrome, Edge, Safari, and Firefox across Windows, macOS, and iOS

Risk of deadends: Overly restrictive transport filtering can create authentication deadends where users cannot log in at all. For example, removing hybrid might prevent legitimate cross-device authentication scenarios where a user needs to authenticate from a borrowed device. Always provide fallback authentication methods and test thoroughly across your target platforms before deploying transport optimizations.

These are optimization hints: WebAuthn provides other mechanisms to optimize authentication UX beyond transport manipulation-such as hints.

Transport behavior is unpredictable: Cross-device authentication (CDA) via hybrid transport exhibits inconsistent behavior across browser and OS combinations. Real-world testing demonstrates that transport values don't guarantee specific UI behavior-platforms interpret and handle transports differently, leading to unexpected results.

Platform-specific complexity: When explicitly controlling transports, you must account for platform differences:

• iOS: Sends empty arrays for platform authenticators; requires filling
• Windows Hello: Must remain ["internal"] only; adding hybrid triggers unwanted QR codes
• Web & Android: Generally provide accurate transport information
• CDA variations: QR code prompts may appear or disappear regardless of hybrid presence in transports array

End-to-end understanding required: Explicitly controlling transports means taking responsibility for the entire flow. You must understand how each transport combination behaves across all your target platforms and test thoroughly. Transport manipulation can create authentication deadends where no valid authentication path exists for users.

Advantages:

• Tailored UX: Control exactly which authentication options users see in specific contexts
• Solves iOS empty array issue: Explicitly defines transports where iOS provides none
• Context-aware optimization: Adapt authentication UI based on device type

Disadvantages:

• Unpredictable behavior: Transport manipulation doesn't guarantee consistent UI behavior-extensive testing shows platforms interpret transports differently, sometimes showing or hiding options regardless of transport values
• Risk of authentication deadends: Overly restrictive transport filtering can prevent users from authenticating entirely, especially in cross-device scenarios
• Deviates from specification: Moves away from spec recommendations, potentially causing issues with future platform changes
• Maintenance burden: Requires ongoing platform-specific logic and updates as platforms evolve
• Complexity: Must handle iOS empty arrays, Windows Hello constraints, and other platform quirks manually
• Testing overhead: Every optimization rule needs verification across all platform combinations

Best for: Consumer applications with specific UX requirements, teams with resources to maintain platform-specific logic, scenarios prioritizing streamlined authentication flows over strict spec compliance.

WebAuthn transport handling doesn't exist in isolation-it's one piece of your overall passkey implementation strategy. Two common approaches emerge in production deployments, each with different implications for internal and hybrid transport usage.

This approach prioritizes flexibility and standards compliance, allowing users to authenticate with any compatible authenticator.

Implementation Characteristics:

• Authentication UI: Passkey button appears alongside existing login options (username/password)
• allowCredentials: Set to empty array [], allowing any credential to match
• Authenticator types: Security keys, cross-device authentication (QR codes), platform authenticators all supported
• Native app requirements: Must support all authentication methods, including security keys
• preferImmediatelyAvailableCredentials: Cannot be used, as it excludes security keys and QR code logins by definition
• Transport handling: Must accommodate all transport types, including security key transports (usb, nfc, ble)

Transport Implications:

With empty allowCredentials, transports become less critical during authentication-the platform shows all available options. However, this means users may see security key prompts, QR codes, and platform options simultaneously, which can create decision paralysis in consumer applications.

Best for: Enterprise environments, applications with diverse user bases requiring security key support, scenarios prioritizing maximum authentication flexibility.

This approach optimizes for consumer UX by restricting passkey creation to platform authenticators and using identifier-first flows.

Implementation Characteristics:

• Passkey creation: Only platform authenticators allowed via authenticatorAttachment: "platform"
• Authentication flow: Identifier-first-users enter email/username before authentication
• allowCredentials: Populated with user's specific credentials (not empty) once identifier is known
• Authenticator types: Platform authenticators and cross-device authentication; security keys typically excluded
• Native app optimization: Can use preferImmediatelyAvailableCredentials, which excludes security keys and cross-device authentication by definition
• Cross-device authentication: Available on web; not available when using preferImmediatelyAvailableCredentials in native apps, but this scenario is rare (users typically have passkeys on the device they're using)
• Transport handling: Focused on internal and hybrid transports only

Transport Implications:

Since allowCredentials contains specific credentials with their transports, transport handling becomes crucial.

Best for: Consumer applications, native mobile apps, scenarios prioritizing streamlined UX over authenticator flexibility, platforms where identifier-first flows already exist.

For platforms that already leak account existence or use identifier-first flows (user enters email before seeing login options), the consumer-tailored approach aligns naturally. Once the user has provided their identifier:

1. Backend queries for existing passkeys
2. Returns allowCredentials with specific credentials and their transports
3. Platform can optimize authentication UI based on transports
4. No additional account enumeration risk (identifier already provided)

In these scenarios, transports can become optimization tool rather than a security concern. You can tailor authentication options based on device context (mobile vs. desktop) and credential capabilities.

Recommendation: For platforms that already use identifier-first flows or where account enumeration isn't a concern, the consumer-tailored approach with explicit transport handling provides superior UX, especially in native mobile applications where preferImmediatelyAvailableCredentials enables seamless biometric authentication.

Regardless of which approach you choose for handling internal and hybrid transports, follow these practices to minimize issues:

Persist Transports During Registration: Always store the transports array from the authenticator response alongside the credential ID and public key. This data is essential for authentication flows.

Handle Empty Arrays Gracefully: When receiving an empty transport array from iOS platform authenticators:

• Spec-compliant: Leave empty or omit transports property-means "any transport" is acceptable
• Optimization approach: Fill with ["internal", "hybrid"] to control which authentication options are shown

Test Across All Target Platforms: Create a testing matrix covering all combinations:

• Registration: Web, iOS Native, Android Native
• Authentication: Web, iOS Native, Android Native
• Verify QR codes appear when expected and are hidden when inappropriate

Understand Empty Array vs. Missing Property: Both an empty transports array [] and a missing transports property are typically treated as "any transport is acceptable" according to the specification. However, implementation details vary across platforms.

Monitor Platform Changes: WebAuthn implementations evolve. Apple, Google, and Microsoft regularly update their authenticator behaviors. Stay informed about changes that might affect transport handling.

WebAuthn transports-especially internal and hybrid transports-are technical details with significant practical impact on cross-device authentication. Your transport handling strategy should align with your broader passkey implementation approach and target platforms.

Transport Decisions Live Within Broader Strategy: How you handle transports depends on whether you're building for maximum flexibility (empty allowCredentials) or consumer UX (identifier-first with specific credentials). The latter makes transports critical for optimization.

Platform Differences Require Handling: Web and Android provide reliable transport information, while iOS platform authenticators return empty arrays. Windows Hello sends only ["internal"]. Understanding these differences is essential for production deployments.

Two Valid Transport Approaches: Spec-compliant (trust authenticator transports) works well for enterprise and maximum flexibility scenarios. Explicit control (optimize transports) suits consumer applications with identifier-first flows and native mobile apps.

Identifier-First Enables Transport Optimization: When users provide their identifier first, transport handling becomes a powerful UX tool. You can prevent unwanted QR codes on mobile, hide security key options, and streamline authentication-without additional account enumeration concerns.

For Enterprise / Maximum Flexibility:

• Use empty allowCredentials to support all authenticator types
• Trust authenticator-provided transports
• Accept that users see more authentication options
• Simpler implementation, broader compatibility

For Consumer Applications / Native Apps:

• Implement identifier-first authentication flow
• Restrict to platform authenticators (authenticatorAttachment: "platform")
• Use allowCredentials with specific credentials and optimized transports
• Enable preferImmediatelyAvailableCredentials in native apps
• Fill iOS empty arrays with ["hybrid", "internal"]
• Filter hybrid on mobile devices to prevent QR codes
• Superior UX with streamlined authentication options

For Platforms with Identifier-First Flows Already:

• Account enumeration is already a non-issue
• Consumer-tailored approach aligns naturally with existing UX
• Transport optimization provides immediate UX benefits
• Recommended approach for most consumer applications

Start spec-compliant, then optimize based on your strategy:

1. Persist transports exactly as received during registration
2. Decide your overall strategy (maximum flexibility vs. consumer-tailored)
3. If consumer-tailored: implement identifier-first flow and optimize transports
4. Handle iOS empty arrays appropriately for your chosen strategy
5. Test thoroughly across Web, iOS Native, and Android Native platforms

The WebAuthn landscape continues evolving. Platform vendors regularly update their implementations, and specifications like WebAuthn Level 3 introduce new capabilities. Building flexible systems that align transport handling with your broader authentication strategy ensures your passkey implementation remains robust and provides excellent user experiences as the ecosystem matures.