Pular para o conteúdo principal

Verificação pós-primeiro fator (Post first-factor verification)

A Ação de verificação pós-primeiro fator oferece suporte à migração de usuários just-in-time de um sistema de senha legado.

Apesar do nome, esta Ação não é executada após todo primeiro fator bem-sucedido. Ela só é executada quando todas as condições a seguir são verdadeiras:

  • A interação da Experience API é SignIn.
  • O usuário enviou um nome de usuário, endereço de e-mail ou número de telefone com uma senha.
  • A verificação de senha local do Logto falhou.
  • Se o identificador pertence a um usuário Logto existente, esse usuário não está suspenso.

Se a senha local for válida, o Logto continua sem executar a Ação. Tentativas de registro, esqueci a senha, login sem senha e usuários suspensos não a acionam.

Payload do evento​

O event tem este formato:

type PostFirstFactorVerificationEvent = {
// Mantido para compatibilidade retroativa após o recurso ser renomeado para Actions.
key: 'inlineHook.postFirstFactorVerification';
interactionEvent: 'SignIn';
verificationType: 'Password';
identifier: {
type: 'username' | 'email' | 'phone';
value: string;
};
user: {
id: string;
username: string | null;
primaryEmail: string | null;
primaryPhone: string | null;
name: string | null;
avatar: string | null;
customData: Record<string, unknown>;
profile: Record<string, unknown>;
} | null;
password: string;
};

user é null quando o identificador não pertence a um usuário Logto. Caso contrário, contém o contexto de perfil editável do usuário existente.

perigo:

event.password é a senha em texto puro enviada pelo usuário. Envie-a apenas para seu endpoint de autenticação legado confiável via HTTPS. Nunca registre, armazene, coloque em customData, inclua em um erro ou retorne da Ação.

Resultado​

Após o sistema legado verificar as credenciais enviadas, retorne um destes resultados:

type ActionMfaVerification =
| {
type: 'Totp';
secret: string;
}
| {
type: 'BackupCode';
codes: string[];
}
| {
type: 'WebAuthn';
credentialId: string;
publicKey: string;
counter: number;
transports?: ('usb' | 'nfc' | 'ble' | 'internal' | 'cable' | 'hybrid' | 'smart-card')[];
agent?: string;
name?: string;
};

type PostFirstFactorVerificationResult =
| {
action: 'createUser';
passwordVerified: true;
user: ActionUserPatch;
mfaVerifications?: ActionMfaVerification[];
}
| {
action: 'updateUser';
passwordVerified: true;
user: ActionUserPatch;
mfaVerifications?: ActionMfaVerification[];
};

O resultado deve corresponder ao evento:

  • Quando event.user é null, retorne createUser.
  • Quando event.user está presente, retorne updateUser.
  • passwordVerified deve ser literalmente true.
  • user pode conter apenas os campos de patch de usuário suportados.

Para um novo usuário, o Logto adiciona o identificador de login enviado quando o resultado não o inclui. A Ação não pode alterar o identificador enviado para outro valor. A comparação de e-mail é case-insensitive, números de telefone são comparados após normalização e nomes de usuário devem coincidir exatamente.

Quando o resultado é aceito, o Logto faz o hash da senha enviada com Argon2i e a salva como senha local do usuário. O script não deve gerar nem retornar um hash de senha.

Retorne undefined quando o sistema legado rejeitar as credenciais. Um resultado vazio, malformado ou não suportado também é tratado como credenciais inválidas.

Migrar fatores MFA​

Inclua mfaVerifications para migrar os fatores MFA existentes do usuário junto com a senha. O Logto adiciona os fatores aos fatores existentes do usuário e ativa o MFA para a conta, de modo que o mesmo login seja desafiado por um dos fatores migrados quando o MFA for exigido. O tipo de fator deve estar habilitado nas configurações de MFA da experiência de login para ser desafiado. Uma configuração skipMfaOnSignIn que o usuário ou um administrador já definiu na conta é mantida.

  • TOTP — { type: 'Totp', secret }. secret é um segredo TOTP em Base32. O Logto remove espaços em branco, converte para maiúsculas e adiciona padding Base32 antes de validar; o resultado deve ter de 16 a 32 caracteres. Um usuário pode ter apenas um fator TOTP.
  • Códigos de backup — { type: 'BackupCode', codes }. codes deve conter de 1 a 10 códigos, cada um com 10 caracteres de 0-9 e a-f. Códigos migrados são armazenados como não usados, então envie apenas os códigos que ainda não foram usados no sistema legado. Códigos de backup não podem ser o único fator: o usuário já deve ter outro fator ou receber um no mesmo resultado.
  • WebAuthn — { type: 'WebAuthn', credentialId, publicKey, counter, transports?, agent?, name? }. credentialId e publicKey são strings Base64URL sem padding; publicKey é a chave pública da credencial. Apenas credenciais registradas para o domínio em que o usuário faz login no Logto podem ser verificadas, então não migre passkeys registradas para outro domínio.

Um fator idêntico a um que o usuário já possui é ignorado: o mesmo segredo TOTP, uma credencial WebAuthn com o mesmo credentialId e publicKey, ou códigos de backup que já estão todos no conjunto do usuário, usados ou não. Um código já usado permanece usado.

