TsgcWSAPIServer_WebAuthn

O componente TsgcWSAPIServer_WebAuthn fornece uma solução simples, porém poderosa, para implementar o servidor WebAuthn Relying Party, habilitando autenticação sem senha em sua aplicação web. Uma aplicação WebAuthn consiste em um servidor WebAuthn que trata do registro e da autenticação no lado do servidor, e uma aplicação do lado do cliente que geralmente é uma aplicação javascript.

 

O WebAuthn requer o uso de conexões seguras (SSL/TLS), portanto as bibliotecas OpenSSL devem ser implantadas e configuradas com o servidor.

 

Apenas a OpenSSL 3.0.0+ API é suportada, portanto versões anteriores do OpenSSL podem não funcionar.

 

Configuração

 

O TsgcWSAPIServer_WebAuthn deve ser anexado a um servidor HTTP, TsgcWebSocketHTTP_Server ou TsgcWebSocketServer_HTTPAPI utilizando a propriedade Server. Você pode configurar os endpoints do servidor que tratarão as opções de registro e autenticação, e as opções do WebAuthn, como algoritmos suportados, origins e muito mais.

 

Endpoints Options

Aqui você pode configurar os endpoints do servidor que tratarão as requisições HTTP/JavaScript para utilizar o WebAuthn como autenticador. O componente já vem configurado com endpoints padrão, mas você pode alterar todos eles para atender às suas necessidades.

 

• AuthenticationOptions: por padrão é /sgcWebAuthn/Authentication/Options
• AuthenticationVerify: por padrão é /sgcWebAuthn/Authentication/Verify
• RegistrationOptions: por padrão é /sgcWebAuthn/Registration/Options
• RegistrationVerify: por padrão é /sgcWebAuthn/Registration/Verify
• Webauthn: inclui a biblioteca javascript usada por padrão. Você pode desabilitar esta propriedade e usar sua própria biblioteca webauthn.
• Test: por padrão está desabilitado; utilize apenas para testar a funcionalidade WebAuthn.

 

Exemplo: se o seu servidor está escutando no domínio www.test.com, a requisição às opções de autenticação por padrão será http://www.test.com/sgcWebAuthn/Authentication/Options

 

WebAuthn Options

Nesta propriedade, você pode configurar as principais opções do Componente Servidor WebAuthn.

 

• RelyingParty: uma propriedade obrigatória onde o nome DNS do servidor deve ser definido. Exemplo: se o servidor está em execução no domínio www.test.com, defina esta propriedade como "www.test.com".

 

O WebAuthn utiliza origens para impor restrições da política de mesma origem, que são essenciais para prevenir ataques de phishing e cross-site. Durante os processos de registro e autenticação WebAuthn, a origem é estritamente validada pelo navegador e pelo authenticator.

 

• Origins: Se as requisições puderem vir de diferentes origens, use a propriedade Origin para definir as origens adicionais. Exemplo: se as requisições puderem vir de login.test.com e www.test.co.uk, configure a propriedade Origins com os valores: https://login.test.com e https://www.test.co.uk

 

• TopOrigins: Normalmente, o WebAuthn depende da origem do frame chamador (ou seja, aquele que invoca navigator.credentials.create() ou navigator.credentials.get()). No entanto, páginas web podem ser incorporadas em iframes, que podem vir de uma origem diferente da página de nível superior. Isso abre potencial para abusos ou ataques no estilo clickjacking. Para mitigar isso, a especificação WebAuthn Level 2 introduz TopOrigin, onde você pode definir os TopOrigins.

 

No WebAuthn, crossOrigin é um parâmetro booleano que indica se a operação WebAuthn está sendo realizada a partir de um contexto cross-origin, como um iframe incorporado de uma origem diferente do contexto de navegação de nível superior.

Este parâmetro foi introduzido para ajudar navegadores e authenticators a tratar requisições de autenticação com segurança em ambientes embarcados—um cenário comum em aplicações web modernas.

 

