Xamarin.Essentials: Web Authenticator

Makale
03/05/2024

WebAuthenticator sınıfı, uygulamaya kayıtlı belirli bir URL'ye geri çağırmayı dinleyen tarayıcı tabanlı akışları başlatmanıza olanak tanır.

Genel bakış

Birçok uygulama için kullanıcı kimlik doğrulaması eklenmesi gerekir ve bu genellikle kullanıcılarınızın mevcut Microsoft, Facebook, Google ve şimdi Apple Oturum Açma hesaplarında oturum açmalarını sağlamak anlamına gelir.

Microsoft Authentication Library (MSAL), uygulamanıza kimlik doğrulaması eklemek için mükemmel bir anahtar teslim çözümü sağlar. İstemci NuGet paketinde Xamarin uygulamaları için destek bile vardır.

Kimlik doğrulaması için kendi web hizmetinizi kullanmak istiyorsanız, istemci tarafı işlevselliğini uygulamak için WebAuthenticator'ı kullanabilirsiniz.

Neden bir sunucu arka ucu kullanmalısınız?

Birçok kimlik doğrulama sağlayıcısı, daha iyi güvenlik sağlamak için yalnızca açık veya iki ayaklı kimlik doğrulama akışları sunmaya geçti. Bu, kimlik doğrulama akışını tamamlamak için sağlayıcıdan bir 'istemci gizli dizisine' ihtiyacınız olduğu anlamına gelir. Ne yazık ki, mobil uygulamalar gizli dizileri ve bir mobil uygulamanın kodunda, ikili dosyalarında depolanan herhangi bir şeyi depolamak için harika bir yer değildir veya genellikle güvenli olmadığı kabul edilir.

Burada en iyi yöntem, mobil uygulamanızla kimlik doğrulama sağlayıcısı arasında orta katman olarak bir web arka ucu kullanmaktır.

Önemli

İstemci gizli dizilerini depolamaya yönelik güvenlik eksikliği nedeniyle kimlik doğrulama akışında bir web arka ucu kullanmayan eski yalnızca mobil kimlik doğrulama kitaplıklarının ve desenlerinin kullanılmasını kesinlikle öneririz.

Kullanmaya başlayın

Bu API'yi kullanmaya başlamak için kitaplığın projelerinizde düzgün yüklendiğinden ve ayarlandığından emin olmak için Xamarin.Essentials kullanmaya başlama kılavuzunu okuyun.

WebAuthenticator işlevine erişmek için aşağıdaki platforma özgü kurulum gereklidir.

Android, geri çağırma URI'nizi işlemek için bir Amaç Filtresi kurulumu gerektirir. Bu, sınıfı alt sınıflandırılarak WebAuthenticatorCallbackActivity kolayca gerçekleştirilebilir:

const string CALLBACK_SCHEME = "myapp";

[Activity(NoHistory = true, LaunchMode = LaunchMode.SingleTop, Exported = true)]
[IntentFilter(new[] { Android.Content.Intent.ActionView },
    Categories = new[] { Android.Content.Intent.CategoryDefault, Android.Content.Intent.CategoryBrowsable },
    DataScheme = CALLBACK_SCHEME)]
public class WebAuthenticationCallbackActivity : Xamarin.Essentials.WebAuthenticatorCallbackActivity
{
}

Projenizin Hedef Android sürümü Android 11 (R API 30) olarak ayarlandıysa, Android Bildiriminizi yeni paket görünürlüğü gereksinimleriyle kullanılan sorgularla güncelleştirmeniz gerekir.

Özellikler klasörünün altındaki AndroidManifest.xml dosyasını açın ve bildirim düğümünün içine aşağıdakileri ekleyin:

<queries>
    <intent>
        <action android:name="android.support.customtabs.action.CustomTabsService" />
    </intent>
</queries>

iOS'ta, uygulamanızın geri çağırma URI'sini Info.plist'inize eklemeniz gerekir:

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLName</key>
        <string>xamarinessentials</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>xamarinessentials</string>
        </array>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
    </dict>
</array>

Ayrıca Essentials'a çağrı yapmak için ve OpenUrlContinueUserActivity yöntemlerinizi geçersiz kılmanız AppDelegategerekir:

public override bool OpenUrl(UIApplication app, NSUrl url, NSDictionary options)
{
    return Xamarin.Essentials.Platform.OpenUrl(app, url, options);
}

public override bool ContinueUserActivity(UIApplication application, NSUserActivity userActivity, UIApplicationRestorationHandler completionHandler)
{
    if (Xamarin.Essentials.Platform.ContinueUserActivity(application, userActivity, completionHandler))
        return true;
    return base.ContinueUserActivity(application, userActivity, completionHandler);
}

