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

Şunlar için geçerlidir: Aşağıdaki içeriğin iş gücü kiracıları için geçerli olduğunu gösteren beyaz onay işareti simgesine sahip yeşil daire. İş gücü kiracıları (daha fazla bilgi edinin)

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 oturumunuza giriş yaptığınız hesap gibi Windows tarafından tanınan hesaplarla entegrasyon sayesinde 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ı tek 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) yetkileri 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 Microsoft.Identity.Client.Broker pakete başvurması gerekir. .NET MAUI uygulamalarının bunu yapmasına gerek yoktur, çünkü bu işlev, hedef net6-windows ve sonrasında MSAL'in içindedir.

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 MSAL.NET'de belirteç önbelleği serileştirme kısmına bkz.

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ınızı kullanmak için PublicClientApplication.OperatingSystemAccount'yi kullanın.
  • Etkileşimli olarak oturum açarak kullanıcının farklı bir hesaba değiştirmesine izin verin.

Üst pencere tutamaçları

MSAL’yi, etkileşimli deneyimin bağlı olacağı pencere ile WithParentActivityOrWindow API'lerini kullanarak 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ı almaya.

Konsol uygulamaları

Konsol uygulamaları için yapılandırma, terminal penceresi ve sekmeleri nedeniyle daha karmaşıktı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 çöktüğünü gösteren bir işarettir. Bir Windows kontrolü Windows'da yanlış kaydedilirse AccountsControl kilitlenme 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ı olan broker'ı 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.

  • Son güncelleştirme: