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.
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, retornecreateUser. - Quando
event.userestá presente, retorneupdateUser. passwordVerifieddeve ser literalmentetrue.userpode 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 }.codesdeve conter de 1 a 10 códigos, cada um com 10 caracteres de0-9ea-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? }.credentialIdepublicKeysã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.
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.
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:
- A verificação de senha local falha, então o Logto executa a Ação.
- O script envia o identificador e a senha para o sistema legado.
- O sistema legado verifica as credenciais e o script retorna
createUserouupdateUser. - O Logto cria ou atualiza o usuário, armazena a senha enviada como uma nova credencial local Argon2i e grava quaisquer fatores MFA migrados.
- O usuário completa o MFA se necessário, incluindo um fator migrado, e o Logto conclui o login.
- 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
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: trueapenas 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
customDataou 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.PostFirstFactorVerificationnos 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.