Udostępnij za pośrednictwem

Menedżer kont sieci Web

W tym artykule opisano, jak używać AccountsSettingsPane do łączenia aplikacji UWP platformy uniwersalnej Windows z zewnętrznymi dostawcami tożsamości, takimi jak Microsoft lub Facebook, przy użyciu interfejsów API Menedżera kont internetowych systemu Windows 10 i Windows 11. Dowiesz się, jak zażądać uprawnienia użytkownika do korzystania z konta Microsoft, uzyskać token dostępu i użyć go do wykonywania podstawowych operacji (takich jak pobieranie danych profilu lub przekazywanie plików do konta usługi OneDrive). Kroki są podobne do uzyskiwania uprawnień użytkownika i dostępu do dowolnego dostawcy tożsamości obsługującego Menedżera kont sieci Web.

Uwaga / Notatka

Pełny przykładowy kod można znaleźć w przykładzie WebAccountManagement w witrynie GitHub.

Rozpocznij konfigurowanie

Najpierw utwórz nową, pustą aplikację w programie Visual Studio.

Po drugie, aby połączyć się z dostawcami tożsamości, musisz skojarzyć aplikację ze Sklepem. Aby to zrobić, kliknij prawym przyciskiem myszy swój projekt, wybierz Store/Publish>Associate app with the store, a następnie postępuj zgodnie z instrukcjami kreatora.

Po trzecie, utwórz bardzo podstawowy interfejs użytkownika składający się z prostego przycisku XAML i dwóch pól tekstowych.

<StackPanel HorizontalAlignment="Center" VerticalAlignment="Center">
	<Button x:Name="LoginButton" Content="Log in" Click="LoginButton_Click" />
	<TextBlock x:Name="UserIdTextBlock"/>
	<TextBlock x:Name="UserNameTextBlock"/>
</StackPanel>

Program obsługi zdarzeń dołączony do przycisku w kodzie:

private void LoginButton_Click(object sender, RoutedEventArgs e)
{	
}

Na koniec dodaj następujące przestrzenie nazw, aby nie martwić się o żadne problemy referencyjne później:

using System;
using Windows.Security.Authentication.Web.Core;
using Windows.System;
using Windows.UI.ApplicationSettings;
using Windows.UI.Xaml;
using Windows.UI.Xaml.Controls;
using Windows.Data.Json;
using Windows.UI.Xaml.Navigation;
using Windows.Web.Http;

Pokaż okienko ustawień kont

System udostępnia wbudowany interfejs użytkownika do zarządzania dostawcami tożsamości i kontami internetowymi o nazwie AccountsSettingsPane. Możesz to pokazać w następujący sposób:

private void LoginButton_Click(object sender, RoutedEventArgs e)
{
	AccountsSettingsPane.Show(); 
}

Jeśli uruchomisz aplikację i klikniesz przycisk "Zaloguj się", powinno zostać wyświetlone puste okno.

Zrzut ekranu przedstawiający okno Wybieranie konta bez kont na liście.

Okienko jest puste, ponieważ system udostępnia tylko powłokę interfejsu użytkownika — deweloper może programowo wypełnić okienko dostawcami tożsamości.

Wskazówka

Opcjonalnie możesz użyć ShowAddAccountAsync zamiast Show, która zwróci IAsyncAction, aby wykonać zapytanie o stan operacji.

Zarejestruj się w AccountCommandsRequested

Aby dodać polecenia do okienka, zacznijmy od zarejestrowania się w programie obsługi zdarzeń AccountCommandsRequested. Informuje to system o uruchomieniu logiki kompilacji, gdy użytkownik poprosi o wyświetlenie okienka (na przykład klika nasz przycisk XAML).

W kodzie za nim zastąpij zdarzenia OnNavigatedTo i OnNavigatedFrom i dodaj do nich następujący kod:

protected override void OnNavigatedTo(NavigationEventArgs e)
{
	AccountsSettingsPane.GetForCurrentView().AccountCommandsRequested += BuildPaneAsync; 
}

protected override void OnNavigatedFrom(NavigationEventArgs e)
{
	AccountsSettingsPane.GetForCurrentView().AccountCommandsRequested -= BuildPaneAsync; 
}

Użytkownicy nie wchodzą w interakcje z kontami bardzo często, dlatego rejestrowanie i wyrejestrowanie programu obsługi zdarzeń w ten sposób pomaga zapobiec wyciekom pamięci. W ten sposób dostosowany panel znajduje się w pamięci tylko wtedy, gdy istnieje duże prawdopodobieństwo, że użytkownik go potrzebuje (na przykład gdy znajduje się na stronie "ustawienia" lub "logowanie").

