Transportes WebAuthn: Transporte interno e híbrido

Whitepaper empresarial de Passkeys. Guias práticos, padrões de implementação e KPIs para programas de passkeys.

Obter whitepaper

Nota: De acordo com a especificação WebAuthn, uma sequência de transportes vazia significa que as informações de transporte estão indisponíveis ou retidas por motivos de privacidade. Muitas vezes tratado pelos navegadores como se todos os transportes fossem possíveis.

Ao implementar chaves de acesso em várias plataformas, os desenvolvedores enfrentam uma decisão importante:

• Como você deve lidar com os transportes WebAuthn, especialmente os transportes interno (internal) e híbrido (hybrid), para garantir experiências ideais de autenticação entre dispositivos?

A resposta está na compreensão dos transportes WebAuthn — um detalhe técnico que determina como os autenticadores se comunicam com as partes confiáveis (relying parties). Embora os transportes pareçam simples na teoria, sua implementação varia significativamente em navegadores da web, aplicativos iOS nativos e aplicativos Android nativos, particularmente para o tratamento de transportes interno e híbrido.

Este artigo examina como os transportes WebAuthn funcionam em diferentes plataformas e apresenta duas abordagens distintas para lidar com transportes interno e híbrido - cada uma com suas próprias vantagens e desvantagens.

Este artigo aborda:

1. Transportes WebAuthn: interno, híbrido e autenticadores de plataforma em web, iOS e Android
2. Duas abordagens: tratamento de transporte interno e híbrido compatível com a especificação vs. otimizado
3. Melhores práticas e recomendações de implementação de autenticação entre dispositivos

Os transportes WebAuthn definem os métodos de comunicação entre autenticadores e dispositivos clientes. A especificação WebAuthn Level 3 define seis tipos de transporte:

usb: Usado por chaves de segurança de hardware que se conectam via portas USB, como YubiKeys ou outros tokens de segurança FIDO2.

nfc: Permite a comunicação com autenticadores através do Near Field Communication, permitindo que os usuários aproximem suas chaves de segurança ou dispositivos com NFC.

ble: Facilita a autenticação via Bluetooth Low Energy, permitindo a comunicação sem fio com autenticadores externos.

smart-card: Usado para leitores de cartão inteligente, permitindo a autenticação por meio de cartões inteligentes.

hybrid: Permite a autenticação entre dispositivos, normalmente onde um usuário escaneia um código QR para autenticar entre dispositivos - como usar um telefone para autenticar em um navegador de desktop ou vice-versa. Este transporte pode acionar prompts de código QR em dispositivos móveis e desktops, o que pode não ser sempre desejável dependendo do contexto. Nota: hybrid foi adicionado no WebAuthn Level 3.

internal: O autenticador está embutido no próprio dispositivo - como o iCloud Keychain (verificado via Face ID ou Touch ID) em iPhones, Windows Hello em PCs ou Google Password Manager em dispositivos Android. Esses são autenticadores de plataforma.

Quando uma chave de acesso é criada, o autenticador sinaliza quais transportes ele suporta. Esta informação é enviada para a parte confiável (seu backend), que deve persisti-la junto com a credencial. Durante a autenticação, a parte confiável envia esses transportes de volta ao cliente na lista allowCredentials, ajudando o navegador ou a plataforma a determinar quais métodos de autenticação oferecer ao usuário.

O manuseio do transporte difere significativamente entre as plataformas, criando os desafios de compatibilidade que os desenvolvedores enfrentam.

Os navegadores recebem informações de transporte dos autenticadores e as honram durante os fluxos de autenticação. Quando você cria uma chave de acesso no Chrome, Safari ou Edge, o gerenciador de credenciais do navegador fornece dados de transporte que variam de acordo com o autenticador subjacente:

Autenticadores de plataforma: O Windows Hello fornece ["internal"] apenas, refletindo sua natureza vinculada ao dispositivo. No entanto, quando o Chrome usa o Google Password Manager como autenticador, ele fornece ["internal", "hybrid"] porque o Google Password Manager suporta autenticação entre dispositivos por meio de telefones Android.

Chaves de segurança de hardware: Fornecem transportes específicos como ["usb", "nfc"] com base em suas capacidades reais.

