Português (Portugal)

Magic link
Sem senha
Autenticação
Convite

Autenticação por link mágico

Aprenda a implementar links mágicos para acesso sem senha, registo apenas por convite, e convites para membros de organizações usando tokens de uso único.

Ran

Product & Design

6/6/2025

Pare de perder semanas com autenticação de utilizadores

Lance aplicações seguras mais rapidamente com o Logto. Integre a autenticação de utilizadores 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 utilizador recebe um URL de login de uso único por email (ou SMS). Ao clicar no link, é efetuado o login sem a necessidade de uma senha.

Aqui estão algumas características de segurança importantes dos links mágicos:

Token de uso único: Uma vez clicado, o token torna-se inválido para prevenir reutilização.
Expiração do link: O link mágico deve ter um tempo de expiração curto (por exemplo, 10 minutos) para segurança adicional.
Limitação de taxa: Prevenir abuso limitando quantos links mágicos podem ser enviados num determinado período de tempo.
Vinculação de dispositivo/navegador (Opcional): Restringir 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 do URL: Aponta para a página de destino da sua aplicação.
Token de uso único: Um token único e de consumo único usado para autenticação sem senha.
Email do utilizador: Usado para validar a autenticidade do token e a identidade do utilizador.
Parâmetros adicionais: Opcionais, dependendo das necessidades da sua aplicação.

Por exemplo, um link mágico pode ser algo assim:

Para criar um link mágico, precisa gerar um token de uso único, enviá-lo com segurança ao utilizador e depois validá-lo quando o utilizador clicar no link.

Fluxo de trabalho de um link mágico

O utilizador solicita um link mágico: O utilizador insere seu email na sua aplicação.
Geração de token de uso único: O servidor gera um token e envia-o como um link via email.
O utilizador clica no link: O utilizador clica no link no email.
Validação do token: O servidor verifica se o token é válido.
O utilizador é autenticado: Se o token é válido, o utilizador é autenticado automaticamente.

Como implementar links mágicos com Logto?

Passo 1: Requisitar token de uso único

Use a API de Gestão do Logto para criar um token de uso único.

Exemplo de payload do corpo da requisição:

Passo 2: Compor seu link mágico

Depois de obter o token de uso único, pode compor um link mágico e enviá-lo para o email do utilizador final. O link mágico deve conter pelo menos o token e o email do utilizador como parâmetros e deve navegar para uma página de destino na sua própria aplicação. Ex.: 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. Pode adicionar informações adicionais ao link mágico com base nos requisitos da sua aplicação, bem como codificar todos os parâmetros do URL.

Passo 3: Acionar o fluxo de autenticação via Logto SDK

Depois que o utilizador final clica no link mágico e é redirecionado para a sua aplicação, pode extrair os parâmetros token e email do URL e então chamar a função signIn() do Logto SDK para acionar o fluxo de autenticação.

Para mais detalhes, consulte os Documentos Logto - Link Mágico (Token de Uso Único).

Casos de uso de link mágico

Links mágicos podem substituir a etapa de autenticação de primeiro fator, mas não podem substituir a Autenticação de Múltiplos Fatores (MFA).

No Logto, ao gerar um link mágico com um token de uso único, não precisa especificar se é para login ou registro. Determinamos automaticamente o fluxo com base no status de registo do email:

Email não registado: Clicar no link mágico redireciona o utilizador para o fluxo de criação de conta, pulando a entrada e verificação de email. O utilizador avança para definir uma senha, adicionar detalhes de perfil (por exemplo, nome completo) ou configurar MFA, com base nas configurações do seu registo.
Email registado: Clicar no link mágico ignora a verificação do primeiro passo (por exemplo, “email + senha” ou “email + código de verificação”). O utilizador é autenticado diretamente ou solicitado a completar MFA, com base nas configurações de login.

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

Registo apenas por convite: Para ferramentas internas ou produtos de IA em fase de teste, pode desativar o registo público e convidar utilizadores específicos via um link mágico.
Convite para membros de organizações: Para produtos SaaS, use links mágicos para convidar novos membros para uma organização, facilitando o processo de associação.
Login/Registo: Envie um link mágico para login ou registo via email.

Atualmente não suportado:

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

Deixe-nos saber se precisar de personalizações adicionais.

Registo apenas por convite com link mágico

