Web Hesabı Yöneticisi

Bu makalede, Windows Web Hesabı Yöneticisi API'lerini kullanarak Evrensel Windows Platformu (UWP) uygulamanızı Microsoft veya Facebook gibi dış kimlik sağlayıcılarına bağlamak için AccountsSettingsPane'ın nasıl kullanılacağı açıklanmaktadır. Kullanıcının Microsoft hesabını kullanma iznini isteme, erişim belirteci alma ve bunu kullanarak temel işlemleri (profil verilerini alma veya OneDrive hesabına dosya yükleme gibi) gerçekleştirmeyi öğreneceksiniz. Adımlar, Web Hesabı Yöneticisi'ni destekleyen herhangi bir kimlik sağlayıcısıyla kullanıcı izni ve erişimi almaya benzer.

Uyarı

Eksiksiz bir kod örneği için githubWebAccountManagement örneğine bakın.

Kurulumu yap

İlk olarak Visual Studio'da yeni, boş bir UWP uygulaması oluşturun.

İkincisi, kimlik sağlayıcılarına bağlanmak için uygulamanızı Mağaza ile ilişkilendirmeniz gerekir. Bunu yapmak için projenize sağ tıklayın, Store/Publish>Uygulamayı mağazailişkilendir'i seçin ve sihirbazın yönergelerini izleyin.

Üçüncüsü, basit bir XAML düğmesi ve iki metin kutusu içeren çok temel bir kullanıcı arabirimi oluşturun.

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

Kodun arka planında bulunan düğmenize eklenmiş bir olay işleyicisi de:

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

Son olarak, aşağıdaki ad alanlarını ekleyerek daha sonra derleme sorunları konusunda endişelenmenize gerek kalmaz:

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;

Hesaplar ayarları bölmesini gösterme

Sistem, AccountsSettingsPaneadlı kimlik sağlayıcılarını ve web hesaplarını yönetmek için yerleşik bir kullanıcı arabirimi sağlar. Bunu şu şekilde gösterebilirsiniz:

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

Uygulamanızı çalıştırır ve "Oturum aç" düğmesine tıklarsanız boş bir pencere görüntülenir.

Sistem yalnızca kullanıcı arabirimi kabuğu sağladığından bölme boş. Bölmeyi program aracılığıyla kimlik sağlayıcılarıyla doldurmak geliştiriciye kalmış.

Tavsiye

İsteğe bağlı olarak, Show yerine ShowAddAccountAsync kullanabilirsiniz, bu da işlemin durumunu sorgulamak için bir IAsyncAction döndürecektir.

AccountCommandsRequested için kaydolun

Bölmeye komut eklemek için AccountCommandsRequested olay işleyicisine kaydolarak başlayacağız. Bu, kullanıcı bölmeyi görmek istediğinde sisteme derleme mantığımızı çalıştırmasını söyler (örneğin, XAML düğmemize tıklar).

Arkasındaki kodunuzda OnNavigatedTo ve OnNavigatedFrom olaylarını geçersiz kılın ve bunlara aşağıdaki kodu ekleyin:

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

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

Kullanıcılar hesaplarla çok sık etkileşim kurmaz, bu nedenle olay işleyicinizi bu şekilde kaydetmek ve kaydını silmek bellek sızıntılarını önlemeye yardımcı olur. Bu şekilde, özelleştirilmiş bölmeniz yalnızca kullanıcının bunu isteme olasılığı yüksek olduğunda bellekte olur (örneğin, bir "ayarlar" veya "oturum açma" sayfasında olduğundan).

Hesap ayarları bölmesini oluşturma

AccountsSettingsPane her gösterildiğinde BuildPaneAsync yöntemi çağrılır. Burada bölmede gösterilen komutları özelleştirmek için kodu yerleştireceğiz.

Erteleme elde ederek başlayın. Bu, sistemi AccountsSettingsPane’i oluşturmayı tamamlayana kadar göstermeyi ertelemeye ayarlar.

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

Ardından , WebAuthenticationCoreManager.FindAccountProviderAsync yöntemini kullanarak bir sağlayıcı alın. Sağlayıcının URL'si sağlayıcıya göre değişir ve sağlayıcının belgelerinde bulunabilir. Microsoft Hesapları ve Microsoft Entra için "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(); 
}

"consumers" dizesini isteğe bağlı authority parametresine de geçirebileceğimizi unutmayın. Bunun nedeni, Microsoft'un "tüketiciler" için Microsoft Hesapları (MSA) ve "kuruluşlar" için Microsoft Entra olmak üzere iki farklı kimlik doğrulaması türü sağlamasıdır. "Tüketiciler" yetkilisi MSA seçeneğini istediğimizi gösterir. Kurumsal bir uygulama geliştiriyorsanız bunun yerine "kuruluşlar" dizesini kullanın.