Gerenciadores de credenciais sincronizados na nuvem: O iCloud Keychain no Safari e o Google Password Manager no Chrome normalmente fornecem ["internal", "hybrid"] para suportar fluxos de autenticação locais e entre dispositivos.

Esta informação flui de forma confiável em contextos da web, embora os transportes específicos dependam de qual autenticador o navegador seleciona para o armazenamento de credenciais.

Documentação: Especificação W3C WebAuthn

A API Credential Manager do Android se comporta de maneira semelhante aos navegadores da web. Ao criar chaves de acesso em aplicativos Android nativos, o Credential Manager fornece informações de transporte que espelham o comportamento da web — os autenticadores de plataforma relatam seus recursos com precisão, e o sistema lida com os dados de transporte de forma consistente. Os desenvolvedores Android podem confiar nessas informações sem tratamento especial.

Documentação: Android Credential Manager

O iOS apresenta uma situação mais complexa. A estrutura AuthenticationServices da Apple lida com transportes de forma diferente, dependendo do tipo de autenticador:

Autenticadores de plataforma (iCloud Keychain, verificados via Face ID ou Touch ID): Frequentemente retornam arrays de transporte vazios durante a criação de chaves de acesso. Isso indica que as informações de transporte estão indisponíveis ou retidas por motivos de privacidade - de acordo com a especificação WebAuthn, os user agents podem retornar sequências vazias quando as informações de transporte são desconhecidas ou para preservar a privacidade. As partes confiáveis devem tratar os transportes como dicas e não como garantias.

Chaves de segurança: Fornecem informações de transporte (por exemplo, ["usb"], ["nfc"]) quando usadas com dispositivos iOS, seguindo o padrão esperado.

Documentação: Apple AuthenticationServices

Dados de produção do mundo real de aplicativos nativos e web revelam os seguintes padrões de transporte, ordenados por frequência. Observe que essas distribuições são influenciadas por especificidades de implementação e dados demográficos do cliente (uso móvel vs. desktop, disponibilidade de aplicativos nativos), mas fornecem informações valiosas sobre o uso típico de transporte:

Principais insights:

Autenticadores de plataforma dominam: A grande maioria das chaves de acesso usa transporte internal, muitas vezes combinado com hybrid para suporte a autenticação entre dispositivos. Isso reflete o foco do consumidor em autenticadores de plataforma (iCloud Keychain, Google Password Manager).

Arrays vazios são comuns: Os aplicativos nativos do iOS retornam frequentemente arrays de transporte vazios para autenticadores de plataforma, representando uma parte significativa das credenciais de produção. Conforme discutido na seção 2.2.3, estes indicam informações de transporte indisponíveis em vez de suporte de transporte abrangente.

Chaves de segurança são raras: Chaves de segurança de hardware (usb, nfc) representam uma pequena fração das chaves de acesso de produção, indicando seu uso primário em cenários empresariais ou de alta segurança em vez de aplicativos de consumidor.

Existem variações de ordem: A ordem dos transportes em arrays (["internal", "hybrid"] vs ["hybrid", "internal"]) varia de acordo com a plataforma e a implementação do autenticador, mas não traz nenhuma diferença funcional - ambas indicam suporte para os mesmos métodos de transporte.

Terminologia legada: O identificador de transporte cable aparece ocasionalmente em implementações mais antigas e é sinônimo de hybrid (caBLE = cloud-assisted Bluetooth Low Energy, o nome original para o transporte híbrido).

Essa distribuição reforça a importância de lidar corretamente com os transportes internal e hybrid, pois eles respondem pela esmagadora maioria das implementações de chaves de acesso no mundo real.

A disponibilidade de transporte mostra o que os autenticadores relatam, não se o fluxo resultante foi concluído. A análise de conclusão de autenticação entre dispositivos do Corbado Passkey Benchmark 2026 mede a conclusão do transporte hybrid no primeiro trimestre de 2026 em 60–78% na web do Windows e 66–86% na web do macOS no geral, dividindo em 79–98% (Win) / 83–98% (macOS) para nudges no mesmo dispositivo versus 52–67% (Win) / 59–76% (macOS) para fluxos focados no identificador. Trate o hybrid como o transporte de maior custo na lógica de roteamento e prefira fluxos que mantenham o usuário no dispositivo que contém a credencial.

O mesmo autenticador muitas vezes relata padrões de transporte diferentes com base na plataforma, versão e contexto de implementação. Essa variação é normal e esperada:

iCloud Keychain exibe três padrões:

• ["internal", "hybrid"] - Mais comum, normalmente de navegadores web
• [] (array vazio) - Muito comum, de aplicativos nativos iOS
• ["hybrid", "internal"] - Menos comum, variação de ordem
• Apenas ["internal"] ou ["hybrid"] - Casos extremos raros

Google Password Manager mostra mais variações:

• ["hybrid", "internal"] - Padrão mais comum
• ["internal", "hybrid"] - Ordem alternativa comum
• ["internal", "cable"] - Implementações legadas (cable = termo antigo para híbrido)
• [] (array vazio) - De determinados contextos nativos
• Transportes únicos raramente

Windows Hello é mais consistente:

• ["internal"] - Padrão dominante (vinculado ao dispositivo por design)

Gerenciadores de senhas como 1Password, Bitwarden, Dashlane e LastPass mostram todos padrões de variação semelhantes:

• Ambas as ordens ["internal", "hybrid"] e ["hybrid", "internal"]
• Arrays vazios [] de contextos de aplicativos nativos
• Ocasionalmente apenas ["internal"]

Samsung Pass (ecossistema Android) usa principalmente:

• ["hybrid", "internal"] e ["internal", "hybrid"] - Ambas as ordens são comuns

Diferenças de plataforma: O mesmo autenticador se comporta de maneira diferente na web vs nativo, iOS vs Android ou Windows vs macOS.

Evolução da versão: Os relatórios de transporte evoluíram ao longo do tempo. Versões mais antigas podem usar cable em vez de hybrid, ou relatar combinações diferentes.

Escolhas de implementação: Alguns autenticadores priorizam o internal primeiro, outros o hybrid. A ordem não tem impacto funcional, mas varia de acordo com a implementação.

Sensibilidade ao contexto: Os aplicativos nativos, especialmente no iOS, geralmente recebem arrays vazios mesmo de autenticadores que relatam transportes completos em contextos da web.

Principal lição: Não assuma que os arrays de transporte serão consistentes para um determinado autenticador. Projete sua implementação para lidar com todas as variações de forma otimizada, concentrando-se na presença de transportes específicos em vez da correspondência exata de array.

Os desenvolvedores enfrentam uma escolha: seguir a especificação estritamente ou otimizar os transportes interno e híbrido para a experiência do usuário. Cada abordagem tem méritos e desvantagens.

Essa abordagem se alinha à especificação WebAuthn: use os transportes exatamente como fornecidos pelo autenticador durante o registro da credencial e envie-os de volta inalterados durante a autenticação.

Implementação: Quando uma chave de acesso for criada, persista o array transports da resposta do autenticador. Durante a autenticação, inclua esses transportes exatos na lista allowCredentials:

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

Vantagens:

• Conformidade com a especificação: Segue os padrões WebAuthn com precisão, garantindo compatibilidade com atualizações futuras da plataforma
• Confiabilidade da chave de segurança: Funciona perfeitamente para chaves de segurança de hardware (YubiKeys, etc.) que sempre fornecem informações de transporte precisas
• Evita opções inválidas: Evita oferecer métodos de autenticação que genuinamente não são suportados - por exemplo, não acionará códigos QR para credenciais do Windows Hello

Desvantagens:

• Comportamento de array vazio do iOS: Os autenticadores de plataforma no iOS retornam transportes vazios, o que indica informações de transporte indisponíveis - as plataformas podem interpretar isso de forma diferente ao determinar quais opções de autenticação mostrar
• Pode mostrar opções indesejadas: Pode apresentar opções de chave de segurança (USB, NFC) em aplicativos de consumidor onde não são esperadas
• Experiência de usuário inconsistente: Diferentes plataformas oferecem diferentes opções de autenticação para a mesma conta

Melhor para: Aplicativos priorizando a conformidade com padrões, ambientes corporativos com diversos tipos de autenticadores.

Essa abordagem prioriza a experiência do usuário modificando seletivamente os transportes interno e híbrido com base em metas de otimização específicas. Em vez de uma regra geral, considere estes cenários de otimização comuns:

Problema: Os autenticadores de plataforma iOS retornam arrays de transporte vazios. Quando deixados vazios ou preenchidos pelos backends, os usuários podem ver prompts de chaves de segurança (USB, NFC) juntamente com as opções de plataforma, criando confusão em aplicativos de consumidor.

