Samouczek: Rejestrowanie metody silnego uwierzytelniania w aplikacji jednostronicowej React przy użyciu natywnego zestawu SDK JavaScript do uwierzytelniania

Dotyczy: Najemcy zewnętrzni (dowiedz się więcej)

W tym samouczku zarejestrujesz silną metodę uwierzytelniania dla użytkownika w aplikacji jednostronicowej React (SPA) przy użyciu natywnego zestawu JavaScript SDK do uwierzytelniania.

Jeśli włączysz uwierzytelnianie wieloskładnikowe (MFA), ale użytkownik nie ma zarejestrowanej metody silnego uwierzytelniania, musisz zarejestrować go przed wystawieniem tokenów.

Przepływ rejestracji metody silnego uwierzytelniania odbywa się w trzech scenariuszach:

• Podczas logowania: użytkownik loguje się, ale nie ma zarejestrowanej metody silnego uwierzytelniania.
• Po zarejestrowaniu: użytkownik pomyślnie zarejestruje się i automatycznie zaloguje się.
• Po samoobsługowym resetowaniu hasła (SSPR) użytkownik pomyślnie resetuje swoje hasło i automatycznie przechodzi do logowania.

Gdy wymagana jest rejestracja metody silnego uwierzytelniania, użytkownik wybiera wybraną metodę z listy obsługiwanych metod. Dostępne metody to jednorazowy kod dostępu przez e-mail i jednorazowy kod dostępu przez SMS.

Na poniższym diagramie przepływu przedstawiono trzy scenariusze:

Wymagania wstępne

• Wykonaj kroki opisane w samouczkach dotyczących rejestracji, logowania i resetowania hasła .
• Visual Studio Code lub inny edytor kodu.
• Node.js 20.x lub nowszym.
• Włącz uwierzytelnianie wieloskładnikowe (MFA) dla aplikacji.

Umożliwienie aplikacji rejestrowania metod silnego uwierzytelniania

Aby włączyć rejestrację metody silnego uwierzytelniania w aplikacji React, zaktualizuj konfigurację aplikacji, dodając wymaganą możliwość.

1. Znajdź plik src/config/auth-config.ts .

2. customAuth Dodaj lub zaktualizuj właściwość capabilities obiektu, aby umieścić wartość registration_required w tablicy, jak pokazano w poniższym fragmencie kodu.

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

Wartość możliwości registration_required informuje Microsoft Entra, że aplikacja może obsługiwać silny przepływ rejestracji metody uwierzytelniania. Dowiedz się więcej o typach i możliwościach uwierzytelniania natywnego.

Tworzenie składników interfejsu użytkownika

Aby zarządzać rejestracją metod silnego uwierzytelniania, potrzebujesz składników formularza. Aby dodać te składniki do aplikacji, wykonaj następujące czynności:

1. Utwórz nowy folder o nazwie src/app/shared/components do przechowywania składników wielokrotnego użytku.
2. W nowym folderze utwórz plik o nazwie AuthMethodRegistrationForm.tsx , aby wyświetlić formularz, który umożliwia użytkownikom wybranie i zarejestrowanie metody silnego uwierzytelniania. Dodaj kod w AuthMethodRegistrationForm do pliku.
3. W nowym folderze utwórz inny plik o nazwie AuthMethodRegistrationChallengeForm.tsx , aby wyświetlić formularz umożliwiający zweryfikowanie metody silnego uwierzytelniania przy użyciu jednorazowego kodu dostępu odbieranego przez użytkownika. Dodaj kod w pliku AuthMethodRegistrationChallengeForm.

W razie potrzeby możesz zaimportować i użyć komponentów wielokrotnego użytku w procesie logowania, logowania po rejestracji oraz logowania po przepływie samoobsługowego resetowania hasła (SSPR).

Rejestrowanie metody silnego uwierzytelniania podczas logowania

Zaktualizuj plik src/app/sign-in/page.tsx , aby umożliwić aplikacji obsługę przepływu rejestracji metody silnego uwierzytelniania podczas logowania. Zobacz pełny kod w pliku page.tsx:

1. Zaimportuj wymagane typy i składniki, jak pokazano w poniższym fragmencie kodu:

   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. Dodaj nowe zmienne stanu na potrzeby rejestracji metody silnego uwierzytelniania:

   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. Zaktualizuj funkcje startSignIn, handlePasswordSubmit i handleCodeSubmit, aby sprawdzić, czy wymagana jest rejestracja silnej metody uwierzytelniania:

   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);
           }
   
           ...
       }
   };
   

   W każdej funkcji zwróć uwagę, że sprawdzamy, czy wymagana jest rejestracja silnej metody uwierzytelniania przy użyciu następującego fragmentu kodu:

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

4. Dodaj obsługę wyboru metody silnego uwierzytelniania:

   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. Dodaj procedurę zarządzania na potrzeby weryfikacji metody silnego uwierzytelniania:

   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. Zaktualizuj funkcję, renderForm() aby wyświetlić poprawne formularze rejestracji metody silnego uwierzytelniania (wybór metody lub weryfikacja):

   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}
               />
           );
       }
   
       ...
   };
   

Rejestrowanie metody silnego uwierzytelniania po zarejestrowaniu się lub zresetowaniu hasła

Przepływ rejestracji metody silnego uwierzytelniania po rejestracji i zresetowaniu hasła działa podobnie jak rejestracja metody podczas logowania. Po pomyślnym zarejestrowaniu się lub zresetowaniu hasła zestaw SDK może automatycznie kontynuować logowanie. Jeśli użytkownik nie ma zarejestrowanej metody silnego uwierzytelniania, przepływ przechodzi do stanów rejestracji metody uwierzytelniania.

Rejestrowanie metody silnego uwierzytelniania po zarejestrowaniu

W przypadku rejestracji metody silnego uwierzytelniania po przepływie rejestracji należy zaktualizować plik /src/app/sign-up/page.tsx . Zobacz pełny kod w pliku page.tsx:

1. Upewnij się, że importujesz wymagane typy i składniki.

2. Zarządzaj stanami rejestracji metod silnego uwierzytelniania w podobny sposób, jak w przepływie logowania. Po pomyślnym zakończeniu rejestracji możesz użyć wyniku, aby automatycznie wyzwolić logowanie, jak pokazano w poniższym fragmencie kodu:

   // 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
   

Rejestrowanie metody silnego uwierzytelniania po zresetowaniu hasła

W celu zarejestrowania metody silnego uwierzytelniania po samoobsługowym resetowaniu hasła należy zaktualizować plik /src/app/reset-password/page.tsx. Zobacz pełny kod w pliku page.tsx:

1. Upewnij się, że importujesz wymagane typy i składniki.

2. Zarządzaj stanami rejestracji metody silnego uwierzytelniania podobnie jak w przepływie logowania. Po pomyślnym zakończeniu samoobsługowego resetowania hasła możesz użyć wyniku, aby automatycznie wyzwolić logowanie, jak pokazano w poniższym fragmencie kodu:

   // 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
   

Uruchamianie i testowanie aplikacji

Wykonaj kroki opisane w temacie Uruchamianie i testowanie aplikacji , aby uruchomić aplikację, ale tym razem przetestuj przepływ rejestracji metody silnego uwierzytelniania.

Testowanie rejestracji metody uwierzytelniania po zarejestrowaniu

1. Przejdź do, http://localhost:3000/sign-up aby wyświetlić formularz rejestracji.

2. Wprowadź wymagane szczegóły, a następnie zarejestruj się, postępując zgodnie z monitami. Po pomyślnym zarejestrowaniu aplikacja automatycznie kontynuuje przepływ logowania, wyświetlając formularz rejestracji metody silnego uwierzytelniania.

3. Wybierz wybraną metodę silnego uwierzytelniania, taką jak E-mail OTP, a następnie wprowadź adres e-mail.

4. Wybierz pozycję Kontynuuj , aby przesłać szczegóły formularza. Otrzymasz kod weryfikacyjny na swój adres e-mail.

5. Wprowadź kod weryfikacyjny w polu tekstowym formularza wyzwania, a następnie wybierz przycisk Kontynuuj . Po zweryfikowaniu kodu metoda silnego uwierzytelniania jest zarejestrowana i logujesz się.

Testowanie rejestracji metody silnego uwierzytelniania podczas logowania

Aby przetestować rejestrację metody silnego uwierzytelniania podczas logowania, upewnij się, że masz konto użytkownika, które nie ma zarejestrowanej metody silnego uwierzytelniania.

1. Przejdź do, http://localhost:3000/sign-in aby wyświetlić formularz logowania.

2. Wprowadź szczegóły, wybierz przycisk Kontynuuj , a następnie postępuj zgodnie z monitami. Aplikacja rozpoczyna przepływ rejestracji metody silnego uwierzytelniania.

3. Postępuj zgodnie z monitami aplikacji, aby ukończyć rejestrację metody silnego uwierzytelniania.

Testowanie rejestracji metody uwierzytelniania po zresetowaniu hasła

Aby przetestować rejestrację metody silnego uwierzytelniania po samoobsługowym resetowaniu hasła, upewnij się, że masz konto użytkownika, które nie ma zarejestrowanej metody silnego uwierzytelniania.

1. Przejdź do strony , http://localhost:3000/reset-password aby wyświetlić formularz resetowania hasła.

2. Wprowadź szczegóły, wybierz przycisk Kontynuuj , a następnie postępuj zgodnie z monitami aplikacji, aby ukończyć przepływ resetowania hasła. Po pomyślnym zresetowaniu hasła aplikacja kontynuuje przepływ logowania, wyświetlając formularz rejestracji metody silnego uwierzytelniania.

3. Postępuj zgodnie z monitami aplikacji, aby ukończyć rejestrację metody silnego uwierzytelniania.

Następny krok

Samouczek: włączanie uwierzytelniania wieloczynnikowego w aplikacji React SPA z użyciem natywnego zestawu SDK JavaScript do uwierzytelniania