Lernprogramm: Aktivieren der mehrstufigen Authentifizierung in einer React-Einzelseiten-App mithilfe des nativen Authentifizierungs-JavaScript SDK

Gilt für: Grüner Kreis mit einem weißen Häkchensymbol, das angibt, dass der folgende Inhalt für externe Mandanten gilt. Externe Mandanten (weitere Informationen)

In diesem Lernprogramm erfahren Sie, wie Sie ihrer einzelseitigen React-Anwendung (Single Page Application, SPA) mithilfe des JavaScript-SDKs der nativen Authentifizierung mehrstufige Authentifizierung (Multifactor Authentication, MFA) hinzufügen.

Genau wie bei der Registrierung starker Authentifizierungsmethoden erfolgt der MFA-Fluss in drei Szenarien:

  • Bei der Anmeldung: Der Benutzer meldet sich an und hat eine starke Authentifizierungsmethode registriert.
  • Nach der Registrierung: Nachdem der Benutzer die Registrierung abgeschlossen hat, fahren sie mit der Anmeldung fort. Neue Benutzer müssen eine starke Authentifizierungsmethode einrichten, bevor eine MFA-Herausforderung erfolgt. Da die starke Authentifizierungsmethode auch während der Registrierung überprüft wird, werden sie möglicherweise nicht zur Eingabe einer zusätzlichen MFA-Abfrage aufgefordert.
  • Nach der Self-Service-Kennwortzurücksetzung (SSPR): Der Benutzer setzt sein Kennwort erfolgreich zurück und fährt automatisch mit der Anmeldung fort. Wenn der Benutzer eine starke Authentifizierungsmethode registriert hat, wird er aufgefordert, die MFA-Abfrage abzuschließen.

Wenn MFA erforderlich ist, wählt der Benutzer eine MFA-Abfragemethode aus einer Liste der registrierten Methoden aus. Verfügbare Optionen sind E-Mail-Einmalkennung , SMS-Einmalkennung oder beides, je nachdem, was der Benutzer zuvor registriert hat.

Das folgende Flussdiagramm veranschaulicht die drei Szenarien:

Abschließen einer mehrstufigen Authentifizierungsabfrage.

Voraussetzungen

Aktivieren der App für die Behandlung der mehrstufigen Authentifizierung

Um MFA in Ihrer React-App zu aktivieren, aktualisieren Sie die App-Konfiguration, indem Sie die erforderliche Funktion hinzufügen:

  1. Suchen Sie die Datei "src/config/auth-config.ts ".

  2. Im customAuth-Objekt die capabilities-Eigenschaft hinzufügen oder aktualisieren, um den mfa_required-Wert im Array einzuschließen, wie im folgenden Codeausschnitt gezeigt wird.

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

Der Funktionswert mfa_required informiert Microsoft Entra, dass Ihre App einen MFA-Fluss verarbeiten kann. Erfahren Sie mehr über systemeigene Authentifizierungsabfragetypen und -funktionen.

Erstellen von UI-Komponenten

Sie benötigen Formularkomponenten in Ihrer App, um den MFA-Fluss zu unterstützen. Führen Sie die folgenden Schritte aus, um Ihrer App diese Komponenten hinzuzufügen:

  1. Erstellen Sie einen neuen Ordner, src/app/shared/components für wiederverwendbare Komponenten (sofern er noch nicht vorhanden ist).
  2. Erstellen Sie im neuen Ordner eine Datei namens "MfaAuthMethodSelectionForm.tsx ", um ein Formular anzuzeigen, mit dem Benutzer eine registrierte sichere Authentifizierungsmethode auswählen können. Fügen Sie den Code in MfaAuthMethodSelectionForm der Datei hinzu.
  3. Erstellen Sie im neuen Ordner eine weitere Datei mit dem Namen "MfaChallengeForm.tsx ", um ein Formular zum Überprüfen der sicheren Authentifizierungsmethode mithilfe der einmaligen Kennung anzuzeigen, die der Benutzer empfängt. Fügen Sie den Code in MfaChallengeForm in die Datei ein.

