Tutorial: Habilitar a autenticação multifator em um aplicativo de página única do React usando o SDK javaScript de autenticação nativa

Aplica-se a: Círculo verde com um símbolo de marca de seleção branca que indica que o conteúdo a seguir se aplica a locatários externos. Locatários externos (saiba mais)

Neste tutorial, você aprenderá a adicionar autenticação multifator (MFA) em seu aplicativo de página única React (SPA) usando o SDK JavaScript da autenticação nativa.

Assim como no registro de método de autenticação forte, o processo MFA ocorre em três cenários:

Durante o login: o usuário faz login e tem um método de autenticação forte registrado.
Após a inscrição: depois que o usuário concluir a inscrição, ele procede para entrar. Novos usuários precisam registrar um método de autenticação forte antes de qualquer desafio de MFA. Como o método de autenticação forte também é verificado durante o registro, eles podem não ser solicitados a realizar um desafio adicional de MFA.
Após a redefinição de senha de autoatendimento (SSPR): o usuário redefine a senha com êxito e continua a entrar automaticamente. Se o usuário tiver um método de autenticação forte registrado, será solicitado que ele conclua o desafio de MFA.

Quando a MFA é necessária, o usuário escolhe um método de desafio de MFA em uma lista de métodos registrados. As opções disponíveis são senha única de email , senha única de SMS ou ambas, dependendo do que o usuário registrou anteriormente.

O diagrama de fluxo abaixo ilustra os três cenários:

Conclua o desafio de autenticação multifator.

Pré-requisitos

Conclua as etapas de inscrição, entrada, redefinição de senha e registre tutoriais de método de autenticação forte .
Visual Studio Code ou outro editor de código.
Node.js.
Habilite a MFA (autenticação multifator) para seu aplicativo.

Habilitar o aplicativo para lidar com a autenticação multifator

Para habilitar a MFA em seu aplicativo React, atualize a configuração do aplicativo adicionando a funcionalidade necessária:

Localize o arquivo src/config/auth-config.ts .
No objeto customAuth, adicione ou atualize a propriedade capabilities para incluir o valor mfa_required no array, conforme mostrado no seguinte snippet de código:
```
const customAuthConfig: CustomAuthConfiguration = {
    customAuth: {
        ...
        capabilities: ["mfa_required"],
        ...
    },
    ...
};
```

O valor da capacidade mfa_required informa o Microsoft Entra que o seu aplicativo pode lidar com um fluxo de MFA. Saiba mais sobre os tipos e funcionalidades de desafio de autenticação nativa.

Criar componentes de interface do usuário

Você precisa de componentes de formulário em seu aplicativo para dar suporte ao fluxo de MFA. Use as seguintes etapas para adicionar esses componentes ao seu aplicativo:

Crie uma nova pasta, src/app/shared/components para componentes reutilizáveis (se ainda não existir).
Na nova pasta, crie um arquivo chamado MfaAuthMethodSelectionForm.tsx para exibir um formulário que permite aos usuários selecionar um método de autenticação forte registrado. Adicione o código em MfaAuthMethodSelectionForm no arquivo.
Na nova pasta, crie outro arquivo chamado MfaChallengeForm.tsx para exibir um formulário para verificar o método de autenticação forte usando a senha única recebida pelo usuário. Adicione o código em MfaChallengeForm no arquivo.

Quando necessário, você pode importar e usar componentes reutilizáveis em seu login, login após o cadastro e login após o fluxo de SSPR.

Atualize o arquivo src/app/sign-in/page.tsx para permitir que seu aplicativo manipule o fluxo de MFA durante a entrada. Consulte o código completo em page.tsx:

Importe os tipos e componentes necessários, conforme mostrado no seguinte snippet de código:

import {
    CustomAuthPublicClientApplication,
    ICustomAuthPublicClientApplication,
    SignInCodeRequiredState,
    SignInCompletedState,
    AuthFlowStateBase,
    MfaAwaitingState,
    MfaVerificationRequiredState,
} from "@azure/msal-browser/custom-auth";
import { MfaAuthMethodSelectionForm } from "../components/shared/MfaAuthMethodSelectionForm";
import { MfaChallengeForm } from "../components/shared/MfaChallengeForm";

