Transportes WebAuthn: Transporte Interno e Híbrido

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

Nota: De acordo com a especificação WebAuthn, uma lista de transportes vazia significa que todos os transportes são suportados.

Ao implementar passkeys em várias plataformas, os developers deparam-se com uma decisão importante:

• Como devemos gerir os transportes WebAuthn, especialmente os transportes internos e híbridos, para garantir as melhores experiências de autenticação cross-device?

A resposta está na compreensão dos transportes WebAuthn — um detalhe técnico que determina como os autenticadores comunicam com as relying parties. Embora os transportes pareçam simples na teoria, a sua implementação varia significativamente entre navegadores web, aplicações nativas de iOS e Android, especialmente no que toca à gestão dos transportes interno e híbrido.

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

Este artigo aborda:

1. Transportes WebAuthn: interno, híbrido e autenticadores de plataforma na web, iOS e Android
2. Duas abordagens: gestão de transportes interno e híbrido em conformidade com a especificação vs. otimizada
3. Melhores práticas e recomendações para a implementação da autenticação cross-device

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

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

nfc: Permite a comunicação com autenticadores através de Near Field Communication, permitindo aos utilizadores tocar nas suas chaves de segurança ou dispositivos com NFC.

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

smart-card: Usado para leitores de smart card, permitindo a autenticação através de cartões inteligentes.

hybrid: Permite a autenticação cross-device, tipicamente onde um utilizador digitaliza um código QR para se autenticar entre dispositivos — como usar um telemóvel para se autenticar num navegador de desktop, ou vice-versa. Este transporte pode acionar prompts de código QR tanto em dispositivos desktop como móveis, o que pode nem sempre ser desejável dependendo do contexto. Nota: o hybrid foi adicionado no WebAuthn Level 3.

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

Quando uma passkey é criada, o autenticador sinaliza quais os transportes que suporta. Esta informação é enviada para a relying party (o seu backend), que a deve guardar juntamente com a credencial. Durante a autenticação, a relying party envia estes transportes de volta para o cliente na lista allowCredentials, ajudando o navegador ou a plataforma a determinar que métodos de autenticação oferecer ao utilizador.

A gestão de transportes difere significativamente entre plataformas, criando os desafios de compatibilidade que os developers enfrentam.

Os navegadores recebem informações de transporte dos autenticadores e respeitam-nas durante os fluxos de autenticação. Quando cria uma passkey no Chrome, Safari ou Edge, o gestor de credenciais do navegador fornece dados de transporte que variam com base no autenticador subjacente:

Autenticadores de plataforma: O Windows Hello fornece apenas ["internal"], refletindo a 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 cross-device através de telemóveis Android.

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

Gestores de credenciais sincronizados na nuvem: O iCloud Keychain no Safari e o Google Password Manager no Chrome fornecem tipicamente ["internal", "hybrid"] para suportar fluxos de autenticação tanto locais como cross-device.

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

Documentação: Especificação WebAuthn do W3C

A API Credential Manager do Android comporta-se de forma semelhante aos navegadores web. Ao criar passkeys em aplicações nativas Android, o Credential Manager fornece informações de transporte que espelham o comportamento da web — os autenticadores de plataforma reportam as suas capacidades com precisão, e o sistema gere os dados de transporte de forma consistente. Os developers Android podem confiar nesta informação sem necessidade de tratamento especial.

Documentação: Android Credential Manager

O iOS apresenta uma situação mais complexa. A framework AuthenticationServices da Apple gere os transportes de forma diferente dependendo do tipo de autenticador:

Autenticadores de plataforma (iCloud Keychain, verificado via Face ID ou Touch ID): Frequentemente, retornam arrays de transporte vazios durante a criação da passkey. Isto não significa que a passkey não tenha capacidades de transporte — significa apenas que o iOS não as reporta explicitamente. De acordo com o padrão WebAuthn, omitir os transportes significa que qualquer transporte é aceitável, pelo que a autenticação híbrida continuará a funcionar.

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

Documentação: Apple AuthenticationServices

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

Esta abordagem alinha-se com a especificação WebAuthn: usar os transportes exatamente como fornecidos pelo autenticador durante o registo da credencial e enviá-los de volta inalterados durante a autenticação.

Implementação: Quando uma passkey é criada, guarde o array transports da resposta do autenticador. Durante a autenticação, inclua estes 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 futuras atualizações de plataforma.
• Fiabilidade das chaves de segurança: Funciona perfeitamente para chaves de segurança de hardware (YubiKeys, etc.) que fornecem sempre informações de transporte precisas.
• Previne 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, segundo a especificação, significa "qualquer transporte" — isto pode mostrar todas as opções de autenticação, incluindo chaves de segurança.
• Pode mostrar opções indesejadas: Pode apresentar opções de chave de segurança (USB, NFC) em aplicações de consumo onde não são esperadas.
• Experiência do utilizador inconsistente: Diferentes plataformas oferecem diferentes opções de autenticação para a mesma conta.

Ideal para: Aplicações que priorizam a conformidade com os padrões, ambientes empresariais com diversos tipos de autenticadores.

Esta abordagem prioriza a experiência do utilizador ao modificar seletivamente os transportes interno e híbrido com base em objetivos de otimização específicos. Em vez de uma regra geral, considere estes cenários de otimização comuns:

Problema: Os autenticadores de plataforma do iOS retornam arrays de transporte vazios. Quando deixados vazios ou preenchidos pelos backends, os utilizadores podem ver prompts de chave de segurança (USB, NFC) juntamente com as opções de plataforma, criando confusão em aplicações de consumo.

Solução: Definir explicitamente os transportes para ["hybrid", "internal"] para os autenticadores de plataforma do iOS. Isto garante que apenas a autenticação de plataforma e os fluxos cross-device são oferecidos, ocultando as opções de chave de segurança.

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

Resultado: UI de autenticação limpa, sem prompts de chave de segurança para passkeys criadas no iOS.

Problema: Ao autenticar em dispositivos móveis, mostrar códigos QR para autenticação cross-device cria uma má experiência de utilização — os utilizadores já estão num dispositivo móvel com as suas passkeys disponíveis.

Solução: Remover o transporte hybrid quando o utilizador está a autenticar a partir de 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 utilizadores móveis veem apenas opções de autenticação direta, sem prompts de código QR desnecessários.

⚠️ Cuidado: A manipulação de transportes nem sempre produz resultados consistentes entre plataformas. Testes extensivos mostram que as combinações de navegador e sistema operativo gerem os transportes de forma diferente:

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

Risco de becos sem saída: Uma filtragem de transportes demasiado restritiva pode criar becos sem saída na autenticação, onde os utilizadores não conseguem fazer login de todo. Por exemplo, remover hybrid pode impedir cenários legítimos de autenticação cross-device em que um utilizador precisa de se autenticar a partir de um dispositivo emprestado. Forneça sempre métodos de autenticação de recurso e teste exaustivamente nas suas plataformas-alvo antes de implementar otimizações de transporte.

Estas são dicas de otimização: O WebAuthn fornece outros mecanismos para otimizar a experiência de autenticação para além da manipulação de transportes — como dicas (hints).

O comportamento do transporte é imprevisível: A autenticação cross-device (CDA) através do transporte hybrid exibe um comportamento inconsistente entre as combinações de navegador e SO. Testes no mundo real demonstram que os valores de transporte não garantem um comportamento específico da UI — as plataformas interpretam e gerem os transportes de forma diferente, levando a resultados inesperados.

Complexidade específica da plataforma: Ao controlar explicitamente os transportes, é necessário ter em conta as diferenças de plataforma:

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

É necessária uma compreensão completa: Controlar explicitamente os transportes significa assumir a responsabilidade por todo o fluxo. É preciso entender como cada combinação de transporte se comporta em todas as suas plataformas-alvo e testar exaustivamente. A manipulação de transportes pode criar becos sem saída na autenticação, onde não existe um caminho de autenticação válido para os utilizadores.

Vantagens:

• UX personalizada: Controle exatamente quais opções de autenticação os utilizadores veem em contextos específicos.
• Resolve o problema do array vazio do iOS: Define explicitamente os transportes onde o iOS não fornece nenhum.
• Otimização sensível ao contexto: Adapta a UI de autenticação com base no tipo de dispositivo.

Desvantagens:

• Comportamento imprevisível: A manipulação de transportes não garante um comportamento consistente da UI — testes extensivos mostram que as plataformas interpretam os transportes de forma diferente, por vezes mostrando ou ocultando opções independentemente dos valores de transporte.
• Risco de becos sem saída na autenticação: Uma filtragem de transportes demasiado restritiva pode impedir totalmente os utilizadores de se autenticarem, especialmente em cenários cross-device.
• Desvia-se da especificação: Afasta-se das recomendações da especificação, podendo causar problemas com futuras alterações de plataforma.
• Carga de manutenção: Requer lógica específica da plataforma e atualizações contínuas à medida que as plataformas evoluem.
• Complexidade: É preciso lidar manualmente com arrays vazios do iOS, restrições do Windows Hello e outras peculiaridades da plataforma.
• Sobrecarga de testes: Cada regra de otimização precisa de verificação em todas as combinações de plataforma.

