Sdílet prostřednictvím

Správce webových účtů

Tento článek popisuje, jak pomocí AccountsSettingsPane připojit aplikaci pro Universal Windows Platform (UWP) k externím poskytovatelům identity, jako je Microsoft nebo Facebook, pomocí rozhraní API Správce webových účtů systému Windows. 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 v sadě Visual Studio vytvořte novou prázdnou aplikaci pro UPW.

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="SignInButton" Content="Sign in" Click="SignInButton_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 SignInButton_Click(object sender, RoutedEventArgs e)
{	
}

Nakonec přidejte následující obory názvů, abyste se nemuseli starat o žádné problémy s kompilací 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 SignInButton_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 místo show použít ShowAddAccountAsync, který vrátí IAsyncAction, dotaz na stav operace.

Zaregistrujte se pro AccountCommandsRequested

Abychom přidali příkazy do podokna, začínáme 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 "code-behind" 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 existuje velká šance, že ho uživatel požádá (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 Microsoft Entra 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 rovněž předáme řetězec "consumers" volitelnému parametru autority. Důvodem je to, že Microsoft poskytuje dva různé typy ověřování – účty Microsoft (MSA) pro "uživatele" a Microsoft Entra 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 GetMsaTokenAsync , kterou jsme předali do 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 naši metodu GetMsaTokenAsync , která se aktivuje, když se uživatel rozhodne přihlásit pomocí úč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.

Návod

Pokud vaše aplikace používá nápovědu pro 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, můžete ji volitelně vypsat 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 Microsoft Entra 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);
}

Zbytek tohoto článku popisuje scénář MSA, ale kód pro Microsoft Entra je velmi podobný. Další informace o Entra/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 365 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)
{
	var 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 k ukládání uživatelských dat najdete v tématu Store a načtení nastavení a dat aplikace.

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ým 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);

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

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

private async void SignInButton_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 – Instagram nebo X/Twitter, můžete ho například přidat ručně do podokna AccountsSettingsPane. Uděláte to tak, že vytvoříte nový objekt WebAccountProvider a zadáte vlastní název a ikonu .png a pak ho přidáte do seznamu WebAccountProviderCommands . Tady je nějaký překryvný 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 sign-in 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 váš přihlašovací proces složitý a potřebujete zobrazit další informace, připojte uživatele k samostatné stránce pomocí vlastního odkazu.

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.

Související obsah

zprostředkovatel webové autentikace

Ukázka správy webových účtů

Aplikace Plánovač obědů

  • Last updated on