Adicione novas variáveis de estado para MFA:

export default function SignIn() {
    ...
    // MFA states
const [mfaAuthMethods, setMfaAuthMethods] = useState<AuthenticationMethod[]>([]);
const [selectedMfaAuthMethod, setSelectedMfaAuthMethod] = useState<AuthenticationMethod | undefined>(undefined);
const [mfaChallenge, setMfaChallenge] = useState("");

    // ... initialization code
}

Atualize as funções startSignIn, handlePasswordSubmit e handleCodeSubmit para verificar se a MFA é necessária.

const startSignIn = async (e: React.FormEvent) => {
    // Start the sign-in flow
    const result = await authClient.signIn({
        username,
    });

    ...

    if (result.isMfaRequired()) {
        const methods = result.state.getAuthMethods();
        setMfaAuthMethods(methods);
        setSelectedMfaAuthMethod(methods.length > 0 ? methods[0] : undefined);
    }

    ...
};

const handlePasswordSubmit = async (e: React.FormEvent) => {
    if (signInState instanceof SignInPasswordRequiredState) {
        const result = await signInState.submitPassword(password);

        ...

        // Check for MFA requirement
        if (result.isMfaRequired()) {
            const methods = result.state.getAuthMethods();
            setMfaAuthMethods(methods);
            setSelectedMfaAuthMethod(methods.length > 0 ? methods[0] : undefined);
            setSignInState(result.state);
        }

        ...
    }
};

const handleCodeSubmit = async (e: React.FormEvent) => {
    if (signInState instanceof SignInCodeRequiredState) {
        const result = await signInState.submitCode(code);

        ...

        // Check for MFA requirement
        if (result.isMfaRequired()) {
            const methods = result.state.getAuthMethods();
            setMfaAuthMethods(methods);
            setSelectedMfaAuthMethod(methods.length > 0 ? methods[0] : undefined);
            setSignInState(result.state);
        }

        ...
    }
};

Em cada uma das funções, observe que verificamos se a autenticação multifator é necessária usando o seguinte trecho de código:

if (result.isMfaRequired()) {...}

Adicione o manipulador para a seleção de desafio de MFA:

const handleMfaAuthMethodSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setError("");
    setLoading(true);

    if (!selectedMfaAuthMethod) {
        setError("Please select an authentication method.");
        setLoading(false);
        return;
    }

    if (signInState instanceof MfaAwaitingState) {
        const result = await signInState.requestChallenge(selectedMfaAuthMethod.id);

        if (result.isFailed()) {
            if (result.error?.isInvalidInput()) {
                setError("Incorrect verification contact.");
            } else {
                setError(
                    result.error?.errorData?.errorDescription ||
                        "An error occurred while verifying the authentication method"
                );
            }
        }

        if (result.isVerificationRequired()) {
            setSignInState(result.state);
        }
    }

    setLoading(false);
};

Adicione o manipulador para verificação de desafio de MFA:

const handleMfaChallengeSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setError("");
    setLoading(true);

    if (!mfaChallenge) {
        setError("Please enter a code.");
        setLoading(false);
        return;
    }

    if (signInState instanceof MfaVerificationRequiredState) {
        const result = await signInState.submitChallenge(mfaChallenge);

        if (result.isFailed()) {
            if (result.error?.isIncorrectChallenge()) {
                setError("Incorrect code.");
            } else {
                setError(
                    result.error?.errorData?.errorDescription ||
                        "An error occurred while verifying the challenge response"
                );
            }
        }

        if (result.isCompleted()) {
            setData(result.data);
            setCurrentSignInStatus(true);
            setSignInState(result.state);
        }
    }

    setLoading(false);
};

Atualize a função renderForm() para exibir os formulários corretos de desafio MFA (seleção do método de desafio MFA ou verificação do método de desafio MFA):

