Esercitazione: Registrare un metodo di autenticazione avanzata in un'app a pagina singola React usando JavaScript SDK per l'autenticazione nativa

Si applica a: Cerchio verde con un segno di spunta bianco che indica che il contenuto seguente si applica ai tenant esterni. Tenant esterni (maggiori informazioni)

In questa esercitazione registri un metodo di autenticazione forte per un utente nella Single-Page Application (SPA) React utilizzando l'SDK JavaScript di autenticazione nativa.

Se si abilita l'autenticazione a più fattori (MFA), ma l'utente non ha un metodo di autenticazione avanzata registrato, è necessario registrare uno prima che i token possano essere rilasciati.

Il flusso di registrazione del metodo di autenticazione avanzata si verifica in tre scenari:

  • Durante l'accesso: l'utente accede ma non ha un metodo di autenticazione avanzata registrato.
  • Dopo l'iscrizione: l'utente si iscrive e procede automaticamente per l'accesso.
  • Dopo la reimpostazione della password self-service( SSPR): l'utente reimposta correttamente la password e procede automaticamente per l'accesso.

Quando è necessaria la registrazione avanzata del metodo di autenticazione, l'utente seleziona un metodo di scelta da un elenco di metodi supportati. I metodi disponibili sono il passcode monouso tramite posta elettronica e SMS .

Il diagramma di flusso seguente illustra i tre scenari:

Registrare un metodo di autenticazione avanzata.

Prerequisiti

Abilitare l'app per gestire la registrazione del metodo di autenticazione avanzata

Per abilitare la registrazione avanzata del metodo di autenticazione nell'app React, aggiornare la configurazione dell'app aggiungendo la funzionalità necessaria.

  1. Individuare il file src/config/auth-config.ts .

  2. Nell'oggetto customAuth aggiungere o aggiornare la capabilities proprietà in modo da includere il registration_required valore nella matrice, come illustrato nel frammento di codice seguente:

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

Il valore della funzionalità registration_required informa Microsoft Entra che l'app può gestire il flusso di registrazione del metodo di autenticazione avanzata. Altre informazioni sui tipi e sulle funzionalità di verifica dell'autenticazione nativa.

Creare componenti dell'interfaccia utente

È necessario che i componenti del modulo gestiscano la registrazione del metodo di autenticazione forte. Usare la procedura seguente per aggiungere questi componenti all'app:

  1. Creare una nuova cartella denominata src/app/shared/components per archiviare i componenti riutilizzabili.
  2. Nella nuova cartella creare un file denominato AuthMethodRegistrationForm.tsx per visualizzare un modulo che consente agli utenti di selezionare e registrare un metodo di autenticazione avanzata. Aggiungere il codice in AuthMethodRegistrationForm nel file.
  3. Nella nuova cartella creare un altro file denominato AuthMethodRegistrationChallengeForm.tsx per visualizzare un modulo per verificare il metodo di autenticazione avanzata usando il passcode monouso ricevuto dall'utente. Aggiungere il codice in AuthMethodRegistrationChallengeForm nel file.

Quando necessario, è possibile importare e usare componenti riutilizzabili nell'accesso, accesso dopo l'iscrizione e accesso dopo i flussi di autoriempostazione della password.

Registrare un metodo di autenticazione avanzata durante l'accesso

Aggiornare il file src/app/sign-in/page.tsx per consentire all'app di gestire il flusso di registrazione del metodo di autenticazione avanzata durante l'accesso. Vedere il codice completo in page.tsx:

  1. Importare i tipi e i componenti necessari, come illustrato nel frammento di codice seguente:

    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. Aggiungere nuove variabili di stato per la registrazione del metodo di autenticazione avanzata:

    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. Aggiornare le funzioni startSignIn, handlePasswordSubmit e handleCodeSubmit per verificare se è necessaria la registrazione del metodo di autenticazione forte.

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

        ...
    }
};

    In ognuna delle funzioni si noti che si verifica se è necessaria la registrazione avanzata del metodo di autenticazione usando il frammento di codice seguente:

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

  4. Aggiungere il gestore per la selezione del metodo di autenticazione avanzata:

    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. Aggiungere il gestore per la verifica del metodo di autenticazione avanzata:

    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. Aggiornare la renderForm() funzione per visualizzare i moduli corretti di registrazione del metodo di autenticazione avanzata (selezione o verifica del metodo):

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

    ...
};

Registrare un metodo di autenticazione avanzata dopo l'iscrizione o la reimpostazione della password

