Megosztás a következőn keresztül:

Webes API-kat hívó asztali alkalmazás: Jogkivonat beszerzése WAM használatával

  • Cikk

A Microsoft Authentication Library (MSAL) meghívja a Web Account Managert (WAM), egy Windows 10+ összetevőt, amely hitelesítési közvetítőként működik. A közvetítő lehetővé teszi az alkalmazás felhasználói számára, hogy kihasználják a Windows által ismert fiókokkal, például a Windows-munkamenetbe bejelentkezett fiókkal való integráció előnyeit.

WAM-értékajánlat

A hitelesítési közvetítő, például a WAM használata számos előnnyel jár:

  • Fokozott biztonság. Lásd: Jogkivonat-védelem.
  • A Windows Hello, a Feltételes hozzáférés és a FIDO-kulcsok támogatása.
  • Integráció a Windows E-mail > fióknézettel .
  • Gyors egyszeri bejelentkezés.
  • Az aktuális Windows-fiókkal való csendes bejelentkezés lehetősége.
  • A Windowshoz szállított hibajavítások és fejlesztések.

WAM-korlátozások

  • A WAM windows 10-en és újabb verziókban, valamint Windows Server 2019 és újabb rendszereken érhető el. Mac, Linux és a Windows korábbi verzióiban az MSAL automatikusan visszaesik egy böngészőbe.
  • Az Azure Active Directory B2C (Azure AD B2C) és Active Directory összevonási szolgáltatások (AD FS) (AD FS) hatóságok nem támogatottak. Az MSAL visszaesik egy böngészőbe.

WAM integrációs csomag

A legtöbb alkalmazásnak hivatkoznia kell a Microsoft.Identity.Client.Broker csomagra az integráció használatához. A .NET MAUI-alkalmazásoknak nem kell ezt megtenniük, mert a funkció az MSAL-en belül van, amikor a cél és net6-windows újabb.

WAM-hívási minta

A WAM esetében a következő mintát használhatja:

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

Ha nincs közvetítő (például Windows 8.1, Mac vagy Linux), az MSAL visszakerül egy böngészőbe, ahol az átirányítási URI-szabályok érvényesek.

Átirányítási URI

A WAM átirányítási URI-jait nem kell konfigurálnia az MSAL-ban, de konfigurálnia kell őket az alkalmazásregisztrációban:

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

Jogkivonat-gyorsítótár megőrzése

Fontos az MSAL-jogkivonat gyorsítótárának megőrzése, mert az MSAL továbbra is tárolja az azonosító jogkivonatokat és a fiók metaadatait. További információkért lásd a tokengyorsítótár szerializálását a MSAL.NET.

Fiók csendes bejelentkezéshez

A csendes bejelentkezéshez használt fiók megkereséséhez a következő mintát javasoljuk:

  • Ha a felhasználó korábban bejelentkezett, használja ezt a fiókot. Ha nem, használja PublicClientApplication.OperatingSystemAccount az aktuális Windows-fiókhoz.
  • Interaktív bejelentkezéssel engedélyezheti a felhasználónak, hogy másik fiókra váltson.

Szülőablak fogópontjai

Az MSAL-t úgy kell konfigurálnia, hogy az interaktív felületet az API-k használatával WithParentActivityOrWindow szülőként kell használni.

Felhasználói felületi alkalmazások

Az olyan felhasználói felületi alkalmazások esetében, mint a Windows Forms (WinForms), a Windows megjelenítési alaprendszer (WPF) vagy a Windows felhasználói felületi kódtár 3-as verziója (WinUI3), tekintse meg az ablakleíró lekérése című témakört.

Konzolalkalmazások

A konzolalkalmazások esetében a konfiguráció a terminálablak és a lapfülek miatt nagyobb szerepet játszik. Használja a következő kódot:

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

Hibaelhárítás

"A WAM-fiókválasztó nem adott vissza fiókot" hibaüzenet

A "WAM-fiókválasztó nem adott vissza fiókot" üzenet azt jelzi, hogy az alkalmazás felhasználója bezárta a fiókokat megjelenítő párbeszédpanelt, vagy maga a párbeszédpanel összeomlott. Összeomlás akkor fordulhat elő, ha AccountsControlegy Windows-vezérlő helytelenül van regisztrálva a Windowsban. A probléma megoldása:

  1. A tálcán kattintson a jobb gombbal a Start gombra, majd válassza a Windows PowerShell (Rendszergazda) parancsot.

  2. Ha egy felhasználói fiókvezérlő párbeszédpanel kéri, válassza az Igen lehetőséget a PowerShell elindításához.

  3. Másolja ki, majd futtassa a következő szkriptet:

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

"MsalClientException: ErrorCode: wam_runtime_init_failed" hibaüzenet egyetlen fájl üzembe helyezése során

A következő hibaüzenet jelenhet meg, amikor az alkalmazást egyetlen fájlcsomagba csomagolja:

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

Ez a hiba azt jelzi, hogy a Microsoft.Identity.Client.NativeInterop natív bináris fájljai nem lettek egyetlen fájlcsomagba csomagolva. A fájlok kinyeréshez való beágyazásához és egy kimeneti fájl lekéréséhez állítsa a tulajdonságot IncludeNativeLibrariesForSelfExtract a következőre true: . További információ arról, hogyan csomagolhat natív bináris fájlokat egyetlen fájlba.

Csatlakozási problémák

Ha az alkalmazás felhasználója rendszeresen a "Kérjük, ellenőrizze a kapcsolatot, és próbálkozzon újra" üzenethez hasonló hibaüzenet jelenik meg, tekintse meg az Office hibaelhárítási útmutatóját. Ez a hibaelhárítási útmutató a közvetítőt is használja.

Minta

A GitHubon WAM-et használó WPF-mintát találhat.

Következő lépések

Lépjen tovább a következő cikkre ebben a forgatókönyvben: Webes API meghívása az asztali alkalmazásból.