Ideal para: Aplicações de consumo com requisitos de UX específicos, equipas com recursos para manter lógica específica da plataforma, cenários que priorizam fluxos de autenticação simplificados em detrimento da conformidade rigorosa com a especificação.

A gestão de transportes WebAuthn não existe isoladamente — é uma peça da sua estratégia geral de implementação de passkeys. Duas abordagens comuns surgem em implementações de produção, cada uma com diferentes implicações para o uso de transportes interno e híbrido.

Esta abordagem prioriza a flexibilidade e a conformidade com os padrões, permitindo que os utilizadores se autentiquem com qualquer autenticador compatível.

Características de Implementação:

• UI de Autenticação: O botão de passkey aparece ao lado das opções de login existentes (nome de utilizador/palavra-passe).
• allowCredentials: Definido como um array vazio [], permitindo que qualquer credencial corresponda.
• Tipos de autenticador: Chaves de segurança, autenticação cross-device (códigos QR), autenticadores de plataforma, todos suportados.
• Requisitos de apps nativas: Devem suportar 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 com código QR por definição.
• Gestão de transportes: Deve acomodar todos os tipos de transporte, incluindo os de chaves de segurança (usb, nfc, ble).

Implicações para os Transportes:

Com um allowCredentials vazio, os transportes tornam-se menos críticos durante a autenticação — a plataforma mostra todas as opções disponíveis. No entanto, isto significa que os utilizadores podem ver prompts de chaves de segurança, códigos QR e opções de plataforma simultaneamente, o que pode criar paralisia de decisão em aplicações de consumo.

Ideal para: Ambientes empresariais, aplicações com bases de utilizadores diversas que requerem suporte para chaves de segurança, cenários que priorizam a máxima flexibilidade de autenticação.

Esta abordagem otimiza a UX do consumidor ao restringir a criação de passkeys a autenticadores de plataforma e usar fluxos que começam pelo identificador (identifier-first).

Características de Implementação:

• Criação de passkey: Apenas autenticadores de plataforma são permitidos via authenticatorAttachment: "platform".
• Fluxo de autenticação: Identifier-first — os utilizadores inserem o e-mail/nome de utilizador antes da autenticação.
• allowCredentials: Preenchido com as credenciais específicas do utilizador (não vazio) assim que o identificador é conhecido.
• Tipos de autenticador: Autenticadores de plataforma e autenticação cross-device; as chaves de segurança são tipicamente excluídas.
• Otimização de apps nativas: Pode usar preferImmediatelyAvailableCredentials, que exclui chaves de segurança и autenticação cross-device por definição.
• Autenticação cross-device: Disponível na web; não disponível ao usar preferImmediatelyAvailableCredentials em apps nativas, mas este cenário é raro (os utilizadores geralmente têm as passkeys no dispositivo que estão a usar).
• Gestão de transportes: Focada apenas nos transportes internal e hybrid.

Implicações para os Transportes:

Como allowCredentials contém credenciais específicas com os seus transportes, a gestão de transportes torna-se crucial.

Ideal para: Aplicações de consumo, apps móveis nativas, cenários que priorizam uma UX simplificada em detrimento da flexibilidade do autenticador, plataformas onde já existem fluxos identifier-first.

Para plataformas que já revelam a existência de contas ou usam fluxos identifier-first (o utilizador insere o e-mail antes de ver as opções de login), a abordagem otimizada para o consumidor alinha-se naturalmente. Assim que o utilizador fornece o seu identificador:

1. O backend procura por passkeys existentes.
2. Retorna allowCredentials com credenciais específicas e os seus transportes.
3. A plataforma pode otimizar a UI de autenticação com base nos transportes.
4. Sem risco adicional de enumeração de contas (o identificador já foi fornecido).

Nestes cenários, os transportes podem tornar-se uma ferramenta de otimização em vez de uma preocupação de segurança. Pode personalizar as opções de autenticação com base no contexto do dispositivo (móvel vs. desktop) e nas capacidades da credencial.

Recomendação: Para plataformas que já usam fluxos identifier-first ou onde a enumeração de contas não é uma preocupação, a abordagem otimizada para o consumidor com gestão explícita de transportes oferece uma UX superior, especialmente em aplicações móveis nativas onde preferImmediatelyAvailableCredentials permite uma autenticação biométrica fluida.

Independentemente da abordagem que escolher para gerir os transportes interno e híbrido, siga estas práticas para minimizar problemas:

Guarde os Transportes Durante o Registo: Armazene sempre o array transports da resposta do autenticador juntamente com o ID da credencial e a chave pública. Estes dados são essenciais для os fluxos de autenticação.

