Uso di Web browser (MSAL.NET)

È consigliabile usare broker per eseguire l'autenticazione perché offrono più vantaggi rispetto ai browser. Nei computer Windows il broker è Web Account Manager (WAM), in Android e iOS - Microsoft Authenticator o Intune Portale aziendale. L'autenticazione interattiva richiede l'uso di un broker o di un Web browser. MSAL.NET supporta un Web browser di sistema o una visualizzazione Web incorporata.

Browser Web in MSAL.NET

L'interazione avviene in un Web browser

È importante comprendere che quando si acquisisce un token in modo interattivo, il contenuto della finestra di dialogo non viene fornito dalla raccolta, ma da Microsoft Entra ID. L'endpoint di autenticazione restituisce HTML e JavaScript che controllano l'interazione e che vengono sottoposti a rendering in un browser Web o in un controllo web. Consentire al Microsoft Entra ID di gestire l'interazione HTML presenta molti vantaggi:

• La password, se è stata digitata, non viene mai archiviata dall'applicazione, né dalla libreria di autenticazione.
• Consente il reindirizzamento ad altri provider di identità (ad esempio, l'accesso con un account aziendale o dell'istituto di istruzione o un account personale con MSAL o con un account di social networking con Azure AD B2C).
• Consente al Microsoft Entra ID di controllare l'accesso condizionale, ad esempio, facendo in modo che l'utente esegua l'autenticazione a più fattori (MFA) durante la fase di autenticazione (ad esempio immettendo un PIN Windows Hello oppure chiamando sul telefono o su un'app di autenticazione sul telefono). Nei casi in cui l'autenticazione a più fattori richiesta non è stata ancora configurata, l'utente può configurarla al momento opportuno nella stessa finestra di dialogo. L'utente inserisce il numero di telefono cellulare e viene guidato nell'installazione di un'applicazione di autenticazione e nella scansione di un codice QR per aggiungere il proprio account. Questa interazione basata su server è un'esperienza ottimale.
• Consente all'utente di modificare la password in questa stessa finestra di dialogo quando la password è scaduta (specificando campi aggiuntivi per la vecchia password e la nuova password).
• Consente la personalizzazione del marchio del tenant o dell'applicazione (immagini), gestita dall'amministratore del tenant Microsoft Entra o dal proprietario di un'applicazione.
• Consente agli utenti di prestare il consenso affinché, subito dopo l'autenticazione, l'applicazione possa accedere a risorse e autorizzazioni a proprio nome.

Visualizzazione Web incorporata e browser di sistema

MSAL.NET è una libreria multi-framework e dispone di codice specifico del framework per ospitare un browser in un controllo dell'interfaccia utente,ad esempio in .NET WinForms o WebView2; in .NET MAUI, controlli per dispositivi mobili nativi e così via. Questo controllo è denominato visualizzazione Web incorporata . In alternativa, MSAL.NET è anche in grado di aprire un Web browser di sistema.

In genere, è consigliabile usare l'impostazione predefinita della piattaforma e questo è in genere il browser di sistema. Il browser di sistema ricorda meglio gli utenti che hanno già effettuato l'accesso. Per modificare questo comportamento, usare WithUseEmbeddedWebView(Boolean)

Disponibilità del browser

† Il browser di sistema richiede http://localhost l'URI di reindirizzamento.

†† Per utilizzare il browser incorporato, è necessaria la versione net6.0-windows o superiore.

††† Aggiungere un riferimento a Microsoft.Identity.Client.Desktop e chiamare WithWindowsDesktopFeatures per utilizzare il browser incorporato.

Browser web di sistema

L'uso del browser di sistema ha il vantaggio significativo di condividere lo stato Single Sign-On (SSO) con applicazioni Web e altre applicazioni senza bisogno di un broker (WAM, Portale aziendale, Authenticator e così via).