Tworzenie okienka ustawień konta

Metoda BuildPaneAsync jest wywoływana za każdym razem, gdy jest wyświetlana AccountsSettingsPane. W tym miejscu umieścimy kod w celu dostosowania poleceń wyświetlanych w okienku.

Zacznij od uzyskania odroczenia. Informuje to system o opóźnieniu wyświetlania AccountsSettingsPane do momentu, gdy skończymy go budować.

private async void BuildPaneAsync(AccountsSettingsPane s,
	AccountsSettingsPaneCommandsRequestedEventArgs e)
{
	var deferral = e.GetDeferral();
		
	deferral.Complete(); 
}

Następnie uzyskaj dostawcę przy użyciu metody WebAuthenticationCoreManager.FindAccountProviderAsync. Adres URL dostawcy różni się w zależności od dostawcy i można go znaleźć w dokumentacji dostawcy. W przypadku kont Microsoft i usługi Azure Active Directory jest to "https://login.microsoft.com".

private async void BuildPaneAsync(AccountsSettingsPane s,
	AccountsSettingsPaneCommandsRequestedEventArgs e)
{
	var deferral = e.GetDeferral();
		
	var msaProvider = await WebAuthenticationCoreManager.FindAccountProviderAsync(
		"https://login.microsoft.com", "consumers"); 
		
	deferral.Complete(); 
}

Zwróć uwagę, że przekazujemy również ciąg "konsumenci" do opcjonalnego urzędu parametru. Dzieje się tak, ponieważ firma Microsoft udostępnia dwa różne typy uwierzytelniania — konta Microsoft (MSA) dla "konsumentów" i usługę Azure Active Directory (AAD) dla "organizacji". Organ konsumentów wskazuje, że preferujemy opcję MSA. Jeśli tworzysz aplikację dla przedsiębiorstw, zamiast tego użyj ciągu "organizacje".

Na koniec dodaj dostawcę do elementu AccountsSettingsPane , tworząc nowy element WebAccountProviderCommand w następujący sposób:

private async void BuildPaneAsync(AccountsSettingsPane s,
	AccountsSettingsPaneCommandsRequestedEventArgs e)
{
	var deferral = e.GetDeferral();

	var msaProvider = await WebAuthenticationCoreManager.FindAccountProviderAsync(
		"https://login.microsoft.com", "consumers");

	var command = new WebAccountProviderCommand(msaProvider, GetMsaTokenAsync);  

	e.WebAccountProviderCommands.Add(command);

	deferral.Complete(); 
}

Metoda GetMsaToken przekazana do nowej metody WebAccountProviderCommand jeszcze nie istnieje (skompilujemy ją w następnym kroku), więc możesz dodać ją jako pustą metodę na razie.

Uruchom powyższy kod, a okienko powinno wyglądać mniej więcej tak:

Zrzut ekranu przedstawiający okno Wybieranie konta z wyświetlonymi kontami.

Żądanie tokenu

Po wyświetleniu opcji Konto Microsoft w okienku AccountsSettingsPane musimy obsłużyć to, co się stanie po wybraniu go przez użytkownika. Zarejestrowaliśmy metodę GetMsaToken w celu uruchomienia, gdy użytkownik zdecyduje się zalogować przy użyciu konta Microsoft, więc uzyskamy tam token.

Aby uzyskać token, użyj metody RequestTokenAsync w następujący sposób:

private async void GetMsaTokenAsync(WebAccountProviderCommand command)
{
	WebTokenRequest request = new WebTokenRequest(command.WebAccountProvider, "wl.basic");
	WebTokenRequestResult result = await WebAuthenticationCoreManager.RequestTokenAsync(request);
}

W tym przykładzie przekazujemy ciąg "wl.basic" do parametru zakresu . Zakres reprezentuje typ informacji żądanych od dostawcy usługi dla określonego użytkownika. Niektóre zakresy zapewniają dostęp tylko do podstawowych informacji użytkownika, takich jak nazwa i adres e-mail, podczas gdy inne zakresy mogą udzielać dostępu do poufnych informacji, takich jak zdjęcia użytkownika lub skrzynka odbiorcza poczty e-mail. Ogólnie rzecz biorąc, aplikacja powinna używać najmniej permissywnego zakresu niezbędnego do osiągnięcia jej funkcji. Dostawcy usług udostępnią dokumentację, w której zakresy są potrzebne do uzyskania tokenów w ramach ich usług.

Wskazówka

Opcjonalnie, jeśli aplikacja używa wskazówki logowania (aby wypełnić pole użytkownika domyślnym adresem e-mail) lub inną specjalną właściwość związaną ze środowiskiem logowania, wyświetl ją we właściwości WebTokenRequest.AppProperties . Spowoduje to, że system zignoruje właściwość podczas buforowania konta internetowego, co zapobiegnie niezgodnościom kont w pamięci podręcznej.

Jeśli tworzysz aplikację dla przedsiębiorstw, prawdopodobnie chcesz nawiązać połączenie z instancją Azure Active Directory (AAD) i użyć interfejsu API Microsoft Graph zamiast zwykłych usług kont Microsoft (MSA). W tym scenariuszu użyj następującego kodu:

private async void GetAadTokenAsync(WebAccountProviderCommand command)
{
	string clientId = "your_guid_here"; // Obtain your clientId from the Azure Portal
	WebTokenRequest request = new WebTokenRequest(provider, "User.Read", clientId);
	request.Properties.Add("resource", "https://graph.microsoft.com");
	WebTokenRequestResult result = await WebAuthenticationCoreManager.RequestTokenAsync(request);
}

Pozostała część tego artykułu opisuje scenariusz MSA, ale kod usługi AAD jest bardzo podobny. Aby uzyskać więcej informacji na temat AAD/Graph, w tym pełnego przykładu na GitHub, zobacz dokumentację Microsoft Graph .

Korzystanie z tokenu

Metoda RequestTokenAsync zwraca obiekt WebTokenRequestResult zawierający wyniki żądania. Jeśli żądanie zakończyło się pomyślnie, będzie zawierało token.

private async void GetMsaTokenAsync(WebAccountProviderCommand command)
{
	WebTokenRequest request = new WebTokenRequest(command.WebAccountProvider, "wl.basic");
	WebTokenRequestResult result = await WebAuthenticationCoreManager.RequestTokenAsync(request);
	
	if (result.ResponseStatus == WebTokenRequestStatus.Success)
	{
		string token = result.ResponseData[0].Token; 
	}
}

Uwaga / Notatka

Jeśli podczas żądania tokenu wystąpi błąd, upewnij się, że aplikacja została skojarzona ze Sklepem zgodnie z opisem w kroku 1. Aplikacja nie będzie mogła uzyskać tokenu, jeśli pominięto ten krok.

Po utworzeniu tokenu możesz go użyć do wywołania interfejsu API dostawcy. W poniższym kodzie wywołamy interfejs API Microsoft Live dotyczący informacji o użytkowniku, aby uzyskać podstawowe informacje o użytkowniku i wyświetlić je w naszym interfejsie użytkownika. Należy jednak pamiętać, że w większości przypadków zaleca się przechowywanie tokenu po uzyskaniu, a następnie użycie go w oddzielnej metodzie.

private async void GetMsaTokenAsync(WebAccountProviderCommand command)
{
	WebTokenRequest request = new WebTokenRequest(command.WebAccountProvider, "wl.basic");
	WebTokenRequestResult result = await WebAuthenticationCoreManager.RequestTokenAsync(request);
	
	if (result.ResponseStatus == WebTokenRequestStatus.Success)
	{
		string token = result.ResponseData[0].Token; 
		
		var restApi = new Uri(@"https://apis.live.net/v5.0/me?access_token=" + token);

		using (var client = new HttpClient())
		{
			var infoResult = await client.GetAsync(restApi);
			string content = await infoResult.Content.ReadAsStringAsync();

			var jsonObject = JsonObject.Parse(content);
			string id = jsonObject["id"].GetString();
			string name = jsonObject["name"].GetString();

			UserIdTextBlock.Text = "Id: " + id; 
			UserNameTextBlock.Text = "Name: " + name;
		}
	}
}

Sposób wywoływania różnych interfejsów API REST różni się między dostawcami; Aby uzyskać informacje na temat używania tokenu, zobacz dokumentację interfejsu API dostawcy.

Przechowywanie konta do użytku w przyszłości

