Dispositivos confiáveis de MFA

Dispositivos confiáveis de MFA permitem que os usuários pulem solicitações repetidas de MFA em um navegador que confiam. Após uma verificação ou configuração de MFA elegível, os usuários podem optar por confiar no navegador em uma página separada Confiar neste dispositivo ao final do login ou cadastro. O Logto então armazena uma credencial com tempo limitado em um cookie de primeira parte. Em um login posterior, uma credencial válida pode cumprir a etapa de verificação de MFA sem interação do usuário.

Um dispositivo confiável não é um novo fator de MFA e não altera quando o Logto exige MFA. Ele pode cumprir apenas a etapa de MFA em um fluxo de login. Não pode satisfazer verificação de identidade, verificação recente, recuperação de conta, gerenciamento de fatores de MFA ou outra operação sensível da conta.

Como funcionam os dispositivos confiáveis

Quando um login atinge a etapa de verificação de MFA, o Logto:

1. Avalia a política de MFA existente para decidir se o MFA é necessário.
2. Verifica se dispositivos confiáveis estão habilitados para o tenant e permitidos por todas as organizações às quais o usuário pertence.
3. Valida o cookie do navegador em relação a um registro ativo no servidor para o usuário identificado.
4. Conclui o MFA automaticamente quando a credencial é válida. Caso contrário, o Logto limpa uma credencial inválida e continua com o fluxo convencional de MFA.

Confiar em um dispositivo durante o login ou cadastro

A experiência de login integrada apresenta Confiar neste dispositivo como uma página separada ao final de um fluxo de login ou cadastro elegível, após o preenchimento obrigatório do perfil e etapas de MFA. Confiar no navegador é uma escolha explícita nesta página, separada da verificação ou configuração do MFA.

A página aparece apenas quando dispositivos confiáveis estão habilitados para o tenant, permitidos por todas as organizações às quais o usuário pertence, e a interação atual contém uma prova de MFA elegível:

• Verificação de MFA bem-sucedida com um aplicativo autenticador OTP habilitado, passkey (WebAuthn), código de verificação por email ou código de verificação por SMS.
• Vinculação bem-sucedida de um aplicativo autenticador ou passkey durante a configuração de MFA, incluindo configuração durante o cadastro.

A página não é exibida durante a redefinição de senha ou quando a interação não possui prova de MFA elegível. Verificação por código de backup ou uma credencial de dispositivo confiável existente sozinha não qualificam, então a página não é exibida em todo login ou cadastro. Uma escolha anterior de Pular também pode suprimir a página, conforme descrito abaixo.

Na página, os usuários podem escolher:

• Confiar neste dispositivo por N dias: optar pela duração de confiança configurada. O Logto cria o registro do dispositivo confiável e a credencial do cookie somente após a conclusão bem-sucedida da interação.
• Pular: continuar sem criar um dispositivo confiável. Pular esta página não pula nenhuma verificação ou configuração de MFA obrigatória.

Quando um usuário seleciona Pular, o Logto armazena um cookie de exclusão separado com escopo para aquele tenant e usuário no navegador atual. Seu tempo de vida é a duração de confiança configurada no momento do pulo. Enquanto o navegador retiver esse cookie, logins posteriores não exibirão a página novamente. Após expirar ou ser limpo, um fluxo elegível posterior pode exibir a página novamente. O cookie de exclusão não concede confiança ao dispositivo nem cumpre o MFA.

Confiar no dispositivo após selecionar Pular:

Se um usuário selecionar Pular e depois quiser confiar no navegador atual, a abordagem recomendada é excluir o cookie de exclusão correspondente para o domínio do Logto usando as configurações de cookies do navegador ou ferramentas de desenvolvedor. Seu nome começa com __Host-logto-device-trust-opt-out-.

Como alternativa, limpe todos os cookies para o domínio do Logto.

Após qualquer uma das opções, faça login novamente, conclua a verificação ou configuração de MFA elegível e escolha Confiar neste dispositivo por N dias quando a página aparecer.

A criação do dispositivo confiável e as atualizações de metadados pós-login são feitas por melhor esforço, então uma falha não invalida uma interação de autenticação bem-sucedida.

Configurar a política de dispositivos confiáveis

Política global

Navegue até Console > Autenticação multifatorial e configure Dispositivos confiáveis:

• Ative ou desative dispositivos confiáveis para o tenant. A política é desativada por padrão.
• Defina uma duração de confiança em número inteiro de 1 a 365 dias. O padrão é 30 dias.

A duração é fixa quando um dispositivo confiável é criado. O uso do dispositivo não estende seu tempo de expiração, e alterar a duração afeta apenas dispositivos criados posteriormente.

Desabilitar a política global impede que dispositivos confiáveis existentes cumpram o MFA, mas não os exclui. Se você habilitar a política novamente, registros que não expiraram ou foram removidos podem voltar a ser utilizáveis.

Restrições no nível da organização

Uma organização pode permitir ou não dispositivos confiáveis para seus membros. Esta configuração só pode restringir ainda mais a política no nível do tenant:

• Uma organização não pode habilitar dispositivos confiáveis quando a política global está desativada.
• Se qualquer organização à qual o usuário pertence não permitir dispositivos confiáveis, a credencial de dispositivo confiável do usuário não pode cumprir o MFA, independentemente de essa organização exigir MFA.
• Organizações não possuem uma duração de confiança separada. A duração global se aplica.

Desabilitar dispositivos confiáveis para uma organização suspende seu uso para os membros afetados. Não exclui seus registros e não impede que usuários ou administradores os listem ou removam.

Limitações de navegador e cookies

O reuso de dispositivos confiáveis requer que o contexto do navegador preserve e retorne um cookie de primeira parte persistente para o mesmo endpoint do Logto. Ele representa um perfil de navegador, não um dispositivo físico.

WebViews, navegadores do sistema, abas personalizadas, modos de privacidade, navegadores com cookies desativados e outros contextos efêmeros podem usar dispositivos confiáveis apenas quando seu armazenamento de cookies persiste a credencial. Se o cookie não estiver disponível em um login posterior, o Logto continua com o MFA convencional em vez de falhar a autenticação. Navegadores diferentes, perfis de navegador, domínios do Logto, tenants e usuários não compartilham credenciais de dispositivos confiáveis.

nota:

O Logto não utiliza fingerprinting de navegador nem detecta previamente se um cliente irá persistir o cookie. Aplicativos nativos e fluxos de login personalizados devem tratar a criação de dispositivos confiáveis como melhor esforço e manter o fluxo convencional de MFA disponível.

Gerenciar dispositivos confiáveis

Apenas registros ativos cujo expiresAt está no futuro são listados. Os nomes dos dispositivos são derivados do user agent mais recente, enquanto país e cidade são metadados aproximados do contexto de requisição mais recente disponível. Endereços IP brutos não são exibidos nem retornados pelas APIs públicas.

Gerenciamento por administradores

Em Console > Gerenciamento de usuários, abra um usuário para visualizar e remover seus dispositivos confiáveis. Remover um dispositivo confiável afeta apenas logins futuros; não encerra as sessões ativas do usuário.

Você também pode usar a Management API:

• GET /api/users/{userId}/trusted-devices lista todos os dispositivos confiáveis ativos de um usuário.
• DELETE /api/users/{userId}/trusted-devices/{trustedDeviceId} remove um dispositivo confiável pertencente ao usuário.

A resposta da lista inclui id, userAgent, country, city, createdAt, lastUsedAt e expiresAt.

curl https://[tenant-id].logto.app/api/users/[user-id]/trusted-devices \
  -H "Authorization: Bearer [management-api-access-token]"

curl -X DELETE \
  https://[tenant-id].logto.app/api/users/[user-id]/trusted-devices/[trusted-device-id] \
  -H "Authorization: Bearer [management-api-access-token]"

Saiba como autenticar com a Management API.

Gerenciamento self-service no Account Center

Em Console > Login & conta > Account center, configure o campo Dispositivos confiáveis:

• Desativado: usuários não podem listar ou remover dispositivos confiáveis.
• Somente leitura: usuários podem listar dispositivos confiáveis, mas não podem removê-los.
• Editar: usuários podem listar e remover dispositivos confiáveis.

O Account Center pré-construído exibe dispositivos confiáveis ativos em sua página de segurança e marca o navegador atual quando sua credencial de cookie está válida. Remover o navegador atual limpa seu cookie de dispositivo confiável, mas mantém a sessão de login ativa. Remover o registro de outro navegador não pode limpar imediatamente o cookie desse navegador; o cookie obsoleto é rejeitado e limpo quando for apresentado novamente.

