Správce webových účtů

2025-06-10

Tento článek popisuje, jak pomocí accountSettingsPane připojit aplikaci Pro Univerzální platformu Windows (UPW) k externím zprostředkovatelům identity, jako je Microsoft nebo Facebook, pomocí rozhraní API správce webových účtů pro Windows 10 a Windows 11. Dozvíte se, jak požádat uživatele o oprávnění k používání svého účtu Microsoft, získání přístupového tokenu a jeho použití k provádění základních operací (například získání dat profilu nebo nahrání souborů do účtu OneDrivu). Postup je podobný získání uživatelského oprávnění a přístupu u libovolného zprostředkovatele identity, který podporuje správce webových účtů.

Poznámka:

Kompletní ukázku kódu najdete v ukázce WebAccountManagement na GitHubu.

Připravte se

Nejprve vytvořte novou prázdnou aplikaci v sadě Visual Studio.

Za druhé, abyste se mohli připojit k zprostředkovatelům identity, budete muset aplikaci přidružit ke Storu. Uděláte to tak, že kliknete pravým tlačítkem na projekt, zvolíte Store/Publish>Přidružit aplikaci keStoru a postupujte podle pokynů průvodce.

Za třetí vytvořte velmi základní uživatelské rozhraní skládající se z jednoduchého tlačítka XAML a dvou textových polí.

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

A obslužná rutina události připojená k tlačítku v kódu na pozadí:

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

Nakonec přidejte následující obory názvů, abyste se nemuseli starat o žádné referenční problémy později:

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;

Zobrazení podokna nastavení účtů

Systém poskytuje integrované uživatelské rozhraní pro správu zprostředkovatelů identit a webových účtů s názvem AccountsSettingsPane. Můžete ho zobrazit takto:

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

Pokud spustíte aplikaci a kliknete na tlačítko Přihlásit se, mělo by se zobrazit prázdné okno.

Snímek obrazovky okna pro výběr účtu, kde nejsou uvedeny žádné účty.

Podokno je prázdné, protože systém poskytuje pouze UI shell – je na vývojáři, aby programově naplnil podokno poskytovateli identity.

Návod

Volitelně můžete použít ShowAddAccountAsync místo Show, který vrátí IAsyncAction, pro zjištění stavu operace.

Zaregistrujte se pro AccountCommandsRequested

Pokud chcete do podokna přidat příkazy, začneme registrací obslužné rutiny události AccountCommandsRequested. To systému říká, aby spustil logiku sestavení, když uživatel požádá o zobrazení podokna (například klikne na tlačítko XAML).

V kódu pozadí přepište události OnNavigatedTo a OnNavigatedFrom a přidejte do nich následující kód:

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

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

Uživatelé s účty moc často nekomunikují, takže registrace a odregistrace obslužné rutiny událostí tímto způsobem pomáhá zabránit úniku paměti. Díky tomu je vaše přizpůsobené podokno v paměti jenom v případě, že si ho uživatel bude moct vyžádat (protože je například na stránce nastavení nebo přihlášení).

Vytvoření podokna nastavení účtu

Metoda BuildPaneAsync se volá vždy, když se zobrazí AccountsSettingsPane . Tady vložíme kód pro přizpůsobení příkazů zobrazených v podokně.

Začněte získáním odložení. Toto systému říká, aby odložil zobrazení AccountsSettingsPane, dokud ho nedokončíme.

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

Dále získejte zprostředkovatele pomocí metody WebAuthenticationCoreManager.FindAccountProviderAsync. Adresa URL poskytovatele se liší podle poskytovatele a najdete ji v dokumentaci poskytovatele. Pro účty Microsoft a Azure Active Directory je 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(); 
}

Všimněte si, že také předáme řetězec "spotřebitelé" volitelnému parametru autority. Důvodem je, že Microsoft poskytuje dva různé typy ověřování – účty Microsoft (MSA) pro uživatele a Azure Active Directory (AAD) pro "organizace". Autorita "spotřebitelů" naznačuje, že chceme zvolit možnost MSA. Pokud vyvíjíte podnikovou aplikaci, použijte místo toho řetězec "organizace".

Nakonec přidejte zprostředkovatele do AccountsSettingsPane vytvořením nového WebAccountProviderCommand takto:

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, kterou jsme předali do našeho nového WebAccountProviderCommand ještě neexistuje (vytvoříme ji v dalším kroku), takže ji prozatím přidejte jako prázdnou metodu.

Spusťte výše uvedený kód a podokno by mělo vypadat přibližně takto:

Snímek obrazovky s oknem Zvolit účet se seznamem účtů

Vyžádání tokenu

Jakmile je možnost "Účet Microsoft" zobrazená v AccountsSettingsPane, musíme zpracovat, co se stane, když ji uživatel vybere. Zaregistrovali jsme metodu GetMsaToken, která se aktivuje, když se uživatel rozhodne přihlásit pomocí svého účtu Microsoft, takže tam získáme token.

K získání tokenu použijte metodu RequestTokenAsync takto:

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

V tomto příkladě předáváme řetězec "wl.basic" jako parametr rozsahu . Obor představuje typ informací, které požadujete od poskytování služby pro konkrétního uživatele. Určité obory poskytují přístup jenom k základním informacím uživatele, jako je jméno a e-mailová adresa, zatímco jiné obory můžou udělovat přístup k citlivým informacím, jako jsou fotky uživatele nebo doručená pošta e-mailu. Obecně platí, že aplikace by měla k dosažení své funkce použít nejméně nezbytný rozsah. Poskytovatelé služeb poskytnou dokumentaci k rozsahům potřebným k získání tokenů pro použití se službami.

Obory Microsoftu 365 a Outlook.com najdete v tématu Použití rozhraní REST API Outlooku (verze 2.0).
Rozsahy OneDrivu najdete v tématu Ověřování a přihlášení OneDrivu.

Návod

Pokud vaše aplikace používá nápovědu k přihlášení (k naplnění pole uživatele výchozí e-mailovou adresou) nebo jinou speciální vlastnost související s přihlašovacím prostředím, uveďte ji ve vlastnosti WebTokenRequest.AppProperties . To způsobí, že systém při ukládání webového účtu do mezipaměti ignoruje vlastnost, což brání neshodám účtů v mezipaměti.

Pokud vyvíjíte podnikovou aplikaci, budete se pravděpodobně chtít připojit k instanci Azure Active Directory (AAD) a místo běžných služeb MSA používat rozhraní Microsoft Graph API. V tomto scénáři použijte místo toho následující kód:

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

Zbývající část tohoto článku pokračuje v popisu scénáře MSA, ale kód pro AAD je velmi podobný. Další informace o AAD/Graphu, včetně úplné ukázky na GitHubu, najdete v dokumentaci k Microsoft Graphu.

Použití tokenu

RequestTokenAsync metoda vrátí WebTokenRequestResult objekt, který obsahuje výsledky vašeho požadavku. Pokud vaše žádost proběhla úspěšně, bude obsahovat 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; 
	}
}

Poznámka:

Pokud se při vyžádání tokenu zobrazí chyba, ujistěte se, že jste aplikaci přidružili ke Storu, jak je popsáno v kroku 1. Pokud jste tento krok přeskočili, vaše aplikace nebude moct získat token.

Jakmile máte token, můžete ho použít k volání rozhraní API vašeho poskytovatele. V následujícím kódu zavoláme informace o uživateli, rozhraní Microsoft Live API, abychom získali základní informace o uživateli a zobrazili ho v našem uživatelském rozhraní. Všimněte si však, že ve většině případů doporučujeme, abyste token po získání uložili a pak ho použili v samostatné metodě.

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

Způsob volání různých rozhraní REST API se liší mezi poskytovateli; Informace o používání tokenu najdete v dokumentaci k rozhraní API poskytovatele.

Uložení účtu pro budoucí použití

Tokeny jsou užitečné pro okamžité získání informací o uživateli, ale obvykle mají různou životnost – tokeny MSA jsou například platné jenom na několik hodin. Naštěstí není nutné znovu zobrazovat AccountsSettingsPane pokaždé, když vyprší platnost tokenu. Jakmile uživatel aplikaci jednou autorizoval, můžete informace o účtu uživatele uložit pro budoucí použití.

K tomu použijte třídu WebAccount . WebAccount je vrácen stejnou metodou, jakou jste použili k vyžádání 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; 
	}
}

Jakmile máte instanci WebAccount , můžete ji snadno uložit. V následujícím příkladu používáme LocalSettings. Další informace o použití LocalSettings a dalších metodách k ukládání uživatelských dat naleznete v tématu Uložení a získání nastavení aplikace a dat.

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

Pak můžeme použít asynchronní metodu, jako je následující, abychom se pokusili získat token na pozadí s uloženými 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; 
	}
}

Výše uvedenou metodu umístěte těsně před kód, který sestaví AccountsSettingsPane. Pokud se token získá na pozadí, nemusí se podokno zobrazovat.

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

Vzhledem k tomu, že získání tokenu bezobslužně je velmi jednoduché, měli byste tento proces použít k aktualizaci tokenu mezi relacemi místo ukládání existujícího tokenu do mezipaměti (protože tento token může kdykoli vypršet).

Poznámka:

Výše uvedený příklad se týká pouze základních případů úspěchu a selhání. Vaše aplikace by měla také zohlednit neobvyklé scénáře (například odebrání oprávnění aplikace uživatelem nebo odebrání jejich účtu z Windows) a zpracovat je elegantně.

Odebrání uloženého účtu

Pokud si zachováte webový účet, můžete uživatelům dát možnost zrušit přidružení svého účtu k vaší aplikaci. Díky tomu se můžou aplikace efektivně odhlásit: informace o svém účtu se už při spuštění nenačtou automaticky. Uděláte to tak, že nejprve odeberete všechny uložené informace o účtu a poskytovateli z úložiště. Potom zavolejte SignOutAsync , aby se vymaže mezipaměť a zneplatní se všechny existující tokeny, které vaše aplikace mohla mít.

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

Přidání zprostředkovatelů, kteří nepodporují WebAccountManager

Pokud chcete integrovat ověřování ze služby do vaší aplikace, ale tato služba nepodporuje WebAccountManager – Google+ nebo Twitter, můžete ho například přidat do AccountsSettingsPane ručně. Uděláte to tak, že vytvoříte nový objekt WebAccountProvider a zadáte vlastní název a .png ikonu a pak ho přidáte do seznamu WebAccountProviderCommands. Tady je nějaký ukázkový kód:

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
}

Poznámka:

Tím se přidá ikona pouze do AccountsSettingsPane a spustí metodu, kterou zadáte při kliknutí na ikonu (GetTwitterTokenAsync, v tomto případě). Musíte zadat kód, který zpracovává skutečné ověřování. Další informace najdete v tématu zprostředkovatel webového ověřování, který poskytuje pomocné metody pro ověřování pomocí služeb REST.

Přidání vlastní hlavičky

Podokno nastavení účtu můžete přizpůsobit pomocí vlastnosti HeaderText, například takto:

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

cs-CZ: Snímek obrazovky okna

Nepřehánějte to s textem záhlaví; udržujte ho krátký a výstižný. Pokud je proces přihlášení složitý a potřebujete zobrazit další informace, propojte uživatele na samostatnou stránku pomocí vlastního odkazu.

Přidání vlastních odkazů

Vlastní příkazy můžete přidat do AccountsSettingsPane, které se zobrazí jako odkazy pod podporovanými webAccountProviders. Vlastní příkazy jsou skvělé pro jednoduché úlohy související s uživatelskými účty, jako je zobrazení zásad ochrany osobních údajů nebo spuštění stránky podpory pro uživatele, kteří mají potíže.

Tady je příklad:

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
}

Snímek obrazovky s oknem Zvolit účet bez uvedených účtů a odkazem na zásady ochrany osobních údajů

Teoreticky můžete použít příkazy nastavení pro cokoli. Doporučujeme ale omezit jejich použití na intuitivní scénáře související s účty, jako jsou ty popsané výše.