UWP için, dosyanızda geri çağırma URI'nizi bildirmeniz Package.appxmanifest gerekir:

<Applications>
    <Application Id="App" Executable="$targetnametoken$.exe" EntryPoint="MyApp.App">
        <Extensions>
            <uap:Extension Category="windows.protocol">
            <uap:Protocol Name="myapp">
                <uap:DisplayName>My App</uap:DisplayName>
            </uap:Protocol>
            </uap:Extension>
        </Extensions>
    </Application>
</Applications>

WebAuthenticator kullanma

Sınıfınızda için Xamarin.Essentials bir başvuru ekleyin:

using Xamarin.Essentials;

API temelde iki parametre alan tek bir yöntemden AuthenticateAsync oluşur: Web tarayıcısı akışını başlatmak için kullanılması gereken URL ve akışın sonunda geri çağırmasını beklediğiniz ve uygulamanızın işleyebilmesi için kayıtlı olduğu Uri.

Sonuç, geri çağırma URI'sinden ayrıştırılan tüm sorgu parametrelerini içeren bir WebAuthenticatorResult sonuçdur:

var authResult = await WebAuthenticator.AuthenticateAsync(
        new Uri("https://mysite.com/mobileauth/Microsoft"),
        new Uri("myapp://"));

var accessToken = authResult?.AccessToken;

API, WebAuthenticator url'yi tarayıcıda başlatmayı ve geri çağırma alınana kadar beklemeyi üstlenir:

Typical Web Authentication Flow

Kullanıcı herhangi bir noktada akışı iptal ederse, bir TaskCanceledException oluşturulur.

Özel kimlik doğrulama oturumu

iOS 13, geliştiricilerin kimlik doğrulama oturumunu özel olarak başlatması için kısa ömürlü bir web tarayıcısı API'sini kullanıma sundu. Bu, geliştiricilerin kimlik doğrulama oturumları arasında hiçbir paylaşılan tanımlama bilgisi veya göz atma verisi bulunmadığını ve her seferinde yeni bir oturum açma oturumu olmasını istemesine olanak tanır. Bu, iOS için 1.7 sürümünde Xamarin.Essentials kullanıma sunulan yeni WebAuthenticatorOptions sürümle kullanılabilir.

var url = new Uri("https://mysite.com/mobileauth/Microsoft");
var callbackUrl = new Uri("myapp://");
var authResult = await WebAuthenticator.AuthenticateAsync(new WebAuthenticatorOptions
    {
        Url = url,
        CallbackUrl = callbackUrl,
        PrefersEphemeralWebBrowserSession = true
    });

Platform farklılıkları

Özel Sekmeler kullanılabilir olduğunda kullanılır, aksi takdirde URL için bir Amaç başlatılır.

Apple'ın inceleme yönergelerine göre, uygulamanız kimlik doğrulaması için herhangi bir sosyal oturum açma hizmeti kullanıyorsa, apple oturum açma seçeneğini de sunmalıdır.

Uygulamalarınıza Apple Oturum Açma'yı eklemek için önce uygulamanızı Apple Oturum Açma'yı kullanacak şekilde yapılandırmanız gerekir.

iOS 13 ve üzeri için yöntemini çağırmak AppleSignInAuthenticator.AuthenticateAsync() istersiniz. Bu, kullanıcılarınızın bu cihazlarda mümkün olan en iyi deneyimi elde edebilmesi için arka planda yerel Apple Oturum Açma API'lerini kullanır. Çalışma zamanında doğru API'yi kullanmak için paylaşılan kodunuzu şu şekilde yazabilirsiniz:

var scheme = "..."; // Apple, Microsoft, Google, Facebook, etc.
WebAuthenticatorResult r = null;

if (scheme.Equals("Apple")
    && DeviceInfo.Platform == DevicePlatform.iOS
    && DeviceInfo.Version.Major >= 13)
{
    // Use Native Apple Sign In API's
    r = await AppleSignInAuthenticator.AuthenticateAsync();
}
else
{
    // Web Authentication flow
    var authUrl = new Uri(authenticationUrl + scheme);
    var callbackUrl = new Uri("xamarinessentials://");

    r = await WebAuthenticator.AuthenticateAsync(authUrl, callbackUrl);
}

var authToken = string.Empty;
if (r.Properties.TryGetValue("name", out var name) && !string.IsNullOrEmpty(name))
    authToken += $"Name: {name}{Environment.NewLine}";
if (r.Properties.TryGetValue("email", out var email) && !string.IsNullOrEmpty(email))
    authToken += $"Email: {email}{Environment.NewLine}";

// Note that Apple Sign In has an IdToken and not an AccessToken
authToken += r?.AccessToken ?? r?.IdToken;

İpucu

iOS 13 olmayan cihazlarda bu, Android ve UWP cihazlarınızda Apple Oturum Açma'yı etkinleştirmek için de kullanılabilen web kimlik doğrulama akışını başlatır. Apple Oturum Açma'yi test etmek için iOS simülatörünüzde iCloud hesabınızda oturum açabilirsiniz.

ASP.NET çekirdek sunucu arka ucu

API'yi herhangi bir web arka uç hizmetiyle kullanmak WebAuthenticator mümkündür. Bunu ASP.NET temel bir uygulamayla kullanmak için önce web uygulamasını aşağıdaki adımlarla yapılandırmanız gerekir:

İstediğiniz dış sosyal kimlik doğrulama sağlayıcılarını bir ASP.NET Core web uygulamasında ayarlayın.
Aramanızda .AddAuthentication() Varsayılan Kimlik Doğrulama Düzenini olarak CookieAuthenticationDefaults.AuthenticationScheme ayarlayın.
Startup.cs .AddAuthentication() aramanızda kullanın.AddCookie().
Tüm sağlayıcılar ile .SaveTokens = true;yapılandırılmalıdır.

services.AddAuthentication(o =>
    {
        o.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    })
    .AddCookie()
    .AddFacebook(fb =>
    {
        fb.AppId = Configuration["FacebookAppId"];
        fb.AppSecret = Configuration["FacebookAppSecret"];
        fb.SaveTokens = true;
    });

İpucu

Apple Oturum Açma'yı eklemek isterseniz NuGet paketini kullanabilirsiniz AspNet.Security.OAuth.Apple . Startup.cs örneğinin tamamını Essentials GitHub deposunda görüntüleyebilirsiniz.

Özel mobil kimlik doğrulama denetleyicisi ekleme

Mobil kimlik doğrulama akışıyla, akışın doğrudan kullanıcının seçtiği bir sağlayıcıya (örneğin, uygulamanın oturum açma ekranında "Microsoft" düğmesine tıklayarak) başlatılması tercih edilir. Ayrıca, kimlik doğrulama akışını sonlandırmak için belirli bir geri arama URI'sinde ilgili bilgileri uygulamanıza döndürebilmek de önemlidir.

Bunu başarmak için özel bir API Denetleyicisi kullanın:

[Route("mobileauth")]
[ApiController]
public class AuthController : ControllerBase
{
    const string callbackScheme = "myapp";

    [HttpGet("{scheme}")] // eg: Microsoft, Facebook, Apple, etc
    public async Task Get([FromRoute]string scheme)
    {
        // 1. Initiate authentication flow with the scheme (provider)
        // 2. When the provider calls back to this URL
        //    a. Parse out the result
        //    b. Build the app callback URL
        //    c. Redirect back to the app
    }
}

Bu denetleyicinin amacı, uygulamanın istediği şemayı (sağlayıcı) çıkarsamak ve sosyal sağlayıcıyla kimlik doğrulama akışını başlatmaktır. Sağlayıcı web arka ucuna geri çağırdığında denetleyici sonucu ayrıştırıp parametrelerle uygulamanın geri çağırma URI'sine yönlendirir.

Bazen sağlayıcının access_token uygulamaya geri dönmesi gibi verileri geri çağırma URI'sinin sorgu parametreleri aracılığıyla döndürmek isteyebilirsiniz. Alternatif olarak, bunun yerine sunucunuzda kendi kimliğinizi oluşturmak ve kendi belirtecinizi uygulamaya geri geçirmek isteyebilirsiniz. Bu bölümü ne ve nasıl yapacağın sana bağlı!

Essentials deposundaki tam denetleyici örneğine göz atın.

Not

Yukarıdaki örnekte, 3. taraf kimlik doğrulaması (yani OAuth) sağlayıcısından Erişim Belirtecinin nasıl döndürüleceği gösterilmektedir. Web isteklerini web arka ucuna yetkilendirmek için kullanabileceğiniz bir belirteç elde etmek için, web uygulamanızda kendi belirtecinizi oluşturmanız ve bunun yerine bunu döndürmeniz gerekir. ASP.NET Core kimlik doğrulamasına genel bakış, ASP.NET Core'daki gelişmiş kimlik doğrulama senaryoları hakkında daha fazla bilgi sağlar.

Aracılığıyla paylaş