Para um account center personalizado, solicite o escopo urn:logto:scope:trusted_devices e use a Account API com um registro de verificação de identidade válido:

• GET /api/my-account/trusted-devices lista os dispositivos confiáveis ativos do usuário logado e adiciona isCurrent a cada item.
• DELETE /api/my-account/trusted-devices/{trustedDeviceId} remove um dispositivo confiável pertencente ao usuário logado. A exclusão está disponível apenas para aplicativos de primeira parte.

curl https://[tenant-id].logto.app/api/my-account/trusted-devices \
  -H "Authorization: Bearer [account-api-access-token]" \
  -H "logto-verification-id: [verification-record-id]"

curl -X DELETE \
  https://[tenant-id].logto.app/api/my-account/trusted-devices/[trusted-device-id] \
  -H "Authorization: Bearer [account-api-access-token]" \
  -H "logto-verification-id: [verification-record-id]"

Veja a referência da Account API e o guia de verificação de segurança para o fluxo de autorização e verificação.

Modelo de segurança

A credencial de dispositivo confiável é um token opaco do tipo bearer com duas partes: um ID de registro e um segredo criptograficamente aleatório de 32 bytes.

• Em produção, o Logto o armazena em um cookie apenas para o host com o prefixo __Host-, atributos HttpOnly, Secure, SameSite=Lax e Path=/. O JavaScript do aplicativo não pode lê-lo.
• O servidor armazena apenas o hash SHA-256 do segredo e compara as credenciais com uma verificação segura contra timing.
• Toda busca de credencial é restrita ao tenant e usuário e exige que expiresAt esteja no futuro.
• A expiração é fixa na criação. Limpeza oportunista pode excluir linhas expiradas posteriormente, mas o tempo da limpeza nunca é usado como controle de segurança.
• A remoção explícita exclui imediatamente o registro no servidor. Um cookie copiado ou obsoleto não pode passar na validação após a remoção do registro.

Segredos e hashes de credenciais nunca são expostos por UI, APIs públicas, logs de auditoria ou webhooks. O ID público do dispositivo não é um identificador de dispositivo físico e não é suficiente para autenticar. Como o cookie é um token bearer, copiar o cookie completo pode reutilizar a confiança para o mesmo tenant e usuário até que o registro expire ou seja removido; dispositivos confiáveis não fornecem atestação de dispositivo baseada em hardware.

Logs de auditoria e webhooks

Logs de auditoria específicos de dispositivos confiáveis incluem:

• TrustedDevice.Created: um registro de dispositivo confiável e credencial de cookie foram criados após uma interação bem-sucedida.
• TrustedDevice.Used: uma credencial de dispositivo confiável cumpriu o MFA e o login foi concluído com sucesso.

Você pode assinar estes webhooks de mutação de dados:

• TrustedDevice.Created: um registro de dispositivo confiável foi criado.
• TrustedDevice.Deleted: um usuário ou administrador removeu um registro de dispositivo confiável.

Os dados do evento contêm o id, userId e expiresAt do dispositivo confiável. Exclui a credencial do cookie, hash do segredo e IP da requisição. Não há webhook para uso bem-sucedido para evitar alto volume de eventos, e mudanças de política não emitem eventos de ciclo de vida de dispositivos confiáveis porque não alteram registros.

A expiração natural não possui webhook TrustedDevice.Expired. A expiração ocorre quando o tempo passa, e não quando uma mutação de aplicativo é executada, e a limpeza física pode acontecer depois. Use o valor expiresAt de TrustedDevice.Created se sua integração precisar derivar o tempo de expiração esperado.

A expiração natural também não cria um log de auditoria específico de dispositivo confiável.

Veja tipos de eventos de log de auditoria e eventos de webhook para os catálogos de eventos.

Notas sobre o ciclo de vida

• O logout normal não remove dispositivos confiáveis.
• Adicionar, remover ou redefinir fatores de MFA não remove dispositivos confiáveis.
• Remover um dispositivo confiável não encerra sessões ativas.
• Excluir o usuário exclui seus registros de dispositivos confiáveis pelo ciclo de vida dos dados do usuário.
• Não há limite de quantidade de dispositivos confiáveis nem remoção automática.