Dela via

Webbkontohanterare

I den här artikeln beskrivs hur du använder AccountsSettingsPane- för att ansluta din UWP-app (Universal Windows Platform) till externa identitetsprovidrar, till exempel Microsoft eller Facebook, med hjälp av API:erna för Windows 10 och Windows 11 Web Account Manager. Du får lära dig hur du begär en användares behörighet att använda sitt Microsoft-konto, skaffar en åtkomsttoken och använder den för att utföra grundläggande åtgärder (till exempel hämta profildata eller ladda upp filer till deras OneDrive-konto). Stegen är liknande för att få användarbehörighet och åtkomst med alla identitetsprovider som stöder webbkontohanteraren.

Anmärkning

Ett fullständigt kodexempel finns i exemplet WebAccountManagement på GitHub.

Förbered dig

Skapa först en ny tom app i Visual Studio.

För det andra måste du associera din app med Store för att kunna ansluta till identitetsprovidrar. För att göra detta, högerklicka på projektet, välj Store/Publicera>Associera appen med butikenoch följ guidens instruktioner.

För det tredje skapar du ett mycket grundläggande användargränssnitt som består av en enkel XAML-knapp och två textrutor.

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

Och en händelsehanterare som är kopplad till knappen i koden bakom:

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

Slutligen lägger du till följande namnområden så att du inte behöver oroa dig för några referensproblem senare:

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;

Visa panelen för kontoinställningar

Systemet tillhandahåller ett inbyggt användargränssnitt för hantering av identitetsprovidrar och webbkonton som kallas AccountsSettingsPane. Du kan visa den så här:

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

Om du kör appen och klickar på knappen Logga in bör den visa ett tomt fönster.

Skärmbild av fönstret Välj ett konto utan konton i listan.

Fönstret är tomt eftersom systemet bara tillhandahåller ett gränssnittsgränssnitt – det är upp till utvecklaren att programmatiskt fylla i fönstret med identitetsprovidrar.

Tips/Råd

Du kan också använda ShowAddAccountAsync i stället för Visa, som returnerar en IAsyncActionför att kontrollera statusen för åtgärden.

Registrera dig för AccountCommandsRequested

Om du vill lägga till kommandon i fönstret börjar vi med att registrera oss för händelsehanteraren AccountCommandsRequested. Detta talar om för systemet att köra vår bygglogik när användaren ber om att få se fönstret (till exempel klickar på vår XAML-knapp).

I koden bakom åsidosätter du händelserna OnNavigatedTo och OnNavigatedFrom och lägger till följande kod i dem:

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

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

Användare interagerar inte med konton särskilt ofta, så att registrera och avregistrera händelsehanteraren på det här sättet hjälper till att förhindra minnesläckor. På så sätt finns ditt anpassade fönster bara i minnet när det finns en stor chans att en användare kommer att be om det (eftersom de är på en "inställningar" eller "inloggningssida", till exempel).

Bygg kontoinställningspanelen

Metoden BuildPaneAsync anropas när AccountsSettingsPane visas. Det är här vi placerar koden för att anpassa kommandona som visas i fönstret.

Börja med att hämta en uppskjutning. Detta talar om för systemet att fördröja visning av AccountsSettingsPane- tills vi är klara med att bygga den.

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

Hämta sedan en provider med metoden WebAuthenticationCoreManager.FindAccountProviderAsync. Url:en för providern varierar beroende på providern och finns i leverantörens dokumentation. För Microsoft-konton och Azure Active Directory är det "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(); 
}

Observera att vi också skickar strängen "konsumenter" till den valfria auktoritets parametern. Det beror på att Microsoft tillhandahåller två olika typer av autentisering – Microsoft-konton (MSA) för "konsumenter" och Azure Active Directory (AAD) för "organisationer". "Konsumentmyndigheten anger att vi vill ha alternativet MSA." Om du utvecklar en företagsapp använder du strängen "organisationer" i stället.

Lägg slutligen till providern i AccountsSettingsPane genom att skapa en ny WebAccountProviderCommand så här:

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

Metoden GetMsaToken som vi skickade till vår nya WebAccountProviderCommand finns inte ännu (vi skapar den i nästa steg), så lägg gärna till den som en tom metod för tillfället.

Kör koden ovan så bör fönstret se ut ungefär så här:

Skärmbild av fönstret Välj konto med listade konton.

Begära en token

När alternativet Microsoft-konto visas i AccountsSettingsPanemåste vi hantera vad som händer när användaren väljer det. Vi registrerade vår GetMsaToken-metod för att utlösa när användaren väljer att logga in med sitt Microsoft-konto, så vi hämtar token där.

Om du vill hämta en token använder du metoden RequestTokenAsync så här:

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

I det här exemplet skickar vi strängen "wl.basic" till omfångsparametern . Omfånget representerar den typ av information som du begär från den tillhandahållande tjänsten för en viss användare. Vissa omfång ger endast åtkomst till en användares grundläggande information, till exempel namn och e-postadress, medan andra omfång kan ge åtkomst till känslig information, till exempel användarens foton eller e-post inkorg. I allmänhet bör din app använda det minsta tillåtna omfång som krävs för att uppnå dess funktion. Tjänsteleverantörer tillhandahåller dokumentation om vilka omfång som behövs för att hämta token för användning med sina tjänster.

Tips/Råd

Om din app använder ett inloggningstips (för att fylla i användarfältet med en standard-e-postadress) eller annan särskild egenskap som är relaterad till inloggningsupplevelsen kan du också ange den i egenskapen WebTokenRequest.AppProperties. Detta gör att systemet ignorerar egenskapen när webbkontot cachelagras, vilket förhindrar kontofel i cacheminnet.

Om du utvecklar en företagsapp vill du förmodligen ansluta till en Azure Active Directory-instans (AAD) och använda Microsoft Graph API i stället för vanliga MSA-tjänster. I det här scenariot använder du följande kod i stället:

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

Resten av den här artikeln fortsätter att beskriva MSA-scenariot, men koden för AAD är mycket lik. Mer information om AAD/Graph, inklusive ett fullständigt exempel på GitHub, finns i Microsoft Graph-dokumentationen.

Använd token

Metoden RequestTokenAsync returnerar ett WebTokenRequestResult-objekt som innehåller resultatet av din begäran. Om din begäran lyckades innehåller den en 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; 
	}
}

Anmärkning

Om du får ett fel när du begär en token kontrollerar du att du har associerat din app med Store enligt beskrivningen i steg ett. Din app kan inte hämta en token om du hoppades över det här steget.

När du har en token kan du använda den för att anropa leverantörens API. I koden nedan anropar vi användarinfo från Microsoft Live API för att hämta grundläggande information om användaren och visa den i vårt användargränssnitt. Observera dock att det i de flesta fall rekommenderas att du lagrar token när den har hämtats och sedan använder den i en separat 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;
		}
	}
}

Hur du anropar olika REST-API:er varierar mellan leverantörer. Se leverantörens API-dokumentation för information om hur du använder din token.

Lagra kontot för framtida användning

Token är användbara för att omedelbart hämta information om en användare, men de har vanligtvis varierande livslängd – MSA-token är till exempel bara giltiga i några timmar. Som tur är behöver du inte visa AccountsSettingsPane varje gång en token upphör att gälla. När en användare har godkänt din app en gång kan du lagra användarens kontoinformation för framtida användning.

Det gör du genom att använda klassen WebAccount. En WebAccount- returneras med samma metod som du använde för att begära 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)
	{
		WebAccount account = result.ResponseData[0].WebAccount; 
	}
}

När du har en WebAccount- instans kan du enkelt lagra den. I följande exempel använder vi LocalSettings. Mer information om hur du använder LocalSettings och andra metoder för att lagra användardata finns i Lagra och hämta appinställningar och data.

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

Sedan kan vi använda en asynkron metod som den nedan för att försöka hämta en token i bakgrunden med den lagrade 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; 
	}
}

Placera metoden ovan precis före koden som skapar AccountsSettingsPane. Om token hämtas i bakgrunden behöver du inte visa rutan.

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

Eftersom det är mycket enkelt att hämta en token tyst bör du använda den här processen för att uppdatera din token mellan sessioner i stället för att cachelagra en befintlig token (eftersom den token kan upphöra att gälla när som helst).

Anmärkning

Exemplet ovan omfattar endast grundläggande lyckade och felfall. Din app bör också ta hänsyn till ovanliga scenarier (till exempel en användare som återkallar appens behörighet eller tar bort sitt konto från Windows) och hanterar dem på ett smidigt sätt.

Ta bort ett lagrat konto

Om du bevarar ett webbkonto kanske du vill ge användarna möjlighet att koppla bort sitt konto till din app. På så sätt kan de effektivt "logga ut" från appen: deras kontoinformation läses inte längre in automatiskt vid start. Det gör du genom att först ta bort all sparad konto- och providerinformation från lagringen. Anropa sedan SignOutAsync- för att rensa cacheminnet och ogiltigförklara eventuella befintliga token som din app kan ha.

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

Lägg till leverantörer som inte stöder WebAccountManager

Om du till exempel vill integrera autentisering från en tjänst i din app men tjänsten inte stöder WebAccountManager – Google+ eller Twitter – kan du fortfarande lägga till providern manuellt i AccountsSettingsPane. För att göra det skapar du ett nytt WebAccountProvider-objekt och anger ditt eget namn och .png-ikonen och lägger sedan till det i listan WebAccountProviderCommands. Här är lite stubkod:

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
}

Anmärkning

Detta lägger bara till en ikon i AccountsSettingsPane och kör den metod som du anger när ikonen klickas (GetTwitterTokenAsync, i det här fallet). Du måste ange den kod som hanterar den faktiska autentiseringen. Mer information finns i webautentiseringskoordinator, som tillhandahåller hjälpmetoder för autentisering med hjälp av REST-tjänster.

Lägga till en anpassad rubrik

Du kan anpassa fönstret kontoinställningar med egenskapen HeaderText, så här:

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

Skärmbild av fönstret Välj ett konto utan konton i listan och ett meddelande om att Min fantastiska app fungerar bäst om du är inloggad.

Gå inte överbord med rubriktext; hålla den kort och söt. Om inloggningsprocessen är komplicerad och du behöver visa mer information länkar du användaren till en separat sida med hjälp av en anpassad länk.

Du kan lägga till anpassade kommandon i AccountsSettingsPane, som visas som länkar under dina WebAccountProviders som stöds. Anpassade kommandon är bra för enkla uppgifter som rör användarkonton, som att visa en sekretesspolicy eller starta en supportsida för användare som har problem.

Här är ett exempel:

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
}

Skärmbild av fönstret Välj ett konto utan konton i listan och en länk till en sekretesspolicy.

Teoretiskt sett kan du använda inställningskommandon för vad som helst. Vi föreslår dock att de begränsas till intuitiva, kontorelaterade scenarier som de som beskrivs ovan.

Se även

Windows.Security.Authentication.Web.Core-namnområdet

Windows.Security.Credentials-namnområde

AccountsSettingsPane-klassen

webbaserad autentiseringsförmedlare

Exempel på hantering av webbkonton

Lunch Scheduler-app