Tutorial: Registrar um método de autenticação forte em um aplicativo de página única do React usando o SDK javaScript de autenticação nativa

Aplica-se a: Locatários externos (saiba mais)

Neste tutorial, você registrará um método de autenticação robusta para um usuário em seu SPA (aplicativo de página única) React usando o SDK JavaScript da autenticação nativa.

Se você habilitar a MFA (autenticação multifator), mas o usuário não tiver nenhum método de autenticação forte registrado, será necessário que o usuário registre um antes que os tokens possam ser emitidos.

O fluxo de registro do método de autenticação forte ocorre em três cenários:

• Durante o login: o usuário entra, mas não tem um método de autenticação forte registrado.
• Após a inscrição: o usuário se inscreve com êxito e continua a entrar automaticamente.
• Após a redefinição de senha de autoatendimento (SSPR): o usuário redefine a senha com êxito e continua a entrar automaticamente.

Quando o registro de método de autenticação forte é necessário, o usuário seleciona um método de escolha em uma lista de métodos com suporte. Os métodos disponíveis são email e senha única de SMS .

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

Pré-requisitos

• Conclua as etapas nos tutoriais de inscrição, entrada e redefinição de senha .
• Visual Studio Code ou outro editor de código.
• Node.js 20.x ou posterior.
• Habilite a MFA (autenticação multifator) para seu aplicativo.

Habilitar o aplicativo para lidar com o registro de método de autenticação forte

Para habilitar o registro de método de autenticação forte em seu aplicativo React, atualize a configuração do aplicativo adicionando a funcionalidade necessária.

1. Localize o arquivo src/config/auth-config.ts .

2. customAuth No objeto, adicione ou atualize a capabilities propriedade para incluir o registration_required valor na matriz, conforme mostrado no seguinte snippet de código:

   const customAuthConfig: CustomAuthConfiguration = {
       customAuth: {
           ...
           capabilities: ["registration_required"],
           ...
       },
       ...
   };
   

O valor da funcionalidade registration_required informa Microsoft Entra que seu aplicativo pode lidar com um fluxo de registro de método de autenticação forte. 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 para lidar com o registro de método de autenticação forte. Use as seguintes etapas para adicionar esses componentes ao seu aplicativo:

1. Crie uma nova pasta chamada src/app/shared/components para armazenar componentes reutilizáveis.
2. Na nova pasta, crie um arquivo nomeado AuthMethodRegistrationForm.tsx para exibir um formulário que permita que os usuários selecionem e registrem um método de autenticação forte. Adicione o código em AuthMethodRegistrationForm no arquivo.
3. Na nova pasta, crie outro arquivo nomeado AuthMethodRegistrationChallengeForm.tsx para exibir um formulário para verificar o método de autenticação forte usando a senha única que o usuário recebe. Adicione o código em AuthMethodRegistrationChallengeForm 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.

Registrar método de autenticação forte durante a entrada

Atualize o arquivo src/app/sign-in/page.tsx para permitir que seu aplicativo manipule o fluxo de registro do método de autenticação forte durante o login. Consulte o código completo em page.tsx:

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

   import {
       CustomAuthPublicClientApplication,
       ICustomAuthPublicClientApplication,
       SignInCodeRequiredState,
       SignInCompletedState,
       AuthFlowStateBase,
       SignInAuthMethodRegistrationRequiredState,
       SignInAuthMethodRegistrationChallengeRequiredState,
   } from "@azure/msal-browser/custom-auth";
   import { AuthMethodRegistrationForm } from "../components/shared/AuthMethodRegistrationForm";
   import { AuthMethodRegistrationChallengeForm } from "../components/shared/AuthMethodRegistrationChallengeForm";
   ...
   

2. Adicione novas variáveis de estado para o registro de método de autenticação forte:

   export default function SignIn() {
       ...
       // Authentication method registration states
       const [authMethodsForRegistration, setAuthMethodsForRegistration] = useState<AuthenticationMethod[]>([]);
       const [selectedAuthMethodForRegistration, setSelectedAuthMethodForRegistration] = useState<AuthenticationMethod | undefined>(undefined);
       const [verificationContactForRegistration, setVerificationContactForRegistration] = useState("");
       const [challengeForRegistration, setChallengeForRegistration] = useState("");
   
       // ... initialization code
   }
   