Per le applicazioni desktop, tuttavia, l'avvio di un browser di sistema porta a un'esperienza utente secondaria, poiché l'utente vede il browser, dove potrebbero già essere aperte altre schede. E quando si è verificata l'autenticazione, gli utenti ricevono una pagina in cui viene chiesto di chiudere questa finestra. Se l'utente non presta attenzione, può chiudere l'intero processo (incluse altre schede, che non sono correlate all'autenticazione). L'utilizzo del browser di sistema in ambiente desktop richiederebbe anche l'apertura di porte locali e di mettersi in ascolto su di esse, il che potrebbe richiedere autorizzazioni avanzate per l'applicazione. Tu, in qualità di sviluppatore, utente o amministratore, potresti essere restio di fronte a questo requisito.

Come usare il browser di sistema predefinito

In .NET, MSAL avvierà il browser di sistema come processo separato. MSAL.NET non controlla questo browser, ma una volta che l'utente ha completato l'autenticazione, la pagina Web viene reindirizzata in modo tale che MSAL.NET possa intercettare la chiamata all'URI di reindirizzamento specificato durante la creazione di un'istanza di client pubblico.

MSAL.NET non è possibile rilevare se l'utente si sposta o chiude semplicemente il browser. Le app che usano questa tecnica sono incoraggiate a definire un timeout usando un oggetto CancellationToken. È consigliabile usare un timeout di almeno alcuni minuti per tenere conto dei casi in cui all'utente viene richiesto di modificare la password o di eseguire l'autenticazione a più fattori.

MSAL.NET deve mettersi in ascolto su http://localhost:port per intercettare il codice che Microsoft Entra ID restituisce quando l'utente completa l'autenticazione. Per informazioni dettagliate, vedere Flusso del codice di autorizzazione .

Per abilitare il browser di sistema:

1. Durante la registrazione dell'app nel portale, configurare http://localhost come URI di reindirizzamento (attualmente non supportato da Azure B2C).
2. Quando si costruisce l'app client pubblica, specificare questo URI di reindirizzamento.
3. Aggiungere .WithUseEmbeddedWebView(false).

var pca = PublicClientApplicationBuilder
            .Create("<CLIENT_ID>")
            // or use a known port if you wish "http://localhost:1234"
            .WithRedirectUri("http://localhost")
            .Build();

var result = await pca.AcquireTokenInteractive(s_scopes)
                    .WithUseEmbeddedWebView(false)
                    .ExecuteAsync();

Quando si configura http://localhost, MSAL.NET troverà una porta aperta casuale e la userà. L'uso http://localhost di come URI di reindirizzamento è sicuro. Un altro processo non può essere in ascolto su un socket locale che è già in ascolto da MSAL. Nessuna comunicazione di rete si verifica quando il browser reindirizza a questo URI. Anche se in qualche modo un'app dannosa intercetta il codice di autenticazione (nessun attacco noto, ma è possibile che un'app dannosa abbia accesso amministratore al computer), non può scambiarla per un token perché necessita di un segreto temporaneo noto solo dall'app, come descritto dal protocollo PKCE . L'app non è in grado di restare in ascolto sull'endpoint localhost HTTPS (https://localhost) perché la porta 443 è riservata e MSAL non è in grado di restare in ascolto su di esso.

Limitations

Azure B2C e ADFS 2019 non supportano ancora l'opzione qualsiasi porta. Non è quindi possibile impostare http://localhost (nessuna porta) URI di reindirizzamento, ma solo http://localhost:1234 (con porta). Ciò significa che sarà necessario eseguire la propria gestione delle porte, ad esempio, è possibile riservare alcune porte e configurarle come URI di reindirizzamento. Quindi l'app può provare in sequenza queste porte finché non ne trova una libera, che può poi essere usata da MSAL.

Per altri dettagli, vedere Eccezioni localhost.

Linux e macOS

In Linux MSAL.NET apre il browser di sistema predefinito con uno strumento come xdg-open. L'apertura del browser con sudo non è supportata da MSAL e causerà la generazione di un'eccezione da MSAL.

In macOS il browser viene aperto richiamando open <url>.

Personalizzazione dell'esperienza

MSAL.NET può rispondere con un messaggio HTTP o un reindirizzamento HTTP quando viene ricevuto un token o si verifica un errore.

var options = new SystemWebViewOptions()
{
    HtmlMessageError = "<p> An error occurred: {0}. Details {1}</p>",
    BrowserRedirectSuccess = new Uri("https://www.microsoft.com");
}

await pca.AcquireTokenInteractive(s_scopes)
         .WithUseEmbeddedWebView(false)
         .WithSystemWebViewOptions(options)
         .ExecuteAsync();

Apertura di un browser specifico

È possibile personalizzare il modo in cui MSAL.NET apre il browser. Ad esempio, invece di usare il browser predefinito, è possibile forzare l'apertura di un browser specifico:

var options = new SystemWebViewOptions()
{
    OpenBrowserAsync = SystemWebViewOptions.OpenWithEdgeBrowserAsync
}

Visualizzazioni Web nelle applicazioni per dispositivi mobili

Le visualizzazioni Web incorporate possono essere abilitate nelle applicazioni .NET MAUI. È possibile scegliere di usare visualizzazioni Web incorporate o browser di sistema. La scelta dipende dall'esperienza utente e dagli aspetti di sicurezza che si desidera affrontare.

Differenze tra la visualizzazione Web incorporata e il browser di sistema

Esistono alcune differenze visive tra la visualizzazione Web incorporata e il browser di sistema in MSAL.NET.

Accesso interattivo con MSAL.NET tramite la visualizzazione Web incorporata:

Accesso interattivo con MSAL.NET tramite il browser di sistema:

Opzioni per sviluppatori

Gli sviluppatori che usano MSAL.NET hanno diverse opzioni per visualizzare la finestra di dialogo di accesso interattivo da Microsoft Entra ID:

• Browser di sistema. Il browser di sistema è impostato per impostazione predefinita nella libreria. Se si usa Android, vedere Browser di sistema per informazioni specifiche sui browser supportati per l'autenticazione. Quando si usa il browser di sistema in Android, è consigliabile che il dispositivo disponga di un browser che supporti schede personalizzate di Chrome; in caso contrario, l'autenticazione potrebbe non riuscire.
• Visualizzazione Web incorporata. Per usare solo la visualizzazione Web incorporata in MSAL.NET, il AcquireTokenInteractive generatore contiene un WithUseEmbeddedWebView metodo .

In un'app iOS:

var result = app.AcquireTokenInteractive(scopes)
                .WithUseEmbeddedWebView(useEmbeddedWebview)
                .ExecuteAsync();

In un'app Android:

var result = app.AcquireTokenInteractive(scopes)
                .WithParentActivityOrWindow(activity)
                .WithUseEmbeddedWebView(useEmbeddedWebview)
                .ExecuteAsync();

Scelta tra visualizzazione Web incorporata o browser di sistema in iOS

Nella tua app iOS, in AppDelegate.cs puoi inizializzare ParentWindow su null. Non viene usato in iOS.

App.ParentWindow = null; // no UI parent on iOS

Scelta tra visualizzazione Web incorporata o browser di sistema in Android

Nell'app Android, in MainActivity.cs è possibile impostare l'attività padre in modo che il risultato dell'autenticazione venga restituito a quest'ultima:

 App.ParentWindow = this;

Quindi nel MainPage.xaml.cs:

var result = await App.PCA.AcquireTokenInteractive(App.Scopes)
                      .WithParentActivityOrWindow(App.ParentWindow)
                      .WithUseEmbeddedWebView(true)
                      .ExecuteAsync();

Rilevamento della presenza di schede personalizzate in Android

Se si desidera utilizzare il browser web di sistema per abilitare il Single Sign-On con le app in esecuzione nel browser, ma si teme per l'esperienza utente sui dispositivi Android che non dispongono di un browser che supporti le schede personalizzate, è possibile scegliere chiamando il IPublicClientApplication.IsSystemWebViewAvailable. Questo metodo restituisce true se il gestore pacchetti di Android rileva le schede personalizzate e false se non vengono rilevate sul dispositivo.

In base al valore restituito da questo metodo e ai requisiti, è possibile prendere una decisione:

• È possibile restituire un messaggio di errore personalizzato all'utente, ad esempio " Installare Chrome per continuare con l'autenticazione" o
• È possibile eseguire il fallback per avviare la pagina di accesso in una visualizzazione Web incorporata.

bool useSystemBrowser = app.IsSystemWebViewAvailable();

authResult = await App.PCA.AcquireTokenInteractive(App.Scopes)
                      .WithParentActivityOrWindow(App.ParentWindow)
                      .WithUseEmbeddedWebView(!useSystemBrowser)
                      .ExecuteAsync();