Webaccountbeheer

In dit artikel wordt beschreven hoe u de AccountsSettingsPane gebruikt om uw UWP-app (Universal Windows Platform) te verbinden met externe id-providers, zoals Microsoft of Facebook, met behulp van de Windows Web Account Manager-API's. U leert hoe u de machtiging van een gebruiker kunt aanvragen om hun Microsoft-account te gebruiken, een toegangstoken te verkrijgen en dit te gebruiken om basisbewerkingen uit te voeren (zoals profielgegevens ophalen of bestanden uploaden naar hun OneDrive-account). De stappen zijn vergelijkbaar voor het verkrijgen van gebruikersmachtigingen en -toegang met elke id-provider die ondersteuning biedt voor webaccountbeheer.

Aan de slag gaan

Maak eerst een nieuwe, lege UWP-app in Visual Studio.

Ten tweede moet u uw app koppelen aan de Store om verbinding te maken met id-providers. Klik hiervoor met de rechtermuisknop op uw project, kies Store/Publish>App koppelen aan de Storeen volg de instructies van de wizard.

Maak ten derde een zeer eenvoudige gebruikersinterface die bestaat uit een eenvoudige XAML-knop en twee tekstvakken.

<StackPanel HorizontalAlignment="Center" VerticalAlignment="Center">
	<Button x:Name="SignInButton" Content="Sign in" Click="SignInButton_Click" />
	<TextBlock x:Name="UserIdTextBlock"/>
	<TextBlock x:Name="UserNameTextBlock"/>
</StackPanel>

Daarnaast een "event handler" die is gekoppeld aan uw knop in de "code-behind":

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

Voeg ten slotte de volgende naamruimten toe, zodat u zich later geen zorgen hoeft te maken over compilatieproblemen:

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;

Het deelvenster voor de accountinstellingen weergeven

Het systeem biedt een ingebouwde gebruikersinterface voor het beheren van id-providers en webaccounts met de naam AccountsSettingsPane. U kunt deze als volgt weergeven:

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

Als u uw app uitvoert en op de knop Aanmelden klikt, wordt er een leeg venster weergegeven.

Het deelvenster is leeg omdat het systeem alleen een UI-shell biedt. Het is aan de ontwikkelaar om het deelvenster programmatisch te vullen met de id-providers.

Registratie voor AccountCommandsRequested

Om opdrachten aan het deelvenster toe te voegen, beginnen we met registreren voor de event handler AccountCommandsRequested. Dit vertelt het systeem om onze buildlogica uit te voeren wanneer de gebruiker vraagt om het deelvenster weer te geven (bijvoorbeeld wanneer de gebruiker op de XAML-knop klikt).

Overschrijf in uw achtergrondcode de events OnNavigatedTo en OnNavigatedFrom en voeg de volgende code eraan toe:

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

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

Gebruikers werken niet vaak met accounts, dus het registreren en uitschrijven van uw event handler op deze manier helpt geheugenlekken te voorkomen. Op deze manier bevindt het aangepaste deelvenster zich alleen in het geheugen wanneer een gebruiker er veel om vraagt (omdat deze zich bijvoorbeeld op een 'instellingen' of 'aanmeldingspagina' bevindt).

Het accountinstellingenpaneel bouwen

De methode BuildPaneAsync wordt aangeroepen wanneer de AccountsSettingsPane wordt weergegeven. Hier plaatsen we de code om de opdrachten in het deelvenster aan te passen.

Begin met het verkrijgen van een uitstel. Dit geeft aan dat het systeem het weergeven van de AccountsSettingsPane moet vertragen totdat het is voltooid.

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

Haal vervolgens een provider op met behulp van de methode WebAuthenticationCoreManager.FindAccountProviderAsync . De URL voor de provider varieert op basis van de provider en vindt u in de documentatie van de provider. Voor Microsoft-accounts en Microsoft Entra is het '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(); 
}

Houd er rekening mee dat we ook de string 'consumenten' doorgeven aan de optionele authority parameter. Dit komt doordat Microsoft twee verschillende typen verificatie biedt: Microsoft-accounts (MSA) voor 'consumenten' en Microsoft Entra voor 'organisaties'. De autoriteit "consumentenzaken" wijst erop dat we de MSA-optie willen. Als u een bedrijfs-app ontwikkelt, gebruik dan 'organisaties' als string.

Voeg tot slot de provider toe aan de AccountsSettingsPane- door een nieuwe WebAccountProviderCommand- als volgt te maken:

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

De GetMsaTokenAsync-methode die we hebben doorgegeven aan onze nieuwe WebAccountProviderCommand , bestaat nog niet (we gaan dat in de volgende stap bouwen), dus u kunt deze voorlopig toevoegen als een lege methode.

Voer de bovenstaande code uit en uw deelvenster ziet er ongeveer als volgt uit:

Een token aanvragen

Zodra de optie Microsoft-account wordt weergegeven in de AccountsSettingsPane-, moeten we afhandelen wat er gebeurt wanneer de gebruiker deze selecteert. We hebben onze GetMsaTokenAsync-methode geregistreerd om te worden geactiveerd wanneer de gebruiker ervoor kiest zich aan te melden met zijn Of Haar Microsoft-account, dus we verkrijgen het token daar.

Als u een token wilt verkrijgen, gebruikt u de methode RequestTokenAsync als volgt:

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

In dit voorbeeld geven we de tekenreeks "wl.basic" door aan de scopeparameter. Scope vertegenwoordigt het type informatie dat u opvraagt bij de dienstverlener voor een specifieke gebruiker. Bepaalde scopes bieden alleen toegang tot de basisgegevens van een gebruiker, zoals naam en e-mailadres, terwijl andere scopes toegang kunnen verlenen tot gevoelige informatie, zoals de foto's van de gebruiker of de e-mailinbox van de gebruiker. Over het algemeen moet uw app het minst permissieve bereik gebruiken dat nodig is om zijn functie te vervullen. Service providers bieden documentatie over welke toepassingsgebieden nodig zijn om tokens op te halen voor gebruik met hun diensten.

• Zie voor Microsoft 365- en Outlook.com-scopes De Outlook REST API (versie 2.0) gebruiken.
• Zie OneDrive-verificatie en -aanmeldingvoor OneDrive-bereiken.

Als u een bedrijfs-app ontwikkelt, wilt u waarschijnlijk verbinding maken met een Microsoft Entra-exemplaar en de Microsoft Graph API gebruiken in plaats van reguliere MSA-services. Gebruik in dit scenario in plaats daarvan de volgende code:

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

In de rest van dit artikel wordt het MSA-scenario beschreven, maar de code voor Microsoft Entra is vergelijkbaar. Zie de Microsoft Graph-documentatie voor meer informatie over Entra/Graph, inclusief een volledig voorbeeld op GitHub.

Het token gebruiken

De methode RequestTokenAsync retourneert een WebTokenRequestResult-object dat de resultaten van uw aanvraag bevat. Als uw aanvraag is geslaagd, bevat deze een 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; 
	}
}

Zodra u een token hebt, kunt u dit gebruiken om de API van uw provider aan te roepen. In de onderstaande code roepen we de microsoft 365-API voor gebruikersgegevens aan om basisinformatie over de gebruiker te verkrijgen en weer te geven in onze gebruikersinterface. Houd er echter rekening mee dat het in de meeste gevallen wordt aanbevolen om het token op te slaan zodra het is verkregen en vervolgens in een afzonderlijke methode te gebruiken.

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

Hoe u verschillende REST API's aanroept, verschilt per provider; raadpleeg de API-documentatie van de provider voor informatie over het gebruik van uw token.

Het account opslaan voor toekomstig gebruik