Solução: Defina os transportes explicitamente como ["hybrid", "internal"] para autenticadores de plataforma iOS. Isso garante que apenas as opções de autenticação da plataforma e fluxos entre dispositivos sejam oferecidos, ocultando as opções de chave de segurança.

// Ao persistir credenciais do autenticador da plataforma iOS
if (platform === "iOS" && authenticatorAttachment === "platform") {
    transports = ["hybrid", "internal"];
}

Resultado: Interface do usuário de autenticação limpa sem prompts de chave de segurança para chaves de acesso criadas no iOS.

Problema: Ao autenticar em dispositivos móveis, a exibição de códigos QR para autenticação entre dispositivos cria uma UX ruim - os usuários já estão em um dispositivo móvel com suas chaves de acesso disponíveis.

Solução: Remova o transporte hybrid quando o usuário estiver se autenticando em um dispositivo móvel, deixando apenas ["internal"].

// Ao construir allowCredentials para autenticação
const transports = isMobileDevice
    ? credentials.transports.filter((t) => t !== "hybrid")
    : credentials.transports;

Resultado: Os usuários de dispositivos móveis veem apenas opções de autenticação direta sem solicitações desnecessárias de código QR.

⚠️ Cuidado: A manipulação de transporte nem sempre produz resultados consistentes nas plataformas. Testes extensivos mostram que as combinações de navegador e sistema operacional lidam com transportes de maneira diferente:

• Algumas plataformas mostram códigos QR mesmo quando hybrid é excluído dos transportes
• Outros ocultam os códigos QR, mesmo que hybrid seja incluído
• O comportamento varia significativamente entre Chrome, Edge, Safari e Firefox no Windows, macOS e iOS

Risco de becos sem saída: A filtragem de transporte excessivamente restritiva pode criar becos sem saída na autenticação, onde os usuários não podem fazer login. Por exemplo, remover o hybrid pode impedir cenários legítimos de autenticação entre dispositivos, em que um usuário precisa se autenticar de um dispositivo emprestado. Sempre forneça métodos de autenticação de fallback e teste exaustivamente nas plataformas de destino antes de implementar otimizações de transporte.

Essas são dicas de otimização: O WebAuthn fornece outros mecanismos para otimizar a UX da autenticação além da manipulação de transporte, como hints.

O comportamento de transporte é imprevisível: A autenticação entre dispositivos (CDA) por meio do transporte hybrid exibe um comportamento inconsistente nas combinações de navegador e sistema operacional. Os testes do mundo real demonstram que os valores de transporte não garantem um comportamento específico da interface do usuário - as plataformas interpretam e lidam com os transportes de maneira diferente, levando a resultados inesperados.

Complexidade específica da plataforma: Ao controlar explicitamente os transportes, você deve levar em conta as diferenças de plataforma:

• iOS: Envia arrays vazios para autenticadores de plataforma; requer preenchimento
• Windows Hello: Deve permanecer ["internal"] apenas; adicionar hybrid aciona códigos QR indesejados
• Web e Android: Geralmente fornecem informações de transporte precisas
• Variações do CDA: Prompts de código QR podem aparecer ou desaparecer independentemente da presença de hybrid no array de transportes

Compreensão de ponta a ponta necessária: Controlar os transportes explicitamente significa assumir a responsabilidade por todo o fluxo. Você deve entender como cada combinação de transporte se comporta em todas as suas plataformas de destino e testar exaustivamente. A manipulação do transporte pode criar becos sem saída de autenticação onde nenhum caminho de autenticação válido existe para os usuários.

Vantagens:

• UX personalizada: Controle exatamente quais opções de autenticação os usuários veem em contextos específicos
• Resolve problema de array vazio no iOS: Define explicitamente transportes onde o iOS não fornece nenhum
• Otimização baseada no contexto: Adapte a interface do usuário da autenticação com base no tipo de dispositivo

Desvantagens:

• Comportamento imprevisível: A manipulação de transporte não garante um comportamento consistente da interface de usuário - testes extensivos mostram que as plataformas interpretam os transportes de maneira diferente, às vezes mostrando ou ocultando opções, independentemente dos valores do transporte
• Risco de becos sem saída na autenticação: Uma filtragem de transporte excessivamente restritiva pode impedir totalmente a autenticação dos usuários, especialmente em cenários entre dispositivos
• Desvia da especificação: Afasta-se das recomendações da especificação, potencialmente causando problemas com futuras alterações da plataforma
• Carga de manutenção: Requer atualizações e lógicas contínuas e específicas da plataforma à medida que as plataformas evoluem
• Complexidade: Deve lidar com matrizes vazias do iOS, restrições do Windows Hello e outras peculiaridades da plataforma manualmente
• Sobrecarga de testes: Toda regra de otimização precisa de verificação em todas as combinações de plataforma

Melhor para: Aplicativos de consumidor com requisitos de UX específicos, equipes com recursos para manter lógica específica de plataforma, cenários que priorizam fluxos de autenticação simplificados em vez de rigorosa conformidade com a especificação.

O manuseio do transporte WebAuthn não existe isoladamente - é uma parte da sua estratégia geral de implementação de chaves de acesso. Duas abordagens comuns surgem em implementações de produção, cada uma com implicações diferentes para o uso interno e híbrido de transporte.

Essa abordagem prioriza a flexibilidade e a conformidade com os padrões, permitindo que os usuários se autentiquem com qualquer autenticador compatível.

Características de implementação:

• Interface de usuário de autenticação: O botão de chave de acesso aparece ao lado das opções de login existentes (nome de usuário/senha)
• allowCredentials: Definido como array vazio [], permitindo que qualquer credencial corresponda
• Tipos de autenticadores: Chaves de segurança, autenticação entre dispositivos (códigos QR), autenticadores de plataforma, todos com suporte
• Requisitos de aplicativos nativos: Devem oferecer suporte a todos os métodos de autenticação, incluindo chaves de segurança
• preferImmediatelyAvailableCredentials: Não pode ser usado, pois exclui chaves de segurança e logins por código QR por definição
• Manuseio de transporte: Deve acomodar todos os tipos de transporte, incluindo transportes de chave de segurança (usb, nfc, ble)

Implicações de transporte:

Com allowCredentials vazio, os transportes se tornam menos críticos durante a autenticação - a plataforma mostra todas as opções disponíveis. No entanto, isso significa que os usuários podem ver prompts de chave de segurança, códigos QR e opções de plataforma simultaneamente, o que pode criar paralisia de decisão em aplicativos de consumidor.

Melhor para: Ambientes empresariais, aplicativos com bases de usuários diversas que exigem suporte a chaves de segurança, cenários que priorizam a máxima flexibilidade de autenticação.

Essa abordagem otimiza para a UX do consumidor, restringindo a criação de chaves de acesso a autenticadores de plataforma e usando fluxos focados no identificador.

Características da implementação:

• Criação de chave de acesso: Os prompts iniciados pelo usuário (prompts pós-login, fluxos de criação automáticos) usam authenticatorAttachment: "platform" para focar nos autenticadores disponíveis imediatamente
• Suporte de chave de segurança: Disponível por meio de configurações de conta da web sem restrição authenticatorAttachment, permitindo que os usuários avançados (power users) selecionem qualquer autenticador, incluindo chaves de segurança
• Fluxo de autenticação: Focado no identificador (identifier-first) - os usuários inserem e-mail/nome de usuário antes da autenticação
• allowCredentials: Preenchido com as credenciais específicas do usuário (não vazias) uma vez que o identificador é conhecido
• Tipos de autenticador: Autenticadores de plataforma e autenticação entre dispositivos priorizados; as chaves de segurança são suportadas, mas não promovidas nos fluxos primários
• Otimização de aplicativo nativo: Usa preferImmediatelyAvailableCredentials para autenticação instantânea e silenciosa, sem prompts para chaves de segurança ou códigos QR
• Autenticação entre dispositivos: Disponível na web; excluído intencionalmente em aplicativos nativos ao usar preferImmediatelyAvailableCredentials (os usuários normalmente se autenticam no dispositivo onde residem suas chaves de acesso)
• Manuseio de transporte: O foco principal está nos transportes internal e hybrid

Implicações de transporte:

Como allowCredentials contém credenciais específicas com seus transportes, o manuseio do transporte se torna crucial para otimizar as experiências de autenticação.

