Web API'lerini çağıran masaüstü uygulaması: WAM kullanarak belirteç alma

  • Makale

Microsoft Kimlik Doğrulama Kitaplığı (MSAL), kimlik doğrulama aracısı işlevi gören bir Windows 10+ bileşeni olan Web Hesabı Yöneticisi'ni (WAM) çağırır. Aracı, uygulamanızın kullanıcılarının Windows oturumunuzda oturum açtığınız hesap gibi Windows tarafından bilinen hesaplarla tümleştirmeden yararlanmasına olanak tanır.

WAM değer teklifi

WAM gibi bir kimlik doğrulama aracısı kullanmanın birçok avantajı vardır:

  • Gelişmiş güvenlik. Bkz. Belirteç koruması.
  • Windows Hello, Koşullu Erişim ve FIDO anahtarları için destek.
  • Windows E-posta ve hesaplar görünümüyle tümleştirme.
  • Hızlı çoklu oturum açma.
  • Geçerli Windows hesabıyla sessizce oturum açabilme.
  • Windows ile birlikte gelen hata düzeltmeleri ve geliştirmeler.

WAM sınırlamaları

  • WAM, Windows 10 ve üzeri ile Windows Server 2019 ve sonraki sürümlerde kullanılabilir. Mac, Linux ve Windows'un önceki sürümlerinde MSAL otomatik olarak bir tarayıcıya geri döner.
  • Azure Active Directory B2C (Azure AD B2C) ve Active Directory Federasyon Hizmetleri (AD FS) (AD FS) yetkilileri desteklenmez. MSAL bir tarayıcıya geri döner.

WAM tümleştirme paketi

Çoğu uygulamanın bu tümleştirmeyi kullanmak için pakete başvurması Microsoft.Identity.Client.Broker gerekir. .NET MAUI uygulamalarının bunu yapması gerekmez, çünkü işlev hedef ve üzeri olduğunda MSAL içindedir net6-windows .

WAM çağrı düzeni

WAM için aşağıdaki deseni kullanabilirsiniz:

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

Aracı yoksa (örneğin, Windows 8.1, Mac veya Linux), MSAL yeniden yönlendirme URI kurallarının geçerli olduğu bir tarayıcıya geri döner.

Yeniden yönlendirme URI'si

MSAL'de WAM yeniden yönlendirme URI'lerini yapılandırmanız gerekmez, ancak bunları uygulama kaydında yapılandırmanız gerekir:

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

Belirteç önbelleği kalıcılığı

MSAL kimlik belirteçlerini ve hesap meta verilerini orada depolamaya devam ettiğinden MSAL belirteci önbelleğini kalıcı hale getirmek önemlidir. Daha fazla bilgi için bkz . MSAL.NET'de belirteç önbelleği serileştirme.

Sessiz oturum açma hesabı

Sessiz oturum açma için bir hesap bulmak için şu deseni öneririz:

  • Kullanıcı daha önce oturum açtıysa bu hesabı kullanın. Aksi takdirde geçerli Windows hesabı için kullanın PublicClientApplication.OperatingSystemAccount .
  • Etkileşimli olarak oturum açarak kullanıcının farklı bir hesaba değiştirmesine izin verin.

Üst pencere tutamaçları

MSAL'yi API'leri kullanarak WithParentActivityOrWindow etkileşimli deneyimin üst öğesi olması gereken pencereyle yapılandırmanız gerekir.

UI uygulamaları

Windows Forms (WinForms), Windows Presentation Foundation (WPF) veya Windows UI Kitaplığı sürüm 3 (WinUI3) gibi ui uygulamaları için bkz . Pencere tutamacını alma.

Konsol uygulamaları

Konsol uygulamaları için yapılandırma, terminal penceresi ve sekmeleri nedeniyle daha fazla yer alır. Aşağıdaki kodu kullanın:

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

Sorun giderme

"WAM Hesap Seçici bir hesap döndürmedi" hata iletisi

"WAM Hesap Seçici bir hesap döndürmedi" iletisi, uygulama kullanıcısının hesapları görüntüleyen iletişim kutusunu kapattığını veya iletişim kutusunun kendisinin kilitlendiğini gösterir. Bir Windows denetimi Windows'da yanlış kaydedilirse AccountsControlkilitlenme oluşabilir. Bu sorunu çözmek için:

  1. Görev çubuğunda Başlat'a sağ tıklayın ve ardından Windows PowerShell (Yönetici) öğesini seçin.

  2. Kullanıcı Hesabı Denetimi iletişim kutusu tarafından istenirse, PowerShell'i başlatmak için Evet'i seçin.

  3. Aşağıdaki betiği kopyalayın ve çalıştırın:

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

Tek bir dosya dağıtımı sırasında "MsalClientException: ErrorCode: wam_runtime_init_failed" hata iletisi

Uygulamanızı tek bir dosya paketinde paketlerken aşağıdaki hatayı görebilirsiniz:

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

Bu hata, Microsoft.Identity.Client.NativeInterop yerel ikili dosyalarının tek bir dosya paketinde paketlenmediğini gösterir. Ayıklama için bu dosyaları eklemek ve bir çıkış dosyası almak için özelliğini IncludeNativeLibrariesForSelfExtract olarak trueayarlayın. Yerel ikili dosyaları tek bir dosyada paketleme hakkında daha fazla bilgi edinin.

Bağlantı sorunları

Uygulama kullanıcısı düzenli olarak "Lütfen bağlantınızı denetleyin ve yeniden deneyin" gibi bir hata iletisi görürse Office için sorun giderme kılavuzuna bakın. Bu sorun giderme kılavuzu aracıyı da kullanır.

Örnek

GitHub'da WAM kullanan bir WPF örneği bulabilirsiniz.

Sonraki adımlar

Bu senaryoda masaüstü uygulamasından web API'sini çağırma adlı sonraki makaleye geçin.