Um fator conflitante faz o login falhar com um erro em vez de substituir o fator existente. Isso cobre um segredo TOTP diferente quando o usuário já tem TOTP, novos códigos de backup quando o conjunto existente do usuário ainda tem códigos não usados e uma credencial WebAuthn já registrada para este ou outro usuário. Quando todos os códigos de backup existentes tiverem sido usados, os códigos migrados substituem o conjunto esgotado. O erro não inclui nenhum valor de credencial.

Se algum fator falhar na validação, todo o resultado é tratado como credenciais inválidas e nada é gravado.

nota:

Uma credencial WebAuthn migrada pode ser usada para MFA imediatamente, mas não pode ser usada para login com passkey até que o usuário complete o MFA com ela uma vez. Essa primeira verificação de MFA registra o domínio da credencial, que o login com passkey precisa para encontrá-la.

Os fatores são gravados uma vez. Após uma migração bem-sucedida, logins posteriores verificam a senha local e esta Ação não é mais executada para esse usuário.

perigo:

mfaVerifications carrega credenciais de longa duração. Não registre o segredo TOTP, códigos de backup ou dados de credencial WebAuthn, não os inclua em erros nem os retorne em qualquer lugar exceto em mfaVerifications.

Exemplo de migração​

Configure LEGACY_VERIFY_URL e LEGACY_API_TOKEN como variáveis de ambiente da Ação e adapte este script para sua API legada:

const runAction = async ({ event, environmentVariables = {} }) => {
const response = await fetch(environmentVariables.LEGACY_VERIFY_URL, {
method: 'POST',
headers: {
'content-type': 'application/json',
authorization: `Bearer ${environmentVariables.LEGACY_API_TOKEN}`,
},
body: JSON.stringify({
identifier: event.identifier,
password: event.password,
}),
});

// Trate uma rejeição de autenticação como um resultado comum de credenciais inválidas.
if (response.status === 401 || response.status === 404) {
return;
}

if (!response.ok) {
throw new Error(`O serviço de autenticação legado retornou ${response.status}`);
}

const legacyUser = await response.json();

if (!legacyUser.passwordVerified) {
return;
}

return {
action: event.user ? 'updateUser' : 'createUser',
passwordVerified: true,
user: {
...(legacyUser.name && { name: legacyUser.name }),
customData: {
migratedFrom: 'legacy',
legacyUserId: legacyUser.id,
},
},
};
};

Se o usuário legado tiver fatores MFA, mapeie-os para o mesmo resultado:

const toActionMfaVerifications = (legacyUser) => [
...(legacyUser.totpSecret
? [
{
type: 'Totp',
secret: legacyUser.totpSecret,
},
]
: []),
...(legacyUser.backupCodes?.length
? [
{
type: 'BackupCode',
codes: legacyUser.backupCodes,
},
]
: []),
...(legacyUser.passkeys ?? []).map((passkey) => ({
type: 'WebAuthn',
credentialId: passkey.credentialId,
publicKey: passkey.publicKey,
counter: passkey.counter,
})),
];

Adicione mfaVerifications: toActionMfaVerifications(legacyUser) ao resultado retornado. Omitir o campo quando o usuário legado não tiver fatores MFA.

O primeiro login aceito funciona da seguinte forma:

  1. A verificação de senha local falha, então o Logto executa a Ação.
  2. O script envia o identificador e a senha para o sistema legado.
  3. O sistema legado verifica as credenciais e o script retorna createUser ou updateUser.
  4. O Logto cria ou atualiza o usuário, armazena a senha enviada como uma nova credencial local Argon2i e grava quaisquer fatores MFA migrados.
  5. O usuário completa o MFA se necessário, incluindo um fator migrado, e o Logto conclui o login.
  6. Em logins posteriores, a senha local migrada é aceita, então esta Ação não é mais chamada para esse usuário.

Limites de segurança​

atenção:

Usuário, senha e gravações de MFA desta Ação acontecem antes do MFA ser concluído. Se o usuário abandonar ou falhar no MFA, essas gravações permanecem.

Um usuário criado por esta Ação também ignora proteções exclusivas de registro, incluindo listas de bloqueio de e-mail, regras de domínio apenas SSO, modo de cadastro desativado e verificações obrigatórias de perfil de registro. A proteção Sentinel e o MFA ainda se aplicam.

Use estas salvaguardas:

  • Retorne passwordVerified: true apenas após o sistema legado ter verificado positivamente a senha exata enviada.
  • Mantenha o endpoint legado privado sempre que possível, exija autenticação de serviço, use HTTPS e aplique limitação de taxa.
  • Mantenha o patch de usuário retornado mínimo. Não copie identificadores ou dados de perfil não validados.
  • Trate segredos TOTP, códigos de backup e dados de credencial WebAuthn como credenciais. Não os registre, coloque em customData ou inclua em erros.
  • Teste criação de usuário desconhecido, atualização de usuário existente, colisões de identificador, usuários suspensos, migração e conflitos de MFA, falhas upstream e tentativas concorrentes.
  • Monitore Action.PostFirstFactorVerification nos logs de auditoria.
  • Mantenha a Ação habilitada apenas durante a migração, quando possível.

Se você puder exportar dados de usuário e hashes de senha compatíveis com antecedência, considere a migração em massa de usuários.