Português (Brasil)

Link mágico
Sem senha
Autenticação
Convite

Autenticação com link mágico

Aprenda a implementar links mágicos para login sem senha, registro por convite apenas e convites para membros de organização usando tokens de uso único.

Ran

Product & Design

6/6/2025

Pare de perder semanas com autenticação de usuários

Lance aplicativos seguros mais rapidamente com o Logto. Integre a autenticação de usuários em minutos e concentre-se no seu produto principal.

Começar

O que é um link mágico?

Um link mágico é um método de autenticação sem senha onde o usuário recebe uma URL de login de uso único via e-mail (ou SMS). Ao clicar no link, o usuário é logado sem precisar de uma senha.

Aqui estão alguns recursos de segurança dos links mágicos:

Token de uso único: Uma vez clicado, o token se torna inválido para evitar reutilização.
Expiração do link: O link mágico deve ter um tempo de expiração curto (por exemplo, 10 minutos) para maior segurança.
Limite de taxa: Evite abusos limitando quantos links mágicos podem ser enviados em um período específico.
Vinculação de dispositivo/navegador (Opcional): Restrinja o uso do link ao dispositivo ou IP original para evitar intercepção.

Composição de um link mágico

Um link mágico consiste em:

A rota da URL: Aponta para a página de destino do seu aplicativo.
Token de uso único: Um token único e de uso único para autenticação sem senha.
Email do usuário: Usado para validar a autenticidade do token e a identidade do usuário.
Parâmetros adicionais: Opcionais, dependendo das necessidades do seu aplicativo.

Por exemplo, um link mágico pode parecer com isso:

Para criar um link mágico, você precisa gerar um token de uso único, enviá-lo com segurança ao usuário, e então validá-lo quando o usuário clicar no link.

Fluxo de trabalho de um link mágico

Usuário solicita um link mágico: O usuário insere seu e-mail no seu aplicativo.
Geração do token de uso único: O servidor gera um token e o envia como um link via e-mail.
Usuário clica no link: O usuário clica no link do e-mail.
Validação do token: O servidor verifica se o token é válido.
Usuário é autenticado: Se o token é válido, o usuário é logado.

Como implementar links mágicos com Logto?

Etapa 1: Solicitar token de uso único

Use o API de Gerenciamento Logto para criar um token de uso único.

Exemplo de carga útil do corpo da solicitação:

Etapa 2: Compor seu link mágico

Depois de obter o token de uso único, você pode compor um link mágico e enviá-lo para o endereço de e-mail do usuário final. O link mágico deve conter pelo menos o token e o e-mail do usuário como parâmetros, e deve navegar até uma página de destino em seu próprio aplicativo. Por exemplo, https://yourapp.com/landing-page.

Aqui está um exemplo simples de como o link mágico pode parecer:

Nota:

Os nomes dos parâmetros no link mágico podem ser totalmente personalizados. Você pode adicionar informações adicionais ao link mágico com base nas necessidades do seu aplicativo, bem como codificar todos os parâmetros da URL.

Etapa 3: Disparar o fluxo de autenticação via Logto SDK

Depois que o usuário final clicar no link mágico e for redirecionado para seu aplicativo, você pode extrair os parâmetros token e email da URL, e então chamar a função signIn() do Logto SDK para disparar o fluxo de autenticação.

Para mais detalhes, verifique a Documentação Logto - Link Mágico (Token de Uso Único).

Casos de uso de links mágicos

Links mágicos podem substituir a etapa de autenticação de primeiro fator, mas não podem contornar a Autenticação Multifator (MFA).

No Logto, ao gerar um link mágico com um token de uso único, você não precisa especificar se é para login ou registro. Nós determinamos automaticamente o fluxo com base no status de registro do e-mail:

Email não registrado: Clicar no link mágico redireciona os usuários para o fluxo de criação de conta, pulando a entrada e verificação de e-mail. Os usuários devem definir uma senha, adicionar detalhes de perfil (por exemplo, nome completo) ou configurar MFA, com base nas suas configurações de registro.
Email registrado: Clicar no link mágico ignora a verificação do primeiro passo (por exemplo, “email + senha” ou “email + código de verificação”). O usuário é diretamente logado ou solicitado a completar MFA, com base em suas configurações de login.

O Logto suporta os seguintes cenários com links mágicos:

Registro somente por convite: Para ferramentas internas ou produtos de IA em fase de testes, você pode desabilitar o registro público e convidar usuários específicos via um link mágico.
Convite de membro de organização: Para produtos SaaS, use links mágicos para convidar novos membros para uma organização, facilitando o processo de adesão.
Login / Registro: Envie um link mágico para login ou registro via e-mail.

Atualmente não suportado:

Redefinição de senha com link mágico.
Uso de número de telefone ou nome de usuário como identificador.

Informe-nos se você precisar de mais personalização.

Registro somente por convite com link mágico

Para novos produtos (por exemplo, ferramentas de IA) em teste interno ou para ferramentas internas, você pode querer desabilitar o registro público e permitir apenas usuários específicos no seu aplicativo. Para implementar isso com o Logto:

Vá para Console > Experiência de login > Login e registro > Opções avançadas e desative "Ativar registro de usuário" para fechar o registro público.
Colete os endereços de e-mail dos usuários que você deseja convidar (por exemplo, através do seu site ou recomendações de usuários existentes).
Crie e envie o link mágico de convite conforme descrito acima (solicitar token de uso único, compor o link mágico, disparar autenticação via Logto SDK).

Nota: Defina um tempo de expiração para o link de convite. Recomenda-se que o link seja válido por pelo menos um dia. Use o seguinte corpo de solicitação para gerar o token de uso único:
Envie o link mágico para o e-mail do usuário (por exemplo, https://yourapp.com/landing-page?type=registrationInvitation&token=YHwbXSXxQfL02IoxFqr1hGvkB13uTqcd&[email protected]). Personalize o modelo de e-mail, como:

Quando os usuários clicarem em "Aceitar o convite", eles se registrarão automaticamente no seu serviço, mesmo com o registro público desativado. Isso é chamado de "Convite de usuário direcionado".

Convite de membro de organização com link mágico

Para produtos multi-locatários (por exemplo, aplicativos SaaS como Slack, GitHub, Vercel), forneça um processo de convite de membro sem interrupções para gerenciar associações de organização. Use links mágicos para taxas de conversão mais altas em convites de membros.

Siga a documentação do Logto para implementar a criação de organização, controle de acesso baseado em função de organização e gerenciamento de organização: Logto Organizações.
Configure o fluxo de trabalho "Convidar membros" no seu produto. Exemplo:
Siga este guia para Convidar Membros da Organização. Nota: Ao convidar membros, certifique-se de que o payload da solicitação inclua:
- context: jitOrganizationIds para especificar quais organizações o usuário ingressará.
- Defina um tempo de expiresIn mais longo (por exemplo, 2 dias ou 1 semana) para permitir tempo suficiente para os usuários aceitarem o convite.
Exemplo de payload de solicitação:
Envie o link de convite para o e-mail do usuário (por exemplo, https://yourapp.com/landing-page?type=organizationMemberInvitation&token=YHwbXSXxQfL02IoxFqr1hGvkB13uTqcd&[email protected]). Personalize seu modelo de e-mail, por exemplo:

Quando os usuários clicarem em "Aceitar o convite", eles se conectarão ou se registrarão automaticamente e se juntarão à organização.

Lidar com conflitos de conta

O que acontece se um usuário já estiver logado e clicar em outro link mágico?

Para lidar corretamente com conflitos de conta, certifique-se do seguinte:

Evite adicionar login no "prompt de login": Não configure o prompt de login incluindo login nele. Se configurado incorretamente, o Logto fará automaticamente o login na conta associada ao token do link mágico, ignorando o prompt de alternância de conta.
Preserve tokens existentes: Ao chamar a função signIn(), especifique o parâmetro clearTokens: false para impedir que os tokens existentes sejam limpos. Se esta opção for usada, certifique-se de limpar tokens manualmente na página de retorno de chamada de login.

Após a configuração adequada, a experiência do usuário será a seguinte:

Link mágico para a conta atual: Se o usuário já estiver logado e clicar em um link mágico para a mesma conta, o Logto verificará o token de uso único e proverá o usuário para as organizações especificadas se necessário.
Link mágico para uma conta diferente: Se o usuário já estiver logado e clicar em um link mágico para uma conta diferente, o Logto solicitará ao usuário que:
- Continue como a nova conta: O Logto alterna para a nova conta após a verificação do token.
- Ficar com a conta atual: O Logto ignora a verificação do token e retorna o usuário para a conta atual.

Lidar com páginas de erros para link mágico invalidado

Quando os usuários clicam em um link mágico inválido, eles serão redirecionados para uma página de erro com uma explicação clara do problema. Abaixo estão os possíveis cenários de erro e suas mensagens:

Nome	Descrição
token_not_found	Token ativo não encontrado com o email e token fornecidos.
email_mismatch	Email não corresponde ao token fornecido.
token_expired	O token expirou.
token_consumed	O token foi consumido.
token_revoked	O token foi revogado.
cannot_reactivate_token	Não é possível reativar o token.

Cada página de erro fornecerá uma mensagem específica, ajudando os usuários a entenderem o motivo do link mágico inválido e orientando-os sobre os próximos passos. Por exemplo:

Conclusão

Logto oferece segurança de nível empresarial através de fluxos de login sem senha flexíveis usando links mágicos. É uma maneira simples, mas poderosa de criar experiências de usuário suaves—seja para convidar usuários a se juntarem a uma organização, permitir que eles criem contas sem esforço, ou fornecer autenticação sem complicações. E porque o Logto lida com situações complicadas como conflitos de conta e tokens expirados, seus usuários têm um processo seguro e sem frustrações toda vez.

Pronto para modernizar seu IAM com autenticação à prova de balas?

Experimente o Logto Cloud gratuitamente

O que é um link mágico?#

Composição de um link mágico#

Fluxo de trabalho de um link mágico#

Como implementar links mágicos com Logto?#

Etapa 1: Solicitar token de uso único#

Etapa 2: Compor seu link mágico#

Etapa 3: Disparar o fluxo de autenticação via Logto SDK#

Casos de uso de links mágicos#

Registro somente por convite com link mágico#

Convite de membro de organização com link mágico#

Lidar com conflitos de conta#

Lidar com páginas de erros para link mágico invalidado#

Conclusão#

O que é um link mágico?#

Composição de um link mágico#

Fluxo de trabalho de um link mágico#

Como implementar links mágicos com Logto?#

Etapa 1: Solicitar token de uso único#

Etapa 2: Compor seu link mágico#

Etapa 3: Disparar o fluxo de autenticação via Logto SDK#

Casos de uso de links mágicos#

Registro somente por convite com link mágico#

Convite de membro de organização com link mágico#

Lidar com conflitos de conta#

Lidar com páginas de erros para link mágico invalidado#

Conclusão#

O que é um link mágico?

Composição de um link mágico

Fluxo de trabalho de um link mágico

Como implementar links mágicos com Logto?

Etapa 1: Solicitar token de uso único

Etapa 2: Compor seu link mágico

Etapa 3: Disparar o fluxo de autenticação via Logto SDK

Casos de uso de links mágicos

Registro somente por convite com link mágico

Convite de membro de organização com link mágico

Lidar com conflitos de conta

Lidar com páginas de erros para link mágico invalidado

Conclusão

O que é um link mágico?

Composição de um link mágico

Fluxo de trabalho de um link mágico

Como implementar links mágicos com Logto?

Etapa 1: Solicitar token de uso único

Etapa 2: Compor seu link mágico

Etapa 3: Disparar o fluxo de autenticação via Logto SDK

Casos de uso de links mágicos

Registro somente por convite com link mágico

Convite de membro de organização com link mágico

Lidar com conflitos de conta

Lidar com páginas de erros para link mágico invalidado

Conclusão