Pular para o conteúdo principal

Magic link (Token de uso único)

Cloud availabilityOSS availability

Semelhante à senha de uso único (OTP), um token de uso único é outro método de autenticação sem senha que pode ser usado para verificar a identidade de um usuário. O token é válido por um período limitado de tempo e está associado ao endereço de email do usuário final.

Às vezes, você pode querer convidar novos usuários para seu aplicativo / organização sem exigir que eles criem uma conta primeiro. Ou você pode esquecer sua senha e querer fazer login / redefinir sua senha rapidamente verificando sua identidade por email. Nesses casos, o aplicativo pode enviar um "magic link" para seu email. E você será autenticado imediatamente ao clicar no link.

Os desenvolvedores de aplicativos podem usar o token de uso único para compor um magic link e enviá-lo para o endereço de email do usuário final.

Fluxo do token de uso único​

Aqui está o diagrama de sequência do fluxo de autenticação usando token de uso único:

Guia de implementação​

O Logto oferece um conjunto de Management APIs e Experience APIs para facilitar a implementação do seu magic link.

Antes de começar, certifique-se de que você tem uma instância Logto pronta e estabeleceu a conexão Máquina para Máquina entre o servidor do seu aplicativo e o endpoint Logto (necessário para as Management APIs). Saiba mais sobre a Logto Management API.

Passo 1: Solicitar token de uso único​

Use a Logto Management API para criar um token de uso único.

POST /api/one-time-tokens

Exemplo de payload do corpo da requisição:

{
  "email": "[email protected]",
  // Opcional. Padrão é 600 (10 minutos).
  "expiresIn": 3600,
  // Opcional. O usuário será provisionado para as organizações especificadas após verificação bem-sucedida.
  "context": {
    "jitOrganizationIds": ["abcdefgh1234"]
  }
}

Depois de obter o token de uso único, você pode compor um magic link e enviá-lo para o endereço de email do usuário final. O magic link deve conter pelo menos o token e o email do usuário como parâmetros, e deve direcionar para uma landing page em seu próprio aplicativo. Exemplo: https://yourapp.com/landing-page.

Aqui está um exemplo simples de como o magic link pode ser:

https://yourapp.com/landing-page?token=YHwbXSXxQfL02IoxFqr1hGvkB13uTqcd&[email protected]
nota:

Os nomes dos parâmetros no magic link podem ser totalmente personalizados. Você pode adicionar informações adicionais ao magic link conforme as necessidades do seu aplicativo, bem como codificar todos os parâmetros da URL.

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

Depois que o usuário final clicar no magic link e for direcionado ao 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 acionar o fluxo de autenticação.

TokenLandingPage.tsx
// Exemplo React
import { useLogto } from '@logto/react';
import { useEffect } from 'react';
import { useSearchParams } from 'react-router-dom';

const TokenLandingPage = () => {
  const { signIn } = useLogto();
  const [searchParams] = useSearchParams();

  useEffect(() => {
    // Extrai o token e o email do magic link
    const oneTimeToken = searchParams.get('token');
    const email = searchParams.get('email');

    // Supondo que este seja seu redirect URI de login
    const redirectUri = 'https://yourapp.com/callback';

    if (oneTimeToken && email) {
      signIn({
        redirectUri,
        clearTokens: false, // Opcional. Veja o aviso abaixo
        extraParams: {
          'one_time_token': oneTimeToken,
          'login_hint': email,
        },
      });
    }
  }, [searchParams, signIn]);

  return <>Por favor, aguarde...</>;
};
atenção:

Se um usuário já estiver autenticado, chamar a função signIn() do SDK irá automaticamente limpar todos os tokens em cache (Token de ID, Token de acesso e Token de atualização) do armazenamento do cliente, o que resulta na perda do status de autenticação do usuário atual.

Portanto, você deve especificar um parâmetro adicional de login clearTokens: false para evitar a limpeza dos tokens existentes. Se isso for especificado, você também precisará limpar manualmente os tokens na página de callback do login.

Ignore isso se seus magic links não forem projetados para usuários já autenticados.

Passo 4: (Opcional) Limpar tokens em cache na página de callback do login​

Se você especificar clearTokens: false na função de login, será necessário limpar manualmente os tokens na página de callback do login.

Callback.tsx
// Exemplo React
import { useHandleSignInCallback, useLogto } from '@logto/react';
import { useEffect } from 'react';

const Callback = () => {
  const { clearAllTokens } = useLogto();

  useEffect(() => {
    void clearAllTokens();
  }, [clearAllTokens]);

  useHandleSignInCallback(() => {
    // Navegue para sua página inicial
  });

  return <>Por favor, aguarde...</>;
};

Perguntas frequentes​

Sim, você pode usar o magic link para convidar novos usuários para seu aplicativo, bem como para organizações. Se quiser convidar novos usuários para sua organização, basta especificar o jitOrganizationIds no corpo da requisição.

O usuário ingressará automaticamente nas organizações após a verificação bem-sucedida, e os papéis padrão da organização serão atribuídos. Confira a seção "Just-in-time provisioning" na página de detalhes da sua organização e configure os papéis padrão para suas organizações.

O token de uso único expira?​

Sim, o token de uso único irá expirar após o tempo especificado em expiresIn (em segundos). O tempo padrão de expiração é 10 minutos.

Sim, você ainda pode usar magic link para convidar usuários mesmo que desative o registro de usuários em "Experiência de login".

Existem vários cenários possíveis:

  1. O usuário já está autenticado e clica em um magic link associado à conta do usuário atual. Nesse caso, o Logto ainda irá verificar o token de uso único e provisionar o usuário para as organizações especificadas, se necessário.
  2. O usuário já está autenticado e clica em um magic link associado a uma conta diferente. Nesse caso, o Logto solicitará ao usuário que continue como a nova conta ou volte ao aplicativo com a conta atual.
    1. Se o usuário escolher continuar como a nova conta, o Logto mudará para a nova conta após a verificação bem-sucedida do token.
    2. Se o usuário escolher permanecer na conta atual, o Logto não verificará o token e retornará ao aplicativo com a conta atual.
  3. Se seu prompt de login estiver definido como "login" ou contiver "login", o Logto fará automaticamente o login da conta associada ao token de uso único sem solicitar a troca.