Tokeny są przydatne do natychmiastowego uzyskiwania informacji o użytkowniku, ale zwykle mają różne cykle życia — tokeny MSA, na przykład, są ważne tylko przez kilka godzin. Na szczęście nie musisz ponownie wyświetlać elementu AccountsSettingsPane za każdym razem, gdy token wygaśnie. Gdy użytkownik autoryzuje aplikację raz, możesz przechowywać informacje o koncie użytkownika do użytku w przyszłości.

W tym celu użyj klasy WebAccount . WebAccount jest zwracany przez tę samą metodę, którą użyto do żądania tokenu.

private async void GetMsaTokenAsync(WebAccountProviderCommand command)
{
	WebTokenRequest request = new WebTokenRequest(command.WebAccountProvider, "wl.basic");
	WebTokenRequestResult result = await WebAuthenticationCoreManager.RequestTokenAsync(request);
	
	if (result.ResponseStatus == WebTokenRequestStatus.Success)
	{
		WebAccount account = result.ResponseData[0].WebAccount; 
	}
}

Gdy masz wystąpienie WebAccount , możesz je łatwo przechowywać. W poniższym przykładzie używamy ustawień lokalnych. Aby uzyskać więcej informacji na temat używania ustawień lokalnych i innych metod przechowywania danych użytkownika, zobacz Przechowywanie i pobieranie ustawień aplikacji i danych.

private async void StoreWebAccount(WebAccount account)
{
	ApplicationData.Current.LocalSettings.Values["CurrentUserProviderId"] = account.WebAccountProvider.Id;
	ApplicationData.Current.LocalSettings.Values["CurrentUserId"] = account.Id; 
}

Następnie możemy użyć metody asynchronicznej, takiej jak pokazano poniżej, aby spróbować uzyskać token w tle z przechowywanym WebAccount.

private async Task<string> GetTokenSilentlyAsync()
{
	string providerId = ApplicationData.Current.LocalSettings.Values["CurrentUserProviderId"]?.ToString();
	string accountId = ApplicationData.Current.LocalSettings.Values["CurrentUserId"]?.ToString();

	if (null == providerId || null == accountId)
	{
		return null; 
	}

	WebAccountProvider provider = await WebAuthenticationCoreManager.FindAccountProviderAsync(providerId);
	WebAccount account = await WebAuthenticationCoreManager.FindAccountAsync(provider, accountId);

	WebTokenRequest request = new WebTokenRequest(provider, "wl.basic");

	WebTokenRequestResult result = await WebAuthenticationCoreManager.GetTokenSilentlyAsync(request, account);
	if (result.ResponseStatus == WebTokenRequestStatus.UserInteractionRequired)
	{
		// Unable to get a token silently - you'll need to show the UI
		return null; 
	}
	else if (result.ResponseStatus == WebTokenRequestStatus.Success)
	{
		// Success
		return result.ResponseData[0].Token;
	}
	else
	{
		// Other error 
		return null; 
	}
}

Umieść powyższą metodę tuż przed kodem, który kompiluje element AccountsSettingsPane. Jeśli token zostanie uzyskany w tle, nie ma potrzeby wyświetlania okienka.

private void LoginButton_Click(object sender, RoutedEventArgs e)
{
	string silentToken = await GetMsaTokenSilentlyAsync();

	if (silentToken != null)
	{
		// the token was obtained. store a reference to it or do something with it here.
	}
	else
	{
		// the token could not be obtained silently. Show the AccountsSettingsPane
		AccountsSettingsPane.Show();
	}
}

Ponieważ uzyskiwanie tokenu w trybie dyskretnym jest bardzo proste, należy użyć tego procesu do odświeżenia tokenu między sesjami, a nie buforowania istniejącego tokenu (ponieważ ten token może w dowolnym momencie wygasnąć).

Uwaga / Notatka

Powyższy przykład obejmuje tylko podstawowe przypadki powodzenia i niepowodzenia. Aplikacja powinna również uwzględniać nietypowe scenariusze (takie jak użytkownik, który odwołuje uprawnienia aplikacji lub usuwa swoje konto z systemu Windows) i obsłuży je bezpiecznie.

Usuwanie przechowywanego konta

Jeśli utrwalisz konto internetowe, możesz dać swoim użytkownikom możliwość usunięcia skojarzenia konta z twoją aplikacją. Dzięki temu mogą skutecznie "wylogować się" z aplikacji: informacje o koncie nie będą już ładowane automatycznie po uruchomieniu. Aby to zrobić, najpierw usuń zapisane dane o koncie i dostawcy z przechowywania. Następnie wywołaj metodę SignOutAsync , aby wyczyścić pamięć podręczną i unieważnić wszystkie istniejące tokeny, które mogła mieć aplikacja.