Para novos produtos (por exemplo, ferramentas de IA) em teste interno ou para ferramentas internas, pode querer desativar o registo público e permitir apenas que utilizadores específicos acedam à sua aplicação. Para implementar isto com Logto:

Acesse Consola > Experiência de Login > Login e registo > Opções avançadas, e desative "Ativar registo de utilizador" para fechar o registo público.
Colete os endereços de email dos utilizadores que deseja convidar (por exemplo, pelo seu website ou recomendações de utilizadores existentes).
Crie e envie o link de convite mágico conforme descrito acima (solicite o token de uso único, componha o link mágico, acione a autenticação via Logto SDK).

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

Quando os utilizadores clicarem em "Aceitar o convite", eles automaticamente se registam no seu serviço, mesmo com o registo público desativado. Isto é referido como "Convite de utilizador direcionado".

Convite para membros de organização com link mágico

Para produtos multiinquilino (por exemplo, aplicações SaaS como Slack, GitHub, Vercel), fornecer um processo de convite de membros sem complicações para gerenciar associações de organizações. Use links mágicos para uma maior taxa de conversão em convites de membros.

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

Quando os utilizadores clicarem em "Aceitar o convite", eles irão automaticamente fazer login ou registo e automaticamente ingressar na organização.

Lidar com conflitos de conta

O que acontece se um utilizador já está autenticado e clica em outro link mágico?

Para lidar corretamente com conflitos de conta, garanta o seguinte:

Evitar adicionar login no "prompt de login": Não defina o prompt de login incluindo login. Se definido incorretamente, o Logto autentica automaticamente a conta associada ao token do link mágico, ignorando o prompt de troca de conta.
Preservar tokens existentes: Ao chamar a função signIn(), especifique o parâmetro clearTokens: false para evitar limpar tokens existentes. Se esta opção for usada, garanta que limpa manualmente os tokens na página de retorno de login.

Após a configuração correta, a experiência do utilizador será a seguinte:

Link mágico para a conta atual: Se o utilizador já está autenticado e clica em um link mágico para a mesma conta, o Logto verifica o token de uso único e provisiona o utilizador para as organizações especificadas, se necessário.
Link mágico para uma conta diferente: Se o utilizador está autenticado e clica em um link mágico para uma conta diferente, o Logto solicita ao utilizador que:
- Continue como a nova conta: O Logto troca para a nova conta após a verificação do token.
- Permaneça com a conta atual: O Logto ignora a verificação do token e retorna o utilizador à conta atual.

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

Quando os utilizadores clicam num link mágico inválido, sã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 incompatível com o token fornecido.
token_expired	O token está expirado.
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 apresentará uma mensagem específica, ajudando os utilizadores a entender o motivo por trás do link mágico inválido e orientando-os sobre os próximos passos. Por exemplo:

Conclusão

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 suaves para os utilizadores — sejam convidados para se juntarem a uma organização, permitindo-lhes criar contas sem esforço ou fornecendo autenticação sem complicações. E porque o Logto lida com situações complicadas como conflitos de conta e tokens expirados, seus utilizadores têm um processo seguro e livre de frustrações a cada vez.

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

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?#

Passo 1: Requisitar token de uso único#

Passo 2: Compor seu link mágico#

Passo 3: Acionar o fluxo de autenticação via Logto SDK#

Casos de uso de link mágico#

Registo apenas por convite com link mágico#

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

Lidar com conflitos de conta#

Lidar com páginas de erro 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?#

Passo 1: Requisitar token de uso único#

Passo 2: Compor seu link mágico#

Passo 3: Acionar o fluxo de autenticação via Logto SDK#

Casos de uso de link mágico#

Registo apenas por convite com link mágico#

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

Lidar com conflitos de conta#

Lidar com páginas de erro 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?

Passo 1: Requisitar token de uso único

Passo 2: Compor seu link mágico

Passo 3: Acionar o fluxo de autenticação via Logto SDK

Casos de uso de link mágico

Registo apenas por convite com link mágico

Convite para membros de organização com link mágico

Lidar com conflitos de conta

Lidar com páginas de erro 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?

Passo 1: Requisitar token de uso único

Passo 2: Compor seu link mágico

Passo 3: Acionar o fluxo de autenticação via Logto SDK

Casos de uso de link mágico

Registo apenas por convite com link mágico

Convite para membros de organização com link mágico

Lidar com conflitos de conta

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

Conclusão