const renderForm = () => {
    if (loadingAccountStatus) {
        return;
    }

    ...

    // Display MfaAuthMethodSelectionForm if the current state is MFA awaiting state
    if (signInState instanceof MfaAwaitingState) {
        return (
            <MfaAuthMethodSelectionForm
                onSubmit={handleMfaAuthMethodSubmit}
                authMethods={mfaAuthMethods}
                selectedAuthMethod={selectedMfaAuthMethod}
                setSelectedAuthMethod={setSelectedMfaAuthMethod}
                loading={loading}
                styles={styles}
            />
        );
    }

    // Display MfaChallengeForm if the current state is MFA verification required state
    if (signInState instanceof MfaVerificationRequiredState) {
        return (
            <MfaChallengeForm
                onSubmit={handleMfaChallengeSubmit}
                challenge={mfaChallenge}
                setChallenge={setMfaChallenge}
                loading={loading}
                styles={styles}
            />
        );
    }

    ...
};

O fluxo de MFA após a inscrição e a redefinição de senha funciona de forma semelhante ao fluxo de autenticação com MFA. Após uma inscrição bem-sucedida ou redefinição de senha, o SDK pode continuar automaticamente com o fluxo de entrada. Se o usuário tiver um método de autenticação forte registrado, o fluxo fará a transição para a verificação de desafio de MFA.

Para o fluxo de MFA após a inscrição, você precisa atualizar o arquivo /src/app/sign-up/page.tsx . Consulte o código completo em page.tsx:

Certifique-se de importar os tipos e componentes necessários.

Tratar os estados de requisitos de MFA da mesma forma que ocorre no fluxo de login; depois que a inscrição for concluída com êxito, use o resultado para disparar automaticamente um fluxo de login, como demonstrado no seguinte snippet de código.

// In your sign-up completion handler
if (signUpState instanceof SignUpCompletedState) {
    // Continue with sign-in using the continuation token
    const result = await signUpState.signIn();

    ...

    if (result.isMfaRequired()) {
        const methods = result.state.getAuthMethods();
        setMfaAuthMethods(methods);
        setSelectedMfaAuthMethod(methods.length > 0 ? methods[0] : undefined);
        setSignUpState(state);
    }

    ...
}

// Then use the same renderForm logic to display MfaAuthMethodSelectionForm
// and MfaChallengeForm components

Manipular a autenticação multifator após a redefinição de senha

Para o fluxo de MFA após o SSPR, você precisa atualizar o arquivo /src/app/reset-password/page.tsx . Consulte o código completo em page.tsx:

Certifique-se de importar os tipos e componentes necessários.

Manipule os estados de requisito de MFA de maneira semelhante à do fluxo de login. Depois que o SSPRS for concluído com êxito, você poderá usar o resultado para disparar automaticamente um login, conforme mostrado no seguinte trecho de código:

// In your password reset completion handler
if (resetPasswordState instanceof ResetPasswordCompletedState) {
    // Continue with sign-in using the continuation token
    const result = await signUpState.signIn();

    ...

    if (result.isMfaRequired()) {
        const methods = result.state.getAuthMethods();
        setMfaAuthMethods(methods);
        setSelectedMfaAuthMethod(methods.length > 0 ? methods[0] : undefined);
        setResetState(state);
    }

    ...
}

// Then use the same renderForm logic to display MfaAuthMethodSelectionForm
// and MfaChallengeForm components

Executar e testar seu aplicativo

Antes de testar seu aplicativo, verifique se você tem uma conta de usuário que tem um método de autenticação forte registrado. Use as etapas em Executar e testar seu aplicativo para executar seu aplicativo, mas desta vez, teste o fluxo de MFA.

Autenticação Nativa com Microsoft Entra External ID
Recursos de autenticação nativa e tipos de desafio
Fallback web de autenticação nativa

Comentários

Esta página foi útil?

Última atualização em 2026-03-12

Tutorial: Habilitar a autenticação multifator em um aplicativo de página única do React usando o SDK javaScript de autenticação nativa

Pré-requisitos

Habilitar o aplicativo para lidar com a autenticação multifator

Criar componentes de interface do usuário

Gerenciar a autenticação multifator durante o login

Gerenciar a autenticação multifator após o cadastro ou redefinição de senha

Gerenciar a autenticação multifator após a inscrição

Manipular a autenticação multifator após a redefinição de senha

Executar e testar seu aplicativo

Conteúdo relacionado

Comentários

Recursos adicionais