Realidade da chave de segurança: As chaves de segurança representam uma fração extremamente pequena do uso de chave de acesso em implantações de consumidor em grande escala — principalmente usuários avançados ou usuários com requisitos de segurança específicos. A abordagem adaptada ao consumidor reconhece essa realidade ao dar suporte às chaves de segurança sem otimizar os fluxos principais em torno delas.

Estratégia de criação em duas camadas: As implementações podem equilibrar a compatibilidade da chave de segurança com a experiência do consumidor (UX) otimizada por meio de caminhos duplos de criação:

• Nudges e prompts de usuários: Os prompts pós-login e fluxos de criação automáticos usam authenticatorAttachment: "platform", guiando os usuários em direção a chaves de acesso imediatamente disponíveis com altas taxas de sucesso
• Configurações da conta na web: Oferece a criação sem authenticatorAttachment, permitindo que os usuários avançados selecionem chaves de segurança, gerenciadores de senhas de terceiros ou qualquer autenticador disponível

Esse padrão aparece em implantações importantes: as chaves de segurança são suportadas e funcionais via configurações, mas os prompts voltados para o usuário otimizam para o caso de uso predominante — autenticadores de plataforma que fornecem autenticação silenciosa e instantânea.

Melhor para: Aplicativos de consumidor, aplicativos móveis nativos, cenários que priorizam a UX simplificada sobre a flexibilidade do autenticador, plataformas em que fluxos focados no identificador já existem.

Para plataformas que já vazam a existência da conta ou usam fluxos focados no identificador (o usuário insere o e-mail antes de ver as opções de login), a abordagem focada no consumidor se alinha naturalmente. Quando o usuário tiver fornecido o seu identificador:

1. O backend pesquisa chaves de acesso existentes
2. Retorna allowCredentials com credenciais específicas e seus transportes
3. A plataforma pode otimizar a interface do usuário de autenticação com base nos transportes
4. Nenhum risco adicional de enumeração de conta (identificador já fornecido)

Nesses cenários, os transportes podem se tornar uma ferramenta de otimização em vez de uma preocupação de segurança. Você pode adaptar as opções de autenticação com base no contexto do dispositivo (móvel versus desktop) e nos recursos da credencial.

Recomendação: Para plataformas que já usam fluxos focados no identificador ou onde a enumeração de contas não é uma preocupação, a abordagem voltada para o consumidor com manuseio de transporte explícito fornece UX superior, especialmente em aplicativos móveis nativos onde preferImmediatelyAvailableCredentials permite a autenticação biométrica sem atritos.

Independentemente de qual abordagem você escolher para lidar com transportes interno e híbrido, siga estas práticas para minimizar os problemas:

Persistir transportes durante o registro: Sempre guarde o array transports da resposta do autenticador junto ao ID da credencial e a chave pública. Esses dados são essenciais para os fluxos de autenticação.

Lide com arrays vazios de maneira suave: Ao receber um array de transporte vazio de autenticadores de plataforma iOS:

• Compatível com as especificações: Deixar vazio ou omitir a propriedade transports - indica que a informação de transporte está indisponível; as plataformas determinarão as opções disponíveis
• Abordagem de otimização: Preencha com ["internal", "hybrid"] para controlar quais opções de autenticação são mostradas

Estratégias de transporte para Web vs Nativo: Diferencie o manuseio do transporte com base no contexto:

• Autenticação Web: Inclui todos os transportes, permitindo um suporte de autenticador mais amplo, incluindo chaves de segurança por meio de USB/NFC
• Autenticação em aplicativo nativo: Use preferImmediatelyAvailableCredentials para autenticação silenciosa; transportes enviados conforme armazenados
• Páginas de configurações/gerenciamento: Suporte a todos os tipos de autenticadores para usuários avançados

Lidar com autenticação por chave de segurança: Quando os usuários tiverem chaves de segurança registradas:

• Web: Detectar transportes de chaves de segurança em credenciais armazenadas e garantir que os fluxos de autenticação possam acomodá-los
• Aplicativos nativos: Considere fornecer métodos de autenticação de fallback ou direcionar usuários à web para autenticação com chave de segurança
• Abordagem híbrida: Aplicativos nativos otimizam para autenticadores de plataforma enquanto a web oferece suporte à total flexibilidade de autenticadores

Teste em todas as plataformas de destino: Crie uma matriz de teste cobrindo todas as combinações:

• Registro: Web, iOS Nativo, Android Nativo
• Autenticação: Web, iOS Nativo, Android Nativo
• Verifique se a autenticação silenciosa funciona com preferImmediatelyAvailableCredentials
• Confirme que as chaves de segurança funcionam em fluxos de configurações sem authenticatorAttachment
• Valide que códigos QR aparecem apenas em contextos apropriados

Entenda a semântica de transporte: Reconheça as diferenças entre valores de transporte vazios e ausentes:

• Array de transportes vazio []: Indica que as informações de transporte estão indisponíveis ou retidas para privacidade. Os agentes do usuário podem fornecer sequências vazias quando não puderem ou decidirem não relatar os recursos de transporte. Isso não é equivalente a "todos os transportes suportados" - trate como dicas quando a informação está indisponível.
• Propriedade transports ausente: Quando os transportes são omitidos dos descritores de credenciais, os agentes de usuário (user agents) determinam os métodos de autenticação disponíveis com base em outros fatores. O contexto importa: nas respostas de registro vs. opções de solicitação de autenticação, as implicações são diferentes.
• Dicas de transporte: De acordo com a especificação, os transportes devem ser tratados como dicas para ajudar os user agents a otimizar a interface do usuário de autenticação, não como garantias autorizadas de capacidades.

Monitore as mudanças da plataforma: As implementações de WebAuthn evoluem. Apple, Google e Microsoft atualizam regularmente os comportamentos de seus autenticadores. Mantenha-se informado sobre as alterações que possam afetar o manuseio do transporte.

Os transportes WebAuthn — especialmente os transportes interno e híbrido — são detalhes técnicos com impacto prático significativo na autenticação entre dispositivos. Sua estratégia de manuseio de transporte deve estar alinhada com sua abordagem mais ampla de implementação de chaves de acesso e plataformas de destino.

Decisões de transporte residem dentro de uma estratégia mais ampla: A forma como você lida com transportes depende se você está criando com foco em máxima flexibilidade (allowCredentials vazio) ou experiência do usuário para o consumidor (focado no identificador com credenciais específicas). A última torna os transportes críticos para a otimização.

Diferenças da plataforma exigem tratamento: A Web e o Android fornecem informações de transporte confiáveis, enquanto os autenticadores da plataforma iOS retornam arrays vazios. O Windows Hello envia apenas ["internal"]. O entendimento destas diferenças é essencial para implementações em produção.

Duas abordagens de transporte válidas: A conformidade com a especificação (confiar nos transportes do autenticador) funciona bem para cenários de empresa e de máxima flexibilidade. O controle explícito (otimização dos transportes) se adapta a aplicativos de consumidor com fluxos focados no identificador e aplicativos móveis nativos.

Focado no identificador (Identifier-First) permite otimização de transporte: Quando os usuários fornecem seu identificador primeiro, o tratamento do transporte se torna uma poderosa ferramenta de UX. Você pode evitar códigos QR indesejados no celular, ocultar opções de chaves de segurança e simplificar a autenticação — sem preocupações adicionais de enumeração da conta.

Para cenários empresariais / de máxima flexibilidade:

• Use allowCredentials vazio para suportar todos os tipos de autenticador
• Confie nos transportes fornecidos pelo autenticador
• Aceite que os usuários vejam mais opções de autenticação
• Implementação mais simples, compatibilidade mais ampla

Para aplicativos de consumidor / Aplicativos nativos:

• Implementar fluxo de autenticação focado no identificador (identifier-first)
• Nudges de usuários (pós-login, prompts automáticos): Use authenticatorAttachment: "platform" para autenticação imediata de alto sucesso
• Configurações da conta na web: Permitir a criação sem authenticatorAttachment para usuários avançados que precisam de chaves de segurança
• Use allowCredentials com credenciais específicas e transportes otimizados
• Aplicativos nativos: Habilitar preferImmediatelyAvailableCredentials para autenticação silenciosa
• Preencha arrays vazios do iOS com ["hybrid", "internal"]
• Autenticação da web: Suporte para todos os transportes incluindo chaves de segurança
• Filtre o hybrid em dispositivos móveis para evitar códigos QR quando apropriado
• Experiência superior para o usuário com opções de autenticação simplificadas enquanto mantém a compatibilidade