Bei Bedarf können Sie wiederverwendbare Komponenten in Ihre Anmeldung, Anmeldung nach der Registrierung und anmeldung nach SSPR-Flüssen importieren und verwenden.

Verwalten der mehrstufigen Authentifizierung während der Anmeldung

Aktualisieren Sie die Datei "src/app/sign-in/page.tsx ", damit Ihre App den MFA-Fluss während der Anmeldung verarbeiten kann. Den vollständigen Code finden Sie in page.tsx:

  1. Importieren Sie die erforderlichen Typen und Komponenten, wie im folgenden Codeausschnitt gezeigt:

    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";

  2. Hinzufügen neuer Statusvariablen für 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
}

  3. Aktualisieren Sie die startSignIn, handlePasswordSubmit und handleCodeSubmit Funktionen, um zu überprüfen, ob MFA erforderlich ist.

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

        ...
    }
};

    Beachten Sie in jeder Funktion, dass wir überprüfen, ob MFA mithilfe des folgenden Codeausschnitts erforderlich ist:

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

  4. Fügen Sie den Handler für die Auswahl von MFA-Herausforderungen hinzu:

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

  5. Fügen Sie den Handler für die Überprüfung der MFA-Herausforderung hinzu:

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

  6. Aktualisieren Sie die renderForm()-Funktion, um die korrekten MFA-Herausforderungsformulare anzuzeigen (Auswahl der MFA-Herausstellungsmethode oder Überprüfung der MFA-Herausstellungsmethode).

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

    ...
};

Bearbeiten der mehrstufigen Authentifizierung nach Registrierung oder Zurücksetzung des Kennworts

Der MFA-Fluss nach der Registrierung und der Kennwortzurücksetzung funktioniert ähnlich wie der MFA-Fluss im Anmeldeablauf. Nach einer erfolgreichen Registrierung oder Kennwortzurücksetzung kann das SDK automatisch mit dem Anmeldeablauf fortfahren. Wenn der Benutzer eine starke Authentifizierungsmethode registriert hat, wechselt der Fluss zur Überprüfung der MFA-Abfrage.

Verwaltung der mehrstufigen Authentifizierung nach der Registrierung

Für den MFA-Fluss nach der Registrierung müssen Sie die Datei "/src/app/sign-up/page.tsx " aktualisieren. Den vollständigen Code finden Sie in page.tsx:

  1. Stellen Sie sicher, dass Sie die erforderlichen Typen und Komponenten importieren.

  2. Verarbeiten Sie MFA-Anforderungsstatus in ähnlicher Weise wie im Anmeldefluss; nachdem die Registrierung erfolgreich abgeschlossen wurde, verwenden Sie das Ergebnis, um den Anmeldefluss automatisch auszulösen, wie dies im folgenden Codeausschnitt gezeigt wird.

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

Verwaltung der Mehrfaktor-Authentifizierung nach der Kennwortzurücksetzung

Für den MFA-Fluss nach SSPR müssen Sie die Datei "/src/app/reset-password/page.tsx " aktualisieren. Den vollständigen Code finden Sie in page.tsx:

  1. Stellen Sie sicher, dass Sie die erforderlichen Typen und Komponenten importieren.

  2. Behandeln Sie MFA-Anforderungsstatus auf ähnliche Weise wie im Anmeldevorgang. Nachdem SSPRS erfolgreich abgeschlossen wurde, können Sie das Ergebnis verwenden, um eine Anmeldung automatisch auszulösen, wie im folgenden Codeausschnitt gezeigt:

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

Ausführen und Testen der App

Bevor Sie Ihre App testen, stellen Sie sicher, dass Sie über ein Benutzerkonto verfügen, das über eine registrierte sichere Authentifizierungsmethode verfügt. Verwenden Sie die Schritte in "App ausführen und testen", um Ihre App auszuführen, aber testen Sie diesmal den MFA-Ablauf.

Verwandte Inhalte

  • Last updated on