Xamarin.Essentials: Authentificateur web

La classe WebAuthenticator vous permet de lancer des flux basés sur un navigateur qui écoutent un rappel à une URL spécifique inscrite dans l’application.

Vue d’ensemble

De nombreuses applications nécessitent l’ajout de l’authentification utilisateur, ce qui signifie souvent permettre à vos utilisateurs de se connecter à leurs comptes de connexion Microsoft, Facebook, Google et maintenant Apple.

La bibliothèque d’authentification Microsoft (MSAL) fournit une excellente solution clé en clé pour ajouter l’authentification à votre application. Il existe même une prise en charge des applications Xamarin dans leur package NuGet client.

Si vous souhaitez utiliser votre propre service web pour l’authentification, il est possible d’utiliser WebAuthenticator pour implémenter la fonctionnalité côté client.

Pourquoi utiliser un serveur principal ?

De nombreux fournisseurs d’authentification sont passés à offrir uniquement des flux d’authentification explicites ou à deux pattes pour garantir une meilleure sécurité. Cela signifie que vous aurez besoin d’une « clé secrète client » du fournisseur pour terminer le flux d’authentification. Malheureusement, les applications mobiles ne sont pas un endroit idéal pour stocker des secrets et tout ce qui est stocké dans le code, les fichiers binaires ou autres d’une application mobile est généralement considéré comme non sécurisé.

La meilleure pratique consiste à utiliser un back-end web comme couche intermédiaire entre votre application mobile et le fournisseur d’authentification.

Important

Nous vous déconseillons vivement d’utiliser des modèles et des bibliothèques d’authentification mobiles uniquement plus anciens qui ne tirent pas parti d’un back-end web dans le flux d’authentification en raison de leur manque de sécurité inhérent au stockage des secrets client.

Bien démarrer

Pour commencer à utiliser cette API, lisez le guide de prise en main pour Xamarin.Essentials vous assurer que la bibliothèque est correctement installée et configurée dans vos projets.

Pour accéder à la fonctionnalité WebAuthenticator , la configuration spécifique à la plateforme suivante est requise.

Android

Android nécessite une configuration de filtre d’intention pour gérer votre URI de rappel. Pour ce faire, vous pouvez facilement sous-classer la WebAuthenticatorCallbackActivity classe :

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

Si la version Android cible de votre projet est définie sur Android 11 (API R 30), vous devez mettre à jour votre manifeste Android avec les requêtes utilisées avec les nouvelles exigences de visibilité des packages.

Ouvrez le fichier AndroidManifest.xml sous le dossier Propriétés, puis ajoutez ce qui suit dans le nœud manifeste :

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

iOS

Sur iOS, vous devez ajouter le modèle d’URI de rappel de votre application à votre liste Info.plist, par exemple :

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

Vous devez également remplacer vos AppDelegateOpenUrl méthodes et ContinueUserActivity pour appeler Essentials :

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

Pour UWP, vous devez déclarer votre URI de rappel dans votre Package.appxmanifest fichier :

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

Utilisation de WebAuthenticator

Ajoutez une référence à Xamarin.Essentials dans votre classe :

using Xamarin.Essentials;

L’API se compose principalement d’une méthode AuthenticateAsync unique qui prend deux paramètres : l’URL qui doit être utilisée pour démarrer le flux de navigateur web et l’URI vers lequel le flux doit finalement rappeler et que votre application est inscrite pour être en mesure de gérer.

Le résultat est un WebAuthenticatorResult qui inclut tous les paramètres de requête analysés à partir de l’URI de rappel :

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

var accessToken = authResult?.AccessToken;

L’API WebAuthenticator se charge de lancer l’URL dans le navigateur et d’attendre que le rappel soit reçu :

Si l’utilisateur annule le flux à un moment donné, un TaskCanceledException est levée.

Session d’authentification privée

iOS 13 a introduit une API de navigateur web éphémère permettant aux développeurs de lancer la session d’authentification en tant que privée. Cela permet aux développeurs de demander qu’aucun cookie partagé ou aucune donnée de navigation n’est disponible entre les sessions d’authentification et qu’il s’agit d’une nouvelle session de connexion à chaque fois. Ceci est disponible via la nouvelle WebAuthenticatorOptions qui a été introduite dans Xamarin.Essentials la version 1.7 pour iOS.

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

Différences de plateforme