• AllowCrossOrigins: se true, indica que requisições feitas a partir de um iframe cross-origin (por exemplo, um iframe em https://auth.example.com incorporado em uma página em https://app.example.org) são permitidas. Por padrão, está desabilitado.

 

O WebAuthn suporta uma variedade de algoritmos criptográficos para geração e verificação de credenciais de chave pública. Esses algoritmos são utilizados durante o registro de credenciais (com navigator.credentials.create()) e a autenticação (com navigator.credentials.get()), e garantem a assinatura e validação seguras dos desafios utilizando pares de chaves assimétricas. O servidor é configurado por padrão com o ES256 e RS256, que são os algoritmos mais comuns. Você pode alterar a qualquer momento quais algoritmos são suportados pela propriedade Algorithms. Os seguintes algoritmos são suportados:

 

• ES256
• ES384
• ES512
• RS256
• RS384
• RS512
• PS256
• PS384
• PS512
• RS1
• EdDSA

 

No WebAuthn, attestation é um mecanismo opcional que permite ao authenticator (por exemplo, dispositivo ou chave de segurança) fornecer informações sobre seu fabricante, modelo e características de segurança durante a criação da credencial. Essas informações ajudam o Relying Party (RP) a decidir se deve confiar no authenticator.

 

Diferentes formatos de atestação definem como esses dados são estruturados e verificados. Três formatos comumente utilizados são android-key, packed, e outros como fido-u2f, apple ou none. Por padrão, todos os formatos de atestação estão habilitados. Você pode encontrar abaixo a lista de formatos de atestação suportados:

 

• NoneAttestation: neste caso, nenhum dado de attestation é retornado. Prioriza a privacidade do usuário ao evitar a exposição de identificadores do dispositivo. Comum em aplicações que não se importam com a procedência do dispositivo.

 

• PackedAttestation: é um formato flexível e compacto usado por muitos autenticadores. O autenticador retorna um certificado de atestação e uma assinatura. Pode ser: Atestação completa: Assinada com uma chave e certificado fornecidos pelo fabricante ou Autoatestação: Assinada usando a chave privada da credencial. O mais amplamente utilizado em diferentes plataformas (por exemplo, YubiKey, Windows Hello).

 

• TPMAttestation: Utilizado por dispositivos com um Trusted Platform Module (TPM). A atestação é assinada utilizando chaves do TPM e inclui uma cadeia de certificados. Utilizado por desktops/laptops corporativos com chips TPM (por exemplo, máquinas Windows).

 

• AndroidKeyAttestation: Utilizado por dispositivos Android com o Android Keystore. A chave é gerada em hardware, e a attestation inclui informações assinadas por uma cadeia de certificados emitida pelo fabricante do dispositivo. Utilizado por telefones Android com keystores apoiados por hardware (TEE ou StrongBox).

 

• AppleAttestation: Usado por autenticadores de plataforma da Apple, como Touch ID e Face ID. A attestation é gerada pelas APIs internas da Apple e inclui um formato de certificado especial. Usado no Safari com biometria da Apple.

 

• FidoU2FAttestation: Formato de atestação legado utilizado por autenticadores FIDO U2F. Retorna um certificado e uma assinatura compatíveis com U2F. Utilizado por chaves de segurança mais antigas (por exemplo, as primeiras YubiKeys) que suportam FIDO U2F.

 

Na API WebAuthn, AllowCredentials é um campo opcional utilizado durante o processo de autenticação (via navigator.credentials.get()). Ele especifica uma lista de IDs de credenciais que estão autorizadas a autenticar o usuário para uma Relying Party (RP) específica. Esse mecanismo permite que a RP controle quais credenciais são consideradas válidas para uma tentativa de login. A propriedade credentials possui os seguintes campos:

 

• AllowCredentials: se habilitado (false por padrão), especifica uma lista de IDs de credenciais que têm permissão para autenticar o usuário

 

• ExcludeCredentials: dado um nome de usuário, mostra todas as credenciais existentes já armazenadas no componente do servidor.

 

• Limit: o número máximo de credenciais que serão enviadas quando ExcludeCredentials for true.

 

WebAuthn Protocol

 

• WebAuthn Registration: O servidor gera um desafio e o envia ao cliente, que utiliza um authenticator (por exemplo, uma chave de segurança ou um dispositivo biométrico) para criar um par de chaves. A chave pública é enviada de volta e armazenada pelo servidor para autenticação futura. Encontre abaixo mais informações sobre os eventos do fluxo de registro:
  • WebAuthn Registration Request
  • WebAuthn Registration Response
  • WebAuthn Registration Result

 

• WebAuthn Authentication: O servidor envia um desafio ao cliente, que o assina utilizando a chave privada previamente registrada armazenada no authenticator. A resposta assinada é verificada pelo servidor utilizando a chave pública armazenada para confirmar a identidade do usuário. Encontre abaixo mais informações sobre os eventos do fluxo de autenticação:
  • WebAuthn Authentication Request
  • WebAuthn Authentication Response
  • WebAuthn Authentication Result

 

• MDS: O FIDO Alliance Metadata Service (MDS) é um repositório centralizado de Metadata Statements utilizado pelas relying parties para validar a attestation do autenticador e provar a autenticidade do modelo do dispositivo.

 

 

• Authorization: O cliente pode solicitar um bearer token do servidor durante o fluxo de autenticação. Este token pode ser utilizado posteriormente para abrir uma nova conexão WebSocket ou HTTP sem a necessidade de fazer login utilizando passkeys.
  • WebAuthn Authorization WebSocket
  • WebAuthn Authorization HTTP