Son olarak, aşağıdaki gibi yeni bir WebAccountProviderCommand oluşturarak sağlayıcıyı AccountsSettingsPane ekleyin:

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

Yeni WebAccountProviderCommand'ımıza iletmiş olduğumuz GetMsaTokenAsync yöntemi henüz mevcut değil (bunu sonraki adımda oluşturacağız), bu nedenle şimdilik bunu boş bir yöntem olarak ekleyebilirsiniz.

Yukarıdaki kodu çalıştırdığınızda bölmeniz şöyle görünmelidir:

Jeton talep et

HesaplarAyarlarPenceresi'de Microsoft Hesabı seçeneğinin görüntülenmesini sağladıktan sonra, kullanıcı bunu seçtiğinde ne olacağını ele almamız gerekir. Kullanıcı Microsoft Hesaplarıyla oturum açmayı seçtiğinde tetiklenmesini sağlamak için GetMsaTokenAsync yöntemimizi kaydettik, dolayısıyla belirteci oradan alacağız.

Belirteç almak için RequestTokenAsync yöntemini şu şekilde kullanın:

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

Bu örnekte, "wl.basic" dizesini kapsam parametresine geçireceğiz. Kapsam, belirli bir kullanıcı üzerinde sağlama hizmetinden istediğiniz bilgi türünü temsil eder. Bazı kapsamlar yalnızca kullanıcının ad ve e-posta adresi gibi temel bilgilerine erişim sağlarken, diğer kapsamlar kullanıcının fotoğrafları veya e-posta gelen kutusu gibi hassas bilgilere erişim izni verebilir. Genellikle uygulamanız işlevini gerçekleştirmek için gereken en az izinli kapsamı kullanmalıdır. Hizmet sağlayıcıları, hizmetleriyle kullanılacak belirteçleri almak için hangi kapsamların gerekli olduğu hakkında belgeler sağlar.

• Microsoft 365 ve Outlook.com kapsamları için bkz. Outlook REST API'sini (sürüm 2.0) kullanma.
• OneDrive kapsamları için bkz. OneDrive kimlik doğrulaması ve oturum açma.

Tavsiye

Uygulamanız oturum açma deneyimiyle ilgili bir oturum açma ipucu (kullanıcı alanını varsayılan e-posta adresiyle doldurmak için) veya başka bir özel özellik kullanıyorsa, bunu isteğe bağlı olarak WebTokenRequest.AppProperties özelliğinde listeleyebilirsiniz. Bu durum, sistemin web hesabını önbelleğe alırken özelliği yoksaymasına ve böylece önbellekteki hesap uyuşmazlıklarını önlemesine neden olur.

Kurumsal bir uygulama geliştiriyorsanız, büyük olasılıkla bir Microsoft Entra örneğine bağlanmak ve normal MSA hizmetleri yerine Microsoft Graph API'sini kullanmak istersiniz. Bu senaryoda, bunun yerine aşağıdaki kodu kullanın:

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

Bu makalenin geri kalanında MSA senaryosu açıklanmaktadır, ancak Microsoft Entra kodu çok benzerdir. GitHub'da tam örnek de dahil olmak üzere Entra/Graph hakkında daha fazla bilgi için Microsoft Graph belgelerine bakın.

Belirteci kullan

RequestTokenAsync yöntemi, isteğinizin sonuçlarını içeren bir WebTokenRequestResult nesnesi döndürür. İsteğiniz başarılı olursa bir belirteç içerir.

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

Uyarı

Belirteç isteğinde bulunurken hata alırsanız uygulamanızı birinci adımda açıklandığı gibi Mağaza ile ilişkilendirdiğinizden emin olun. Bu adımı atlarsanız, uygulamanız bir belirteç edinemez.

Belirteci aldıktan sonra, sağlayıcınızın API'sini çağırmak için bu belirteci kullanabilirsiniz. Aşağıdaki kodda kullanıcı hakkındaki temel bilgileri almak ve kullanıcı arabirimimizde görüntülemek için kullanıcı bilgilerini Microsoft 365 API'sini çağıracağız. Ancak, çoğu durumda belirteci bir kez edindikten sonra depolamanız ve ardından ayrı bir yöntemde kullanmanız önerilir.

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

Çeşitli REST API'lerini çağırma yönteminiz sağlayıcılar arasında farklılık gösterir; Belirtecinizi kullanma hakkında bilgi için sağlayıcının API belgelerine bakın.

Hesabı gelecekte kullanmak üzere depolama

Belirteçler, bir kullanıcı hakkında hemen bilgi almak için kullanışlıdır, ancak genellikle değişen kullanım ömrüne sahiptir. Örneğin, MSA belirteçleri yalnızca birkaç saat geçerlidir. Neyse ki, bir jetonun süresi dolduğunda AccountsSettingsPane'i yeniden göstermezsiniz. Bir kullanıcı uygulamanızı bir kez yetkilendirdikten sonra, kullanıcının hesap bilgilerini gelecekte kullanmak üzere depolayabilirsiniz.

