Uso di MSAL.NET con Web Account Manager (WAM)

MSAL è in grado di chiamare Web Account Manager (WAM), un componente Windows fornito con il sistema operativo. Questo componente funge da broker di autenticazione e consente agli utenti dell'app di beneficiare dell'integrazione con gli account riconosciuti da Windows, ad esempio l'account con cui hai effettuato l'accesso alla sessione di Windows.

Che cos'è un broker

Un gestore di autenticazione è un'applicazione eseguita nel computer di un utente che gestisce gli handshake di autenticazione e la manutenzione dei token per gli account connessi. Il sistema operativo Windows usa Web Account Manager (WAM) come gestore di autenticazione. Offre molti vantaggi per sviluppatori e clienti, tra cui:

• Sicurezza avanzata. Molti miglioramenti della sicurezza verranno distribuiti con il broker, senza dover aggiornare la logica dell'applicazione.
• Supporto delle funzionalità. Con l'aiuto degli sviluppatori broker è possibile accedere a funzionalità avanzate del sistema operativo e del servizio, ad esempio Windows Hello, criteri di accesso condizionale e chiavi FIDO senza scrivere codice di scaffolding aggiuntivo.
• Integrazione del sistema. Applicazioni che usano il broker plug-and-play con il selettore di account integrato, consentendo all'utente di selezionare rapidamente un account esistente invece di reinserire più e più volte le stesse credenziali.
• Protezione del token WAM garantisce che i token di aggiornamento siano associati al dispositivo e consenta alle app di acquisire token di accesso associati al dispositivo. Vedere Protezione dei token.

Abilitazione di WAM

Il supporto di WAM è suddiviso tra due pacchetti:

• Microsoft. Identity.Client (ad esempio, MSAL): libreria principale per l'acquisizione di token.
• Microsoft. Identity.Client.Broker: aggiunge il supporto per l'autenticazione con il broker.

Dopo aver fatto riferimento ai pacchetti pertinenti, chiamare WithBroker(BrokerOptions) con le opzioni di configurazione del broker e un handle di finestra a cui verrà associato il broker.

var scopes = new[] { "User.Read" };

BrokerOptions options = new BrokerOptions(BrokerOptions.OperatingSystems.Windows);
options.Title = "My Awesome Application";

IPublicClientApplication app =
    PublicClientApplicationBuilder.Create("YOUR_CLIENT_ID")
    .WithDefaultRedirectUri()
    .WithParentActivityOrWindow(GetConsoleOrTerminalWindow)
    .WithBroker(options)
    .Build();

AuthenticationResult result = null;

// Try to use the previously signed-in account from the cache
IEnumerable<IAccount> accounts = await app.GetAccountsAsync();
IAccount existingAccount = accounts.FirstOrDefault();

try
{    
    if (existingAccount != null)
    {
        result = await app.AcquireTokenSilent(scopes, existingAccount).ExecuteAsync();
    }
    // Next, try to sign in silently with the account that the user is signed into Windows
    else
    {    
        result = await app.AcquireTokenSilent(scopes, PublicClientApplication.OperatingSystemAccount)
                            .ExecuteAsync();
    }
}
// Can't get a token silently, go interactive
catch (MsalUiRequiredException ex)
{
    result = await app.AcquireTokenInteractive(scopes).ExecuteAsync();
}

Quando si usa il broker, se l'autorità usata è rivolta sia a Microsoft Entra ID sia agli account Microsoft personali, all'utente verrà prima chiesto di selezionare un account usando il selettore degli account di sistema integrato.

Se la configurazione viene impostata su base per tenant usando WithTenantId o se l'autorità è impostata su un gruppo di destinatari che non include account Microsoft personali, la selezione dell'account Windows nativa non verrà visualizzata e all'utente verrà invece richiesto un prompt di autenticazione Microsoft generico.

Dopo aver aggiunto o selezionato l'account, all'utente verrà richiesto di fornire un consenso aggiuntivo se non ha mai usato l'applicazione prima o l'applicazione richiede autorizzazioni aggiuntive.

Handle della finestra principale

Per usare il broker, ora è necessario fornire l'handle della finestra a cui associare la finestra di dialogo modale WAM tramite le API WithParentActivityOrWindow. L'handle della finestra deve essere fornito dallo sviluppatore, poiché per MSAL stesso non è fattibile dedurre la finestra principale e in passato ciò ha portato a un'esperienza utente negativa, con la finestra di autenticazione nascosta dietro la finestra dell'applicazione.

Per le app dell'interfaccia utente, ad esempio quelle che usano Windows Forms, Windows Presentation Foundation (macchine virtuali Windows) o WinUI3, vedi Recuperare un handle di finestra (HWND).

Per le applicazioni console, è possibile usare codice come il frammento di codice seguente.

enum GetAncestorFlags
{   
    GetParent = 1,
    GetRoot = 2,
    /// <summary>
    /// Retrieves the owned root window by walking the chain of parent and owner windows returned by GetParent.
    /// </summary>
    GetRootOwner = 3
}

/// <summary>
/// Retrieves the handle to the ancestor of the specified window.
/// </summary>
/// <param name="hwnd">A handle to the window whose ancestor is to be retrieved.
/// If this parameter is the desktop window, the function returns NULL. </param>
/// <param name="flags">The ancestor to be retrieved.</param>
/// <returns>The return value is the handle to the ancestor window.</returns>
[DllImport("user32.dll", ExactSpelling = true)]
static extern IntPtr GetAncestor(IntPtr hwnd, GetAncestorFlags flags);

[DllImport("kernel32.dll")]
static extern IntPtr GetConsoleWindow();

