Aplikasi desktop yang memanggil API web: Memperoleh token dengan menggunakan WAM

Artikel
2025-03-05

Berlaku untuk: Lingkaran hijau dengan simbol tanda centang putih. Penyewa Tenaga Kerja Lingkaran putih dengan simbol X abu-abu. Penyewa Eksternal (pelajari lebih lanjut)

Microsoft Authentication Library (MSAL) memanggil Web Account Manager (WAM), komponen Windows 10+ yang bertindak sebagai broker autentikasi. Broker memungkinkan pengguna aplikasi Anda untuk memanfaatkan integrasi dengan akun yang dikenal Windows, seperti akun yang Anda gunakan untuk masuk ke sesi Windows Anda.

Proposisi nilai WAM

Menggunakan broker autentikasi seperti WAM memiliki banyak manfaat:

Keamanan yang ditingkatkan. Lihat Perlindungan Token.
Dukungan untuk Windows Hello, Akses Bersyarat, dan kunci FIDO.
Integrasi dengan tampilan Windows Email & akun-akun.
Single sign-on yang cepat.
Kemampuan untuk masuk secara diam-diam dengan akun Windows saat ini.
Perbaikan bug dan penyempurnaan dikirim dengan Windows.

Batasan WAM

WAM tersedia di Windows 10 dan yang lebih baru, dan pada Windows Server 2019 dan yang lebih baru. Di Mac, Linux, dan versi Windows yang lebih lama, MSAL secara otomatis kembali ke browser.
Otoritas Azure Active Directory B2C (Azure AD B2C) dan Active Directory Federation Services (AD FS) tidak didukung. MSAL kembali ke browser.

Paket integrasi WAM

Sebagian besar aplikasi perlu mereferensikan Microsoft.Identity.Client.Broker paket untuk menggunakan integrasi ini. Aplikasi .NET MAUI tidak perlu melakukan ini, karena fungsionalitas sudah ada di dalam MSAL ketika target adalah net6-windows dan yang lebih baru.

Pola panggilan WAM

Anda dapat menggunakan pola berikut untuk WAM:

    // 1. Configuration - read below about redirect URI
    var pca = PublicClientApplicationBuilder.Create("client_id")
                    .WithBroker(new BrokerOptions(BrokerOptions.OperatingSystems.Windows))
                    .Build();

    // Add a token cache; see https://learn.microsoft.com/azure/active-directory/develop/msal-net-token-cache-serialization?tabs=desktop

    // 2. Find an account for silent login

    // Is there an account in the cache?
    IAccount accountToLogin = (await pca.GetAccountsAsync()).FirstOrDefault();
    if (accountToLogin == null)
    {
        // 3. No account in the cache; try to log in with the OS account
        accountToLogin = PublicClientApplication.OperatingSystemAccount;
    }

    try
    {
        // 4. Silent authentication 
        var authResult = await pca.AcquireTokenSilent(new[] { "User.Read" }, accountToLogin)
                                    .ExecuteAsync();
    }
    // Cannot log in silently - most likely Azure AD would show a consent dialog or the user needs to re-enter credentials
    catch (MsalUiRequiredException) 
    {
        // 5. Interactive authentication
        var authResult = await pca.AcquireTokenInteractive(new[] { "User.Read" })
                                    .WithAccount(accountToLogin)
                                    // This is mandatory so that WAM is correctly parented to your app; read on for more guidance
                                    .WithParentActivityOrWindow(myWindowHandle) 
                                    .ExecuteAsync();
                                    
        // Consider allowing the user to re-authenticate with a different account, by calling AcquireTokenInteractive again                                  
    }

Jika broker tidak ada (misalnya, Windows 8.1, Mac, atau Linux), MSAL kembali ke browser, di mana aturan URI pengalihan berlaku.

URI Pengalihan

Anda tidak perlu mengonfigurasi URI pengalihan WAM di MSAL, tetapi Anda perlu mengonfigurasinya dalam pendaftaran aplikasi:

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

Persistensi token cache

Penting untuk mempertahankan cache token MSAL karena MSAL terus menyimpan token ID dan metadata akun di sana. Untuk informasi selengkapnya, lihat Serialisasi cache token di MSAL.NET.

Untuk menemukan akun untuk masuk senyap, kami merekomendasikan pola ini:

Jika pengguna sebelumnya masuk, gunakan akun tersebut. Jika tidak, gunakan PublicClientApplication.OperatingSystemAccount untuk akun Windows saat ini.
Izinkan pengguna untuk mengubah ke akun lain dengan masuk secara interaktif.

Penanganan jendela induk

Anda harus mengonfigurasi MSAL dengan jendela tempat pengalaman interaktif harus dijadikan induk, dengan menggunakan WithParentActivityOrWindow APIs.

Aplikasi UI

Untuk aplikasi UI seperti Windows Forms (WinForms), Windows Presentation Foundation (WPF), atau Windows UI Library versi 3 (WinUI3), lihat Mendapatkan handle jendela.

Aplikasi konsol

Untuk aplikasi konsol, konfigurasi lebih terlibat karena jendela terminal dan tabnya. Gunakan kode berikut:

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

Pemecahan Masalah

Pesan kesalahan "WAM Account Picker tidak mengembalikan akun"

Pesan "Pemilih Akun WAM tidak mengembalikan akun" menunjukkan bahwa pengguna aplikasi menutup dialog yang menampilkan akun, atau dialog itu sendiri mengalami crash. Kerusakan sistem mungkin terjadi jika AccountsControl, kontrol Windows, didaftarkan secara tidak benar di Windows. Untuk mengatasi masalah ini:

Pada taskbar, klik kanan Mulai, lalu pilih Windows PowerShell (Admin).
Jika Anda diminta oleh dialog Kontrol Akun Pengguna, pilih Ya untuk memulai PowerShell.

Salin lalu jalankan skrip berikut:

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

Pesan kesalahan "MsalClientException: ErrorCode: wam_runtime_init_failed" selama penerapan berkas tunggal

Anda mungkin melihat kesalahan berikut saat mengemas aplikasi Anda ke dalam satu bundel file:

MsalClientException: wam_runtime_init_failed: The type initializer for 'Microsoft.Identity.Client.NativeInterop.API' threw an exception. See https://aka.ms/msal-net-wam#troubleshooting

Kesalahan ini menunjukkan bahwa biner asli dari Microsoft.Identity.Client.NativeInterop tidak dikemas ke dalam bundel file tunggal. Untuk menyematkan file tersebut untuk ekstraksi dan mendapatkan satu file output, atur properti IncludeNativeLibrariesForSelfExtract ke true. Baca selengkapnya tentang cara mengemas biner asli ke dalam satu file.

Masalah koneksi

Jika pengguna aplikasi secara teratur melihat pesan kesalahan yang mirip dengan "Silakan periksa koneksi Anda dan coba lagi," lihat panduan pemecahan masalah untuk Office. Panduan pemecahan masalah itu juga menggunakan broker.

Sampel

Anda dapat menemukan sampel WPF yang menggunakan WAM di GitHub.

Langkah berikutnya

Lanjutkan ke artikel berikutnya dalam skenario ini, yaitu Panggil API web dari aplikasi desktop.

Bagikan melalui