Android

Les onglets personnalisés sont utilisés chaque fois qu’ils sont disponibles, sinon une intention est démarrée pour l’URL.

iOS

Sur iOS 12 ou version ultérieure, ASWebAuthenticationSession est utilisé. Sur iOS 11, SFAuthenticationSession est utilisé. Sur les anciennes versions d’iOS, SFSafariViewController est utilisé si disponible, sinon Safari est utilisé.

UWP

Sur UWP, le WebAuthenticationBroker est utilisé s’il est pris en charge; sinon, le navigateur système est utilisé.

Connexion Apple

Selon les instructions de révision d’Apple, si votre application utilise un service de connexion aux réseaux sociaux pour s’authentifier, elle doit également proposer la connexion Apple en option.

Pour ajouter la connexion Apple à vos applications, vous devez d’abord configurer votre application pour utiliser la connexion Apple.

Pour iOS 13 et versions ultérieures, vous devez appeler la AppleSignInAuthenticator.AuthenticateAsync() méthode . Cela utilisera les API de connexion Apple natives sous le capot afin que vos utilisateurs bénéficient de la meilleure expérience possible sur ces appareils. Vous pouvez écrire votre code partagé pour utiliser l’API appropriée au moment de l’exécution, comme suit :

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;

Conseil

Pour les appareils non iOS 13, cela démarre le flux d’authentification web, qui peut également être utilisé pour activer la connexion Apple sur vos appareils Android et UWP. Vous pouvez vous connecter à votre compte iCloud sur votre simulateur iOS pour tester la connexion Apple.

---

serveur principal ASP.NET principal

Il est possible d’utiliser l’API WebAuthenticator avec n’importe quel service back-end web. Pour l’utiliser avec une application principale ASP.NET, vous devez d’abord configurer l’application web en procédant comme suit :

1. Configurez vos fournisseurs d’authentification sociale externes souhaités dans une application web ASP.NET Core.
2. Définissez le schéma CookieAuthenticationDefaults.AuthenticationScheme d’authentification par défaut sur dans votre .AddAuthentication() appel.
3. Utilisez .AddCookie() dans votre appel Startup.cs .AddAuthentication() .
4. Tous les fournisseurs doivent être configurés avec .SaveTokens = true;.

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

Conseil

Si vous souhaitez inclure la connexion Apple, vous pouvez utiliser le AspNet.Security.OAuth.Apple package NuGet. Vous pouvez afficher l’exemple Startup.cs complet dans le référentiel GitHub Essentials.

Ajouter un contrôleur d’authentification mobile personnalisé

Avec un flux d’authentification mobile, il est généralement souhaitable de lancer le flux directement auprès d’un fournisseur que l’utilisateur a choisi (par exemple, en cliquant sur un bouton « Microsoft » sur l’écran de connexion de l’application). Il est également important de pouvoir retourner des informations pertinentes à votre application à un URI de rappel spécifique pour mettre fin au flux d’authentification.

Pour ce faire, utilisez un contrôleur d’API personnalisé :

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

L’objectif de ce contrôleur est de déduire le schéma (fournisseur) demandé par l’application et de lancer le flux d’authentification avec le fournisseur social. Lorsque le fournisseur appelle le back-end web, le contrôleur analyse le résultat et redirige vers l’URI de rappel de l’application avec des paramètres.

Parfois, vous pouvez retourner des données telles que le retour du access_token fournisseur à l’application, ce que vous pouvez faire via les paramètres de requête de l’URI de rappel. Vous pouvez également créer votre propre identité sur votre serveur et transmettre votre propre jeton à l’application. Ce que vous faites et comment vous faites cette partie est à vous de choisir!

Consultez l’exemple de contrôleur complet dans le référentiel Essentials.

Notes

L’exemple ci-dessus montre comment retourner le jeton d’accès à partir du fournisseur d’authentification tierce (par exemple: OAuth). Pour obtenir un jeton que vous pouvez utiliser pour autoriser les demandes web au serveur principal web lui-même, vous devez créer votre propre jeton dans votre application web et le retourner à la place. La vue d’ensemble de l’authentification ASP.NET Core contient plus d’informations sur les scénarios d’authentification avancés dans ASP.NET Core.

---

API

• Code source WebAuthenticator
• Documentation de l’API WebAuthenticator
• exemple de serveur ASP.NET Core