Udostępnij za pośrednictwem

Aplikacja klasyczna, która wywołuje internetowe interfejsy API: uzyskiwanie tokenu przy użyciu WAM

  • Artykuł

Biblioteka Microsoft Authentication Library (MSAL) wywołuje menedżera kont sieci Web (WAM), składnika systemu Windows 10 lub nowszego, który działa jako broker uwierzytelniania. Broker umożliwia użytkownikom aplikacji korzystanie z integracji z kontami znanymi dla systemu Windows, takimi jak konto zalogowane do sesji systemu Windows.

Propozycja wartości WAM

Korzystanie z brokera uwierzytelniania, takiego jak WAM, ma wiele korzyści:

  • Zwiększone zabezpieczenia. Zobacz Ochrona tokenów.
  • Obsługa kluczy Funkcji Windows Hello, dostępu warunkowego i fiDO.
  • Integracja z widokiem Poczty e-mail i kont systemu Windows.
  • Szybkie logowanie jednokrotne.
  • Możliwość logowania się dyskretnie przy użyciu bieżącego konta systemu Windows.
  • Poprawki błędów i ulepszenia dostarczane z systemem Windows.

Ograniczenia WAM

  • WAM jest dostępny w systemie Windows 10 lub nowszym oraz w systemie Windows Server 2019 i nowszych wersjach. Na komputerach Mac, Linux i starszych wersjach systemu Windows biblioteka MSAL automatycznie wraca do przeglądarki.
  • Urzędy usług Azure Active Directory B2C (Azure AD B2C) i Active Directory Federation Services (AD FS) nie są obsługiwane. Biblioteka MSAL wraca do przeglądarki.

Pakiet integracyjny WAM

Większość aplikacji musi odwoływać się Microsoft.Identity.Client.Broker do pakietu w celu korzystania z tej integracji. Aplikacje MAUI platformy .NET nie muszą tego robić, ponieważ funkcja znajduje się wewnątrz biblioteki MSAL, gdy element docelowy jest net6-windows i nowszy.

Wzorzec wywoływania WAM

W programie WAM można użyć następującego wzorca:

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

Jeśli broker nie jest obecny (na przykład Windows 8.1, Mac lub Linux), biblioteka MSAL powraca do przeglądarki, w której mają zastosowanie reguły identyfikatora URI przekierowania.

Adres URI przekierowania

Nie musisz konfigurować identyfikatorów URI przekierowania WAM w usłudze MSAL, ale musisz je skonfigurować w rejestracji aplikacji:

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

Trwałość pamięci podręcznej tokenu

Ważne jest utrwalanie pamięci podręcznej tokenu MSAL, ponieważ biblioteka MSAL nadal przechowuje tam tokeny identyfikatorów i metadane konta. Aby uzyskać więcej informacji, zobacz Serializacja pamięci podręcznej tokenów w MSAL.NET.

Konto logowania dyskretnego

Aby znaleźć konto do logowania dyskretnego, zalecamy następujący wzorzec:

  • Jeśli użytkownik wcześniej się zalogował, użyj tego konta. Jeśli nie, użyj bieżącego PublicClientApplication.OperatingSystemAccount konta systemu Windows.
  • Zezwól użytkownikowi na zmianę na inne konto, logując się interaktywnie.

Uchwyty okien nadrzędnych

Należy skonfigurować bibliotekę MSAL przy użyciu okna, do którego powinno być nadrzędne środowisko, przy użyciu WithParentActivityOrWindow interfejsów API.

Aplikacje interfejsu użytkownika

W przypadku aplikacji interfejsu użytkownika, takich jak Windows Forms (WinForms), Windows Presentation Foundation (WPF) lub Windows UI Library w wersji 3 (WinUI3), zobacz Pobieranie uchwytu okna.

Aplikacje konsolowe

W przypadku aplikacji konsolowych konfiguracja jest bardziej zaangażowana ze względu na okno terminalu i jego karty. Użyj następującego kodu:

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

Rozwiązywanie problemów

Komunikat o błędzie "Selektor kont WAM nie zwrócił konta"

Komunikat "Selektor kont WAM nie zwrócił konta" wskazuje, że użytkownik aplikacji zamknął okno dialogowe z wyświetlonymi kontami lub samo okno dialogowe uległo awarii. Awaria może wystąpić, jeśli AccountsControlkontrolka systemu Windows jest niepoprawnie zarejestrowana w systemie Windows. Aby rozwiązać ten problem:

  1. Na pasku zadań kliknij prawym przyciskiem myszy przycisk Start, a następnie wybierz pozycję Windows PowerShell (Administracja).

  2. Jeśli zostanie wyświetlony monit w oknie dialogowym Kontrola konta użytkownika, wybierz pozycję Tak , aby uruchomić program PowerShell.

  3. Skopiuj, a następnie uruchom następujący skrypt:

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

Komunikat o błędzie "MsalClientException: ErrorCode: wam_runtime_init_failed" podczas wdrożenia pojedynczego pliku

Podczas tworzenia pakietów aplikacji w jednym pakiecie plików może zostać wyświetlony następujący błąd:

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

Ten błąd wskazuje, że natywne pliki binarne z witryny Microsoft.Identity.Client.NativeInterop nie zostały spakowane w jednym pakiecie plików. Aby osadzić te pliki na potrzeby wyodrębniania i pobrać jeden plik wyjściowy, ustaw właściwość IncludeNativeLibrariesForSelfExtract na truewartość . Dowiedz się więcej na temat tworzenia pakietów natywnych plików binarnych w jednym pliku.

Problemy z połączeniem

Jeśli użytkownik aplikacji regularnie widzi komunikat o błędzie podobny do "Sprawdź połączenie i spróbuj ponownie", zobacz przewodnik rozwiązywania problemów dla pakietu Office. Ten przewodnik rozwiązywania problemów korzysta również z brokera.

Przykład

Przykład WPF, który korzysta z WAM w witrynie GitHub.

Następne kroki

Przejdź do następnego artykułu w tym scenariuszu, wywołaj internetowy interfejs API z aplikacji klasycznej.