3. Atualize as funções startSignIn, handlePasswordSubmit e handleCodeSubmit para verificar se o registro de método de autenticação forte é necessário:

   const startSignIn = async (e: React.FormEvent) => {
       // Start the sign-in flow
       const result = await authClient.signIn({
           username,
       });
   
       ...
   
       // Check for auth method registration requirement
       if (result.isAuthMethodRegistrationRequired()) {
           setAuthMethodsForRegistration(result.state.getAuthMethods());
           // Set default selection to the first auth method
           const methods = result.state.getAuthMethods();
           setSelectedAuthMethodForRegistration(methods.length > 0 ? methods[0] : undefined);
       }
   
       ...
   };
   
   const handlePasswordSubmit = async (e: React.FormEvent) => {
       if (signInState instanceof SignInPasswordRequiredState) {
           const result = await signInState.submitPassword(password);
   
           ...
   
           // Check for auth method registration requirement
           if (result.isAuthMethodRegistrationRequired()) {
               const methods = result.state.getAuthMethods();
               setAuthMethodsForRegistration(methods);
               setSelectedAuthMethodForRegistration(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 auth method registration requirement
           if (result.isAuthMethodRegistrationRequired()) {
               const methods = result.state.getAuthMethods();
               setAuthMethodsForRegistration(methods);
               setSelectedAuthMethodForRegistration(methods.length > 0 ? methods[0] : undefined);
               setSignInState(result.state);
           }
   
           ...
       }
   };
   

   Em cada uma das funções, observe que verificamos se o registro de método de autenticação forte é necessário usando o seguinte snippet de código:

   if (result.isAuthMethodRegistrationRequired()) {...}
   

4. Adicione o manipulador para seleção de método de autenticação forte:

   const handleAuthMethodRegistrationSubmit = async (e: React.FormEvent) => {
       e.preventDefault();
       setError("");
       setLoading(true);
   
       if (!selectedAuthMethodForRegistration || !verificationContactForRegistration) {
           setError("Please select an authentication method and enter a verification contact.");
           setLoading(false);
           return;
       }
   
       if (signInState instanceof AuthMethodRegistrationRequiredState) {
           const result = await signInState.challengeAuthMethod({
               authMethodType: selectedAuthMethodForRegistration,
               verificationContact: verificationContactForRegistration,
           });
   
           if (result.isFailed()) {
               if (result.error?.isInvalidInput()) {
                   setError("Incorrect verification contact.");
               } else if (result.error?.isVerificationContactBlocked()) {
                   setError(
                       "The verification contact is blocked. Consider using a different contact or a different authentication method"
                   );
               } else {
                   setError(
                       result.error?.errorData?.errorDescription ||
                           "An error occurred while verifying the authentication method"
                   );
               }
           }
   
           if (result.isCompleted()) {
               setData(result.data);
               setCurrentSignInStatus(true);
               setSignInState(result.state);
           }
   
           if (result.isVerificationRequired()) {
               setSignInState(result.state);
           }
       }
   
       setLoading(false);
   };
   

5. Adicione o manipulador para verificação de método de autenticação forte:

   const handleAuthMethodRegistrationChallengeSubmit = async (e: React.FormEvent) => {
       e.preventDefault();
       setError("");
       setLoading(true);
   
       if (!challengeForRegistration) {
           setError("Please enter a code.");
           setLoading(false);
           return;
       }
   
       if (signInState instanceof AuthMethodVerificationRequiredState) {
           const result = await signInState.submitChallenge(challengeForRegistration);
   
           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);
   };
   

6. Atualize a função renderForm() para exibir os formulários corretos de registro do método de autenticação forte (seleção ou verificação de método):

   const renderForm = () => {
       if (loadingAccountStatus) {
           return;
       }
   
       ...
   
       // Display AuthMethodRegistrationForm if the current state is authentication method registration required state
       if (signInState instanceof AuthMethodRegistrationRequiredState) {
           return (
               <AuthMethodRegistrationForm
                   onSubmit={handleAuthMethodRegistrationSubmit}
                   authMethods={authMethodsForRegistration}
                   selectedAuthMethod={selectedAuthMethodForRegistration}
                   setSelectedAuthMethod={setSelectedAuthMethodForRegistration}
                   verificationContact={verificationContactForRegistration}
                   setVerificationContact={setVerificationContactForRegistration}
                   loading={loading}
                   styles={styles}
               />
           );
       }
   
       // Display AuthMethodRegistrationChallengeForm if the current state is authentication method verification required state
       if (signInState instanceof AuthMethodVerificationRequiredState) {
           return (
               <AuthMethodRegistrationChallengeForm
                   onSubmit={handleAuthMethodRegistrationChallengeSubmit}
                   challenge={challengeForRegistration}
                   setChallenge={setChallengeForRegistration}
                   loading={loading}
                   styles={styles}
               />
           );
       }
   
       ...
   };
   

Registrar método de autenticação forte após a inscrição ou redefinição de senha

O fluxo de cadastro do método de autenticação forte após a inscrição e a redefinição de senha funciona de forma semelhante ao cadastro do método durante o fluxo de login. Após uma inscrição bem-sucedida ou redefinição de senha, o SDK pode continuar automaticamente com o login. Se o usuário não tiver um método de autenticação forte registrado, o fluxo fará a transição para os estados de registro do método de autenticação.

Registrar método de autenticação forte após a inscrição

Para registrar um método de autenticação forte após o processo de inscrição, você precisa atualizar o arquivo /src/app/sign-up/page.tsx. Consulte o código completo em page.tsx:

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

2. Manipule os estados de registro do método de autenticação forte da mesma maneira que ocorre no fluxo de login. Depois que a inscrição for concluída com êxito, você poderá usar o resultado para disparar automaticamente um login, conforme demonstrado no snippet de código a seguir.

   // In your sign-up completion handler
   if (signUpState instanceof SignUpCompletedState) {
       // Continue with sign-in using the continuation token
       const result = await signUpState.signIn();
   
       ...
   
       // Check for auth method registration requirement
       if (result.isAuthMethodRegistrationRequired()) {
           setAuthMethodsForRegistration(result.state.getAuthMethods());
           const methods = result.state.getAuthMethods();
           setSelectedAuthMethodForRegistration(methods.length > 0 ? methods[0] : undefined);
           setSignUpState(result.state);
       }
   
       ...
   }
   
   // Then use the same renderForm logic to display AuthMethodRegistrationForm
   // and AuthMethodRegistrationChallengeForm components
   

Registrar método de autenticação forte após a redefinição de senha

Para um registro de método forte de autenticação após o SSPR, você precisa atualizar o arquivo /src/app/reset-password/page.tsx. Consulte o código completo em page.tsx:

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

2. Manipule os estados de registro do método de autenticação forte de maneira semelhante à do fluxo de entrada. 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();
   
       ...
   
       // Check for auth method registration requirement
       if (result.isAuthMethodRegistrationRequired()) {
           setAuthMethodsForRegistration(result.state.getAuthMethods());
           const methods = result.state.getAuthMethods();
           setSelectedAuthMethodForRegistration(methods.length > 0 ? methods[0] : undefined);
           setSignUpState(result.state);
       }
   
       ...
   }
   
   // Then use the same renderForm logic to display AuthMethodRegistrationForm
   // and AuthMethodRegistrationChallengeForm components
   

Executar e testar seu aplicativo

Use as etapas em Executar e testar seu aplicativo para executar seu aplicativo, mas desta vez, teste o fluxo de registro do método de autenticação forte.

Testar o registro do método de autenticação após a inscrição

1. Navegue até http://localhost:3000/sign-up para exibir o formulário de inscrição.

2. Insira os detalhes necessários e inscreva-se seguindo os prompts. Depois que você se inscrever com êxito, o aplicativo continua automaticamente no fluxo de login exibindo o formulário de registro do método de autenticação forte.

3. Selecione o método de autenticação forte de sua escolha, como Emails OTP, e insira um endereço de email.

4. Selecione Continuar para enviar os detalhes do formulário. Você deve receber um código de verificação em seu endereço de email.

5. Insira o código de verificação na caixa de texto do formulário de desafio e selecione o botão Continuar . Depois que o código é verificado, seu método de autenticação forte é registrado e você está conectado.

Testar o registro do método de autenticação forte durante o login

Para testar o registro de método de autenticação forte durante a entrada, verifique se você tem uma conta de usuário que não tem um método de autenticação forte registrado.

1. Navegue até http://localhost:3000/sign-in para exibir o formulário de entrada.

2. Insira seus detalhes, selecione o botão Continuar e, em seguida, siga os prompts. O aplicativo insere um fluxo de registro de método de autenticação forte.

3. Siga os prompts do aplicativo para concluir o registro de método de autenticação forte.

Testar o registro do método de autenticação após a redefinição de senha

Para testar o registro de método de autenticação forte após a SSPR, verifique se você tem uma conta de usuário que não tem um método de autenticação forte registrado.

1. Navegue até http://localhost:3000/reset-password para exibir o formulário de redefinição de senha.

2. Insira seus detalhes, selecione o botão Continuar e, em seguida, siga os prompts do aplicativo para concluir o fluxo de redefinição de senha. Depois que você redefinir sua senha com êxito, o aplicativo continua o fluxo de entrada exibindo o formulário de registro do método de autenticação robusta.

3. Siga os prompts do aplicativo para concluir o registro de método de autenticação forte.

Próxima etapa

Tutorial: Habilitar a autenticação multifator em um REACT SPA usando o SDK javaScript de autenticação nativa