Lide com Arrays Vazios de Forma Adequada: Ao receber um array de transporte vazio dos autenticadores de plataforma do iOS:

• Conforme a especificação: Deixe vazio ou omita a propriedade transports — significa que "qualquer transporte" é aceitável.
• Abordagem de otimização: Preencha com ["internal", "hybrid"] para controlar quais opções de autenticação são mostradas.

Teste em Todas as Plataformas-Alvo: Crie uma matriz de testes que cubra todas as combinações:

• Registo: Web, Nativo iOS, Nativo Android
• Autenticação: Web, Nativo iOS, Nativo Android
• Verifique se os códigos QR aparecem quando esperado e são ocultados quando inapropriado.

Compreenda a Diferença entre Array Vazio e Propriedade Ausente: Tanto um array de transportes vazio [] como uma propriedade transports ausente são tipicamente tratados como "qualquer transporte é aceitável" de acordo com a especificação. No entanto, os detalhes de implementação variam entre as plataformas.

Monitorize as Alterações nas Plataformas: As implementações do WebAuthn evoluem. A Apple, a Google e a Microsoft atualizam regularmente os comportamentos dos seus autenticadores. Mantenha-se informado sobre as alterações que podem afetar a gestão de transportes.

Os transportes WebAuthn — especialmente os transportes interno e híbrido — são detalhes técnicos com um impacto prático significativo na autenticação cross-device. A sua estratégia de gestão de transportes deve estar alinhada com a sua abordagem geral de implementação de passkeys e com as suas plataformas-alvo.

As Decisões de Transporte Inserem-se numa Estratégia Mais Ampla: A forma como gere os transportes depende se está a construir para máxima flexibilidade (allowCredentials vazio) ou para a UX do consumidor (identifier-first com credenciais específicas). A segunda torna os transportes cruciais para a otimização.

As Diferenças de Plataforma Exigem Tratamento: A web e o Android fornecem informações de transporte fiáveis, enquanto os autenticadores de plataforma do iOS retornam arrays vazios. O Windows Hello envia apenas ["internal"]. Compreender estas diferenças é essencial para implementações em produção.

Duas Abordagens Válidas para Transportes: A conformidade com a especificação (confiar nos transportes do autenticador) funciona bem para cenários empresariais e de máxima flexibilidade. O controlo explícito (otimizar transportes) adequa-se a aplicações de consumo com fluxos identifier-first e apps móveis nativas.

O Identifier-First Permite a Otimização de Transportes: Quando os utilizadores fornecem o seu identificador primeiro, a gestão de transportes torna-se uma poderosa ferramenta de UX. Pode evitar códigos QR indesejados em dispositivos móveis, ocultar opções de chaves de segurança e simplificar a autenticação — sem preocupações adicionais com a enumeração de contas.

Para Empresas / Máxima Flexibilidade:

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

Para Aplicações de Consumo / Apps Nativas:

• Implemente um fluxo de autenticação identifier-first.
• Restrinja a autenticadores de plataforma (authenticatorAttachment: "platform").
• Use allowCredentials com credenciais específicas e transportes otimizados.
• Ative preferImmediatelyAvailableCredentials em apps nativas.
• Preencha os arrays vazios do iOS com ["hybrid", "internal"].
• Filtre o hybrid em dispositivos móveis para evitar códigos QR.
• UX superior com opções de autenticação simplificadas.

Para Plataformas que Já Usam Fluxos Identifier-First:

• A enumeração de contas já não é um problema.
• A abordagem otimizada para o consumidor alinha-se naturalmente com a UX existente.
• A otimização de transportes proporciona benefícios imediatos na UX.
• Abordagem recomendada para a maioria das aplicações de consumo.

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

1. Guarde os transportes exatamente como recebidos durante o registo.
2. Decida a sua estratégia geral (máxima flexibilidade vs. otimizada para o consumidor).
3. Se for otimizada para o consumidor: implemente o fluxo identifier-first e otimize os transportes.
4. Lide com os arrays vazios do iOS de forma apropriada para a sua estratégia escolhida.
5. Teste exaustivamente nas plataformas Web, Nativo iOS e Nativo Android.

O cenário do WebAuthn continua a evoluir. Os fornecedores de plataformas atualizam regularmente as suas implementações, e especificações como o WebAuthn Level 3 introduzem novas capacidades. Construir sistemas flexíveis que alinhem a gestão de transportes com a sua estratégia de autenticação mais ampla garante que a sua implementação de passkeys permanece robusta e proporciona excelentes experiências de utilizador à medida que o ecossistema amadurece.