Para plataformas que já usam fluxos focados no identificador:

• Enumeração de contas já não é um problema
• A abordagem voltada ao consumidor se alinha naturalmente com a UX existente
• A otimização do transporte proporciona benefícios imediatos à UX
• Abordagem recomendada para a maioria dos aplicativos de consumidor

Comece seguindo a especificação, e em seguida, otimize com base na sua estratégia:

1. Persistir transportes exatamente como os recebeu no momento do registro
2. Decidir sua estratégia geral (flexibilidade máxima vs. sob medida para o consumidor)
3. Se for sob medida para o consumidor: implemente o fluxo focado no identificador (identifier-first) e otimize os transportes
4. Lide com as matrizes vazias do iOS de forma apropriada para sua estratégia escolhida
5. Teste exaustivamente as plataformas Web, Native iOS, e Native Android

O panorama WebAuthn continua a evoluir. Os fornecedores de plataformas atualizam as suas implementações regularmente, e as especificações como a WebAuthn Level 3 introduzem novas funcionalidades. A criação de sistemas flexíveis que alinhem a manipulação de transporte com a sua estratégia de autenticação mais abrangente garante que a sua implementação de chaves de acesso permaneça robusta e providencie excelentes experiências para os usuários na medida em que o ecossistema amadurece.

Sobre a Corbado

Corbado é a Passkey Intelligence Platform para times de CIAM que rodam autenticação consumer em escala. Mostramos o que logs de IDP e ferramentas genéricas de analytics não enxergam: quais dispositivos, versões de SO, navegadores e gerenciadores de credenciais suportam passkeys, por que os registros não viram logins, onde o fluxo WebAuthn falha e quando uma atualização de SO ou navegador quebra silenciosamente o login — tudo sem substituir Okta, Auth0, Ping, Cognito ou seu IDP interno. Dois produtos: Corbado Observe adiciona observabilidade para passkeys e qualquer outro método de login. Corbado Connect entrega passkeys gerenciados com analytics integrado (junto ao seu IDP). VicRoads roda passkeys para mais de 5M de usuários com Corbado (+80% de ativação de passkey). Fale com um especialista em Passkeys →

O AuthenticationServices do iOS oculta informações de transporte para autenticadores de plataforma como o iCloud Keychain, retornando arrays vazios de acordo com as disposições de privacidade da especificação WebAuthn. As chaves de segurança no iOS fornecem dados de transporte como ["usb"] ou ["nfc"]. As partes confiáveis (relying parties) devem tratar todos os transportes como dicas e não como garantias autorizadas de capacidade.

cable é uma terminologia legada que é sinônimo de hybrid, significando caBLE (cloud-assisted Bluetooth Low Energy). Ambos descrevem a autenticação entre dispositivos (cross-device), como a leitura de um código QR para autenticar uma sessão de desktop usando um telefone. hybrid é o termo atual introduzido no WebAuthn Level 3 e deve ser usado em novas implementações.

Para aplicativos de consumidor usando fluxos focados no identificador (identifier-first), defina explicitamente os transportes como ["hybrid", "internal"] para autenticadores de plataforma iOS que retornaram arrays vazios durante o registro. Isso evita que os prompts das chaves de segurança USB e NFC apareçam na interface de usuário de autenticação. A alternativa compatível com a especificação é deixar os arrays vazios ou omitir totalmente a propriedade de transportes.

A remoção do transporte hybrid em dispositivos móveis evita prompts de código QR quando os usuários já estão em um dispositivo onde residem suas chaves de acesso. No entanto, a manipulação do transporte produz resultados inconsistentes: algumas plataformas mostram códigos QR mesmo quando hybrid é excluído, e outras os ocultam de qualquer forma. Sempre teste nas plataformas de destino e forneça métodos de autenticação de fallback para evitar a criação de becos sem saída.

Um array allowCredentials vazio suporta todos os tipos de autenticadores, incluindo chaves de segurança e autenticação entre dispositivos, mas reduz a relevância do transporte e pode apresentar aos usuários várias opções simultâneas. O preenchimento com credenciais de usuário específicas torna o manuseio do transporte fundamental para otimizar a interface do usuário, permitindo fluxos focados no identificador para filtrar códigos QR em dispositivos móveis e ocultar prompts de chave de segurança em contextos de consumidor.