Bunu yapmak için WebAccount sınıfını kullanın. WebAccount, belirteci istemek için kullandığınız yöntemle döndürülür:

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

WebAccount örneğiniz olduğunda, kolayca depolayabilirsiniz. Aşağıdaki örnekte LocalSettings kullanıyoruz. Kullanıcı verilerini depolamak için LocalSettings ve diğer yöntemleri kullanma hakkında daha fazla bilgi için bkz. Uygulama ayarlarını ve verilerini depolama ve alma.

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

Ardından, depolanan WebAccount ile arka planda bir belirteç elde etmeye çalışmak için aşağıdaki gibi zaman uyumsuz bir metot kullanabiliriz.

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

Önceki yöntemi AccountsSettingsPane'ı oluşturan kodun hemen önüne yerleştirin. Belirteç arka planda elde edilirse bölmeyi göstermeye gerek yoktur.

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

Belirteci sessizce almak çok basit olduğundan, mevcut bir belirteci önbelleğe almak yerine oturumlar arasında belirtecinizi yenilemek için bu işlemi kullanmanız gerekir (bu belirtecin süresi herhangi bir zamanda dolabileceği için).

Uyarı

Yukarıdaki örnek yalnızca temel başarı ve başarısızlık durumlarını kapsar. Uygulamanızın ayrıca olağan dışı senaryoları (örneğin, uygulamanızın iznini iptal eden veya hesabını Windows'tan kaldıran bir kullanıcı gibi) hesaba eklemesi ve bunları düzgün bir şekilde işlemesi gerekir.

Depolanan hesabı kaldırma

Bir web hesabına sahipseniz, kullanıcılarınıza kendi hesaplarıyla uygulamanızın bağlantısını kesme olanağı vermek isteyebilirsiniz. Bu şekilde, uygulamadan etkili biçimde oturum kapatabilirler; hesap bilgileri artık başlatıldığında otomatik olarak yüklenmeyecektir. Bunu yapmak için önce kaydedilen hesap ve sağlayıcı bilgilerini depolama alanından kaldırın. Ardından signOutAsync'i çağırarak önbelleği temizleyin ve uygulamanızın sahip olabileceği mevcut belirteçleri geçersiz kılın.

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

WebAccountManager'ı desteklemeyen sağlayıcılar ekleme

Bir hizmetten gelen kimlik doğrulamasını uygulamanızla tümleştirmek istiyorsanız ancak bu hizmet WebAccountManager'ı desteklemiyorsa (örneğin, Instagram veya X/Twitter) yine de bu sağlayıcıyı AccountsSettingsPane'a el ile ekleyebilirsiniz. Bunu yapmak için yeni bir WebAccountProvider nesnesi oluşturun ve kendi adınızı ve .png simgenizi sağlayın ve webAccountProviderCommands listesine ekleyin. İşte bazı saplamalı kodlar:

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
}

Uyarı

Bu yalnızca AccountsSettingsPane'a bir simge ekler ve simge tıklatıldığında belirttiğiniz yöntemi çalıştırır (Bu durumda GetTwitterTokenAsync). Gerçek kimlik doğrulamasını işleyen kodu sağlamanız gerekir. Daha fazla bilgi için bkz. REST hizmetlerini kullanarak kimlik doğrulaması için yardımcı yöntemler sağlayanWeb kimlik doğrulama aracısı.

Özel bir üst bilgi ekleyin

HeaderText özelliğini kullanarak hesap ayarları bölmesini şu şekilde özelleştirebilirsiniz:

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

Üst bilgi metniyle aşırıya gitmeyin; Kısa ve tatlı tut. Oturum açma işleminiz karmaşıksa ve daha fazla bilgi görüntülemeniz gerekiyorsa, özel bir bağlantı kullanarak kullanıcıyı ayrı bir sayfaya bağlayın.

Özel bağlantılar ekleme

Desteklenen WebAccountProviders'larınızın altında bağlantılar olarak görünen AccountsSettingsPane'a özel komutlar ekleyebilirsiniz. Özel komutlar, kullanıcı hesaplarıyla ilgili gizlilik ilkesi görüntüleme veya sorun yaşayan kullanıcılar için bir destek sayfası başlatma gibi basit görevler için mükemmeldir.

İşte bir örnek:

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
}

Teorik olarak, her şey için ayarlar komutlarını kullanabilirsiniz. Ancak, bunların kullanımını yukarıda açıklananlar gibi sezgisel, hesapla ilgili senaryolarla sınırlamanızı öneririz.

İlgili içerik

web kimlik doğrulama aracısı

Web hesabı yönetimi örneği

Lunch Scheduler uygulaması