private async Task SignOutAccountAsync(WebAccount account)
{
	ApplicationData.Current.LocalSettings.Values.Remove("CurrentUserProviderId");
	ApplicationData.Current.LocalSettings.Values.Remove("CurrentUserId"); 
	account.SignOutAsync(); 
}

Dodawanie dostawców, którzy nie obsługują składnika WebAccountManager

Jeśli chcesz zintegrować uwierzytelnianie z usługi z aplikacją, ale ta usługa, na przykład Google+ lub Twitter, nie obsługuje elementu WebAccountManager, nadal możesz ręcznie dodać tego dostawcę do AccountsSettingsPane. W tym celu utwórz nowy obiekt WebAccountProvider i podaj własną nazwę i .png ikonę, a następnie dodaj go do listy WebAccountProviderCommands. Oto kod wycinkowy:

private async void BuildPaneAsync(AccountsSettingsPane s, AccountsSettingsPaneCommandsRequestedEventArgs e)
{
	// other code here 

	var twitterProvider = new WebAccountProvider("twitter", "Twitter", new Uri(@"ms-appx:///Assets/twitter-auth-icon.png")); 
	var twitterCmd = new WebAccountProviderCommand(twitterProvider, GetTwitterTokenAsync);
	e.WebAccountProviderCommands.Add(twitterCmd);	
	
	// other code here
}

private async void GetTwitterTokenAsync(WebAccountProviderCommand command)
{
	// Manually handle Twitter login here
}

Uwaga / Notatka

Spowoduje to dodanie ikony tylko do elementu AccountsSettingsPane i uruchomienie metody określonej po kliknięciu ikony (GetTwitterTokenAsync w tym przypadku). Musisz podać kod, który obsługuje rzeczywiste uwierzytelnianie. Aby uzyskać więcej informacji, zobacz Internetowy broker uwierzytelniania, który udostępnia metody pomocnicze do uwierzytelniania przy użyciu usług REST.

Dodawanie nagłówka niestandardowego

Okienko ustawień konta można dostosować przy użyciu właściwości HeaderText, w następujący sposób:

private async void BuildPaneAsync(AccountsSettingsPane s, AccountsSettingsPaneCommandsRequestedEventArgs e)
{
	// other code here 
	
	args.HeaderText = "MyAwesomeApp works best if you're signed in."; 	
	
	// other code here
}

Zrzut ekranu przedstawiający okno Wybieranie konta, w którym nie ma wymienionych kont i komunikat mówiący, że Moja niesamowita aplikacja działa najlepiej, gdy jesteś zalogowany.

Nie przesadzaj z tekstem nagłówka; zachowaj go krótkim i przyjemnym. Jeśli proces logowania jest skomplikowany i musisz wyświetlić więcej informacji, połącz użytkownika z oddzielną stroną przy użyciu linku niestandardowego.

Możesz dodać polecenia niestandardowe do panelu AccountsSettingsPane, które są wyświetlane jako linki poniżej obsługiwanych dostawców WebAccountProviders. Polecenia niestandardowe doskonale nadają się do prostych zadań związanych z kontami użytkowników, takich jak wyświetlanie zasad ochrony prywatności lub uruchamianie strony pomocy technicznej dla użytkowników, którzy mają problemy.

Oto przykład:

private async void BuildPaneAsync(AccountsSettingsPane s, AccountsSettingsPaneCommandsRequestedEventArgs e)
{
	// other code here 
	
	var settingsCmd = new SettingsCommand(
		"settings_privacy", 
		"Privacy policy", 
		async (x) => await Launcher.LaunchUriAsync(new Uri(@"https://privacy.microsoft.com/en-US/"))); 

	e.Commands.Add(settingsCmd); 
	
	// other code here
}

Zrzut ekranu przedstawiający okno Wybierz konto bez kont wymienionych i link do polityki prywatności.

Teoretycznie możesz użyć poleceń ustawień dla dowolnego elementu. Sugerujemy jednak ograniczenie ich użycia do intuicyjnych scenariuszy związanych z kontem, takich jak opisane powyżej.

Zobacz także

Windows.Security.Authentication.Web.Core przestrzeń nazw

przestrzeni nazw Windows.Security.Credentials

AccountsSettingsPane, klasy

Broker uwierzytelniania sieci Web

Przykład zarządzania kontami internetowymi

aplikacja Lunch Scheduler