Tokens zijn handig voor het onmiddellijk verkrijgen van informatie over een gebruiker, maar ze hebben meestal verschillende levensduur- MSA-tokens zijn bijvoorbeeld slechts enkele uren geldig. Gelukkig hoeft u de AccountsSettingsPane- niet telkens opnieuw weer te geven wanneer een token verloopt. Zodra een gebruiker uw app eenmaal heeft geautoriseerd, kunt u de accountgegevens van de gebruiker opslaan voor toekomstig gebruik.

Gebruik hiervoor de klasse WebAccount . Een WebAccount- wordt geretourneerd door dezelfde methode die u hebt gebruikt om het token aan te vragen:

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

Zodra u een WebAccount-exemplaar hebt, kunt u deze eenvoudig opslaan. In het volgende voorbeeld gebruiken we LocalSettings. Zie App-instellingen en -gegevens opslaan en ophalen voor meer informatie over het gebruik van LocalSettings en andere methoden voor het opslaan van gebruikersgegevens.

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

Vervolgens kunnen we een asynchrone methode gebruiken, zoals de onderstaande, om op de achtergrond een token te verkrijgen met het opgeslagen 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; 
	}
}

Plaats de vorige methode vlak voor de code waarmee de AccountsSettingsPane wordt gebouwd. Als het token op de achtergrond wordt verkregen, hoeft u het deelvenster niet weer te geven.

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

Omdat het verkrijgen van een token op de achtergrond heel eenvoudig is, moet u dit proces gebruiken om uw token te vernieuwen tussen sessies in plaats van een bestaand token in de cache op te slaan (omdat dat token op elk gewenst moment kan verlopen).

Een opgeslagen account verwijderen

Als u een webaccount behoudt, wilt u uw gebruikers mogelijk de mogelijkheid geven hun account los te koppelen aan uw app. Op deze manier kunnen ze zich effectief afmelden bij de app: hun accountgegevens worden niet meer automatisch geladen bij het starten. Hiervoor verwijdert u eerst alle opgeslagen account- en providergegevens uit de opslag. Roep Vervolgens SignOutAsync aan om de cache te wissen en bestaande tokens die uw app mogelijk heeft ongeldig te maken.

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

Providers toevoegen die WebAccountManager niet ondersteunen

Als u verificatie van een service in uw app wilt integreren, maar die service bijvoorbeeld geen ondersteuning biedt voor WebAccountManager - Instagram of X/Twitter, kunt u die provider nog steeds handmatig toevoegen aan de AccountsSettingsPane. Hiervoor maakt u een nieuw WebAccountProvider-object en geeft u uw eigen naam en .png pictogram op en voegt u dit toe aan de lijst WebAccountProviderCommands . Hier volgt wat gestubde code:

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
}

Een aangepaste koptekst toevoegen

U kunt het deelvenster accountinstellingen aanpassen met behulp van de eigenschap HeaderText , zoals deze:

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

Ga niet overboord met koptekst; hou het kort en lief. Als uw aanmeldingsproces ingewikkeld is en u meer informatie moet weergeven, koppelt u de gebruiker aan een afzonderlijke pagina met behulp van een aangepaste koppeling.

Aangepaste koppelingen toevoegen

U kunt aangepaste opdrachten toevoegen aan de AccountsSettingsPane, die worden weergegeven als koppelingen onder uw ondersteunde WebAccountProviders. Aangepaste opdrachten zijn ideaal voor eenvoudige taken met betrekking tot gebruikersaccounts, zoals het weergeven van een privacybeleid of het starten van een ondersteuningspagina voor gebruikers die problemen ondervinden.

Hier is een voorbeeld:

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
}

Theoretisch kunt u instellingenopdrachten voor alles gebruiken. We raden echter aan het gebruik te beperken tot intuïtieve, accountgerelateerde scenario's zoals hierboven beschreven.

Verwante inhoud

Webverificatie-makelaar

voorbeeld van webaccountbeheer

Lunch Scheduler-app