// This is your window handle!
public IntPtr GetConsoleOrTerminalWindow()
{
    IntPtr consoleHandle = GetConsoleWindow();
    IntPtr handle = GetAncestor(consoleHandle, GetAncestorFlags.GetRootOwner );
    
    return handle;
}

Token di accesso con prova di possesso

Il broker WAM consente di acquisire token PoP per i flussi client pubblici. Per altri dettagli, vedere Token di verifica del possesso .

URI di reindirizzamento

Gli URI di reindirizzamento WAM non devono essere configurati in MSAL, ma devono essere configurati nella registrazione dell'app. Devono seguire il modello seguente:

ms-appx-web://microsoft.aad.brokerplugin/{client_id}

Flusso di nome utente/password

Questo flusso, noto anche come flusso con credenziali password del proprietario della risorsa (ROPC), non è consigliato, tranne che negli scenari di test o negli scenari in cui l'accesso di un'entità servizio a una risorsa garantisce un livello di accesso eccessivo e può essere limitato solo tramite i flussi utente. Quando si usa WAM, AcquireTokenByUsernamePassword consentirà a WAM di gestire il protocollo e recuperare i token.

Limitazioni di WAM

• Le autorità di Azure B2C e di Active Directory Federation Services (ADFS) non sono supportate. MSAL ricorrerà a un browser per l'autenticazione dell'utente.
• Su Mac, Linux e nelle versioni di Windows precedenti a 10 o in Windows Server 2019, MSAL ripiegherà su un browser.

Disponibilità dei pacchetti

Per usare il broker, gli sviluppatori dovranno chiamare WithBroker(PublicClientApplicationBuilder, BrokerOptions), contenuto nel pacchetto Microsoft.Identity.Client.Broker. La maggior parte delle varianti della piattaforma .NET supportate da MSAL.NET richiederà solo tale pacchetto, con alcune eccezioni. Per un mapping dettagliato, vedere la tabella seguente.

†Microsoft.Identity.Client Le versioni 4.61.0 e successive non includono più il file binario net6.0-windows7.0. Le applicazioni desktop esistenti destinate a net6.0-windows devono fare riferimento a Microsoft.Identity.Client.Broker quando si usa l'autenticazione interattiva con Windows Broker e chiamare WithBroker(PublicClientApplicationBuilder, BrokerOptions); oppure fare riferimento a Microsoft.Identity.Client.Desktop quando si esegue l'autenticazione con il browser e chiamare WithWindowsEmbeddedBrowserSupport(PublicClientApplicationBuilder).

Procedure consigliate per l'integrazione

Per assicurarsi che i clienti abbiano un'esperienza ottimale con WAM, è consigliabile rispettare i principi seguenti:

1. Fornire all'utente il contesto prima dell'autenticazione. Disegnare un'interfaccia utente o una finestra che informerà l'utente che deve eseguire l'autenticazione, insieme ai motivi per l'autenticazione. Spiegare i vantaggi dell'applicazione se si tratta di un servizio in background.
2. Richiamare l'autenticazione in base all'azione dell'utente. L'utente deve tenere presente che ha attivato il processo di autenticazione in un'applicazione specifica facendo clic su un collegamento o un pulsante oppure eseguendo un altro gesto. Gli utenti non devono digitare le credenziali nelle finestre che vengono visualizzate all'interno del sistema operativo senza contesto o azioni associate.
3. Provare ad acquisire il token in modo invisibile all'utente ed eseguire il fallback alla richiesta interattiva in caso di errore. Ai clienti deve essere richiesta l'autenticazione interattiva solo se è necessario immettere nuovamente le credenziali o soddisfare un requisito di criteri.

Troubleshooting

"MsalClientException (ErrCode 5376): è necessario richiedere almeno un ambito per questo flusso di autenticazione."

Questo messaggio indica che è necessario richiedere almeno un ambito applicazione ,ad esempio user.read, insieme ad altri ambiti OIDC (profileemailo offline_access).

var authResult = await pca.AcquireTokenInteractive(new[] { "user.read" })
                 .ExecuteAsync();

Il selettore di account non viene visualizzato

A volte un aggiornamento Windows può influire involontariamente sul componente selezione account, che mostra l'elenco di account in Windows e l'opzione per aggiungere nuovi account. Il problema è che il selettore non viene visualizzato per un numero limitato di utenti.

Una possibile soluzione alternativa consiste nel registrare nuovamente il componente. Eseguire questo script dal terminale con autorizzazioni di amministratore:

if (-not (Get-AppxPackage Microsoft.AccountsControl))
{ 
    Add-AppxPackage -Register "$env:windir\SystemApps\Microsoft.AccountsControl_cw5n1h2txyewy\AppxManifest.xml" -DisableDevelopmentMode -ForceApplicationShutdown 
}

Get-AppxPackage Microsoft.AccountsControl

Problemi di connessione

L'utente dell'applicazione visualizza un messaggio di errore simile a Please check your connection and try again. Se questo problema si verifica regolarmente, vedere la guida alla risoluzione dei problemi per Office, che usa anche WAM.

Codici di errore WAM

Per informazioni dettagliate sugli errori WAM, vedere Errori associati a Web Account Manager (WAM ).

Poiché WAM è un componente relativamente nuovo, quando si verificano errori è consigliabile registrare i dati da AdditionalExceptionData. Ciò consente di individuare problemi specifici relativi alla configurazione o al componente WAM. Quando si verificano problemi di WAM, registrare un bug . Ciò ci aiuterà a risolvere il problema in modo tempestivo.When you run into WAM issues, please log a bug- this will help us ensure we address the problem in a timely manner.