Il flusso di registrazione del metodo di autenticazione avanzata dopo l'iscrizione e la reimpostazione della password funzionano in modo simile alla registrazione del metodo durante il flusso di accesso. Dopo aver completato l'iscrizione o la reimpostazione della password, l'SDK può continuare automaticamente con l'accesso. Se l'utente non dispone di un metodo di autenticazione avanzata registrato, il flusso passa agli stati di registrazione del metodo di autenticazione.

Registrare un metodo di autenticazione avanzata dopo l'iscrizione

Per la registrazione avanzata del metodo di autenticazione dopo il flusso di iscrizione, è necessario aggiornare il file /src/app/sign-up/page.tsx . Vedere il codice completo in page.tsx:

  1. Assicurarsi di importare i tipi e i componenti necessari.

  2. Gestire gli stati di registrazione del metodo di autenticazione avanzata in modo analogo a quanto avviene nel flusso di accesso. Al termine dell'iscrizione, è possibile usare il risultato per attivare automaticamente un accesso, come illustrato nel frammento di codice seguente:

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

Registrare un metodo di autenticazione avanzata dopo la reimpostazione della password

Per la registrazione di un metodo di autenticazione sicuro dopo la reimpostazione della password self-service (SSPR), è necessario aggiornare il file /src/app/reset-password/page.tsx. Vedere il codice completo in page.tsx:

  1. Assicurarsi di importare i tipi e i componenti necessari.

  2. Gestire gli stati di registrazione del metodo di autenticazione avanzata in modo analogo al flusso di accesso. Al termine del completamento di SSPRS, è possibile utilizzare il risultato per attivare automaticamente un'autenticazione, come illustrato nel frammento di codice seguente:

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

Eseguire e testare l'app

Usa la procedura descritta in Eseguire e testare l'app per eseguire l'app, ma questa volta testa il flusso di registrazione del metodo di autenticazione forte.

Testare la registrazione del metodo di autenticazione dopo l'iscrizione

  1. Passare a http://localhost:3000/sign-up per visualizzare il modulo di iscrizione.

  2. Immettere i dettagli necessari, quindi iscriversi seguendo le istruzioni. Dopo che ti sei iscritto con successo, l'app continua automaticamente al flusso di accesso visualizzando il modulo di registrazione del metodo di autenticazione forte.

  3. Selezionare il metodo di autenticazione avanzata scelto, ad esempio Email OTP, quindi immettere un indirizzo di posta elettronica.

  4. Selezionare Continua per inviare i dettagli del modulo. Si dovrebbe ricevere un codice di verifica all'indirizzo di posta elettronica.

  5. Immettere il codice di verifica nella casella di testo Modulo di verifica e quindi fare clic sul pulsante Continua . Dopo aver verificato il codice, il metodo di autenticazione avanzata viene registrato e si è connessi.

Testare la registrazione del metodo di autenticazione avanzata durante l'accesso

Per testare la registrazione del metodo di autenticazione avanzata durante l'accesso, assicurarsi di avere un account utente che non dispone di un metodo di autenticazione sicuro registrato.

  1. Passare a http://localhost:3000/sign-in per visualizzare il modulo di accesso.

  2. Immettere i dettagli, selezionare il pulsante Continua , quindi seguire le istruzioni. L'app entra nel flusso di registrazione del metodo di autenticazione avanzata.

  3. Seguire le istruzioni dell'app per completare la registrazione del metodo di autenticazione avanzata.

Testare la registrazione del metodo di autenticazione dopo la reimpostazione della password

Per testare la registrazione del metodo di autenticazione forte dopo SSPR, assicurarsi di avere un account utente che non abbia un metodo di autenticazione forte registrato.

  1. Passare a http://localhost:3000/reset-password per visualizzare il modulo di reimpostazione della password.

  2. Immettere i dettagli, selezionare il pulsante Continua , quindi seguire le istruzioni dell'app per completare il flusso di reimpostazione della password. Dopo aver reimpostato correttamente la password, l'app continua a eseguire l'accesso visualizzando il modulo di registrazione del metodo di autenticazione avanzata.

  3. Seguire le istruzioni dell'app per completare la registrazione del metodo di autenticazione avanzata.

Passo successivo

Esercitazione: Abilitare l'autenticazione a più fattori in un'applicazione a pagina singola React usando JavaScript SDK per l'autenticazione nativa

  • Ultimo aggiornamento: