Démarrage rapide du SDK Auth0 .NET MAUI : ajouter l’authentification à votre application .NET MAUI

Utiliser l’IA pour intégrer Auth0

Si vous utilisez un assistant de programmation IA comme Claude Code, Cursor ou GitHub Copilot, vous pouvez ajouter l’authentification Auth0 automatiquement en quelques minutes à l’aide des agent skills.Installer :

npx skills add auth0/agent-skills --skill auth0-quickstart --skill auth0-maui

Ensuite, demandez à votre assistant IA :

Add Auth0 authentication to my .NET MAUI app

Votre assistant IA créera automatiquement votre application Auth0, récupérera les identifiants, installera le SDK Auth0 OidcClient MAUI, configurera les URL de rappel et mettra en œuvre les flux de connexion et de déconnexion. Documentation complète sur les agent skills →

Ce guide explique comment intégrer Auth0 à une application .NET MAUI à l’aide du SDK Auth0.OidcClient.MAUI. Au terme de ce guide, votre application prendra en charge la connexion, la déconnexion et l’affichage des informations du profil utilisateur sur Android, iOS, macOS et Windows, à partir d’une seule base de code. Ce guide utilise la version 1.x de Auth0.OidcClient.MAUI.

Prérequis

SDK .NET 8 ou .NET 9 installé (télécharger)
Charge de travail MAUI installée
Un compte Auth0 (inscrivez-vous gratuitement)
Visual Studio 2022 (17.8+), JetBrains Rider ou VS Code avec l’extension .NET MAUI

Vérifiez votre environnement :

dotnet --version        # Devrait être 8.x ou 9.x
dotnet workload list    # Devrait inclure maui

Si la charge de travail MAUI n’est pas installée, installez-la :

dotnet workload install maui

Premiers pas

Configurez votre application Auth0

Configurez votre application Auth0 afin d’avoir les identifiants dont votre application MAUI a besoin.

Accédez à Auth0 Dashboard > Applications > Applications
Sélectionnez Create Application
Entrez un nom pour votre application (par exemple, “My MAUI App”), sélectionnez Native comme type d’application, puis sélectionnez Create
Accédez à l’onglet Settings de la page Application Details
Prenez en note les valeurs Domaine et ID client — vous en aurez besoin plus tard

Dans l’onglet Settings, faites défiler la page jusqu’à Application URIs et configurez les URL suivantes. Les applications .NET MAUI utilisent un schéma d’URI personnalisé (par exemple, myapp://callback) plutôt qu’une URL HTTP.Allowed Callback URLs:

myapp://callback

URL de déconnexion autorisées :

myapp://callback

Choisissez un schéma propre à votre application. Un nom de domaine inversé convient bien, par exemple com.mycompany.myapp://callback.

Sélectionnez Enregistrer les modifications.

Vous avez une application native dans Auth0 avec votre Domaine et votre ID client en main, ainsi que les URL de rappel et de déconnexion configurées.

Créez votre projet MAUI

Si vous avez déjà un projet .NET MAUI, passez à l’étape 3. Sinon, créez-en un à l’aide de la CLI .NET :

dotnet new maui -n MyMauiApp
cd MyMauiApp

Installer le SDK MAUI d’Auth0

Ajoutez le package NuGet Auth0.OidcClient.MAUI à votre projet :

dotnet add package Auth0.OidcClient.MAUI

Exécutez dotnet restore pour confirmer que le package s’est installé sans erreur.

Configurer le traitement du callback propre à la plateforme

Les applications .NET MAUI doivent enregistrer un gestionnaire de rappel sur chaque plateforme afin que le navigateur système puisse rediriger l’utilisateur vers votre application après l’authentification. Suivez les instructions pour chaque plateforme ciblée.

Android
Windows
iOS / macOS

Créez un nouveau fichier dans Platforms/Android/WebAuthenticatorActivity.cs :

Platforms/Android/WebAuthenticatorActivity.cs

using Android.App;
using Android.Content;
using Android.Content.PM;

namespace MyMauiApp.Platforms.Android;

[Activity(NoHistory = true, LaunchMode = LaunchMode.SingleTop, Exported = true)]
[IntentFilter(new[] { Intent.ActionView },
              Categories = new[] { Intent.CategoryDefault, Intent.CategoryBrowsable },
              DataScheme = CALLBACK_SCHEME)]
public class WebAuthenticatorActivity : Microsoft.Maui.Authentication.WebAuthenticatorCallbackActivity
{
    const string CALLBACK_SCHEME = "myapp";
}

Remplacez myapp par le schéma d’URI que vous avez configuré à l’étape 1.

La valeur CALLBACK_SCHEME doit correspondre exactement au schéma indiqué dans votre RedirectUri et dans Allowed Callback URLs dans Auth0.

Le flux de rappel d’Auth0 sous Windows repose sur l’activation par protocole URI, ce qui exige que votre application soit packagée (MSIX). Le modèle .NET MAUI par défaut crée une application packagée; aucune modification n’est donc nécessaire si vous avez utilisé dotnet new maui ou le modèle MAUI de Visual Studio.

Si votre .csproj contient <WindowsPackageType>None</WindowsPackageType>, votre application n’est pas packagée et l’activation par protocole ne fonctionnera pas. Supprimez cette ligne ou définissez-la à <WindowsPackageType>MSIX</WindowsPackageType> pour utiliser une application packagée. Pour en savoir plus, consultez la documentation .NET MAUI sur le packaging Windows.

Deux modifications sont requises : enregistrer le protocole URI et gérer son activation.1. Enregistrez le protocole dans Platforms/Windows/Package.appxmanifest. Ajoutez le bloc <Extensions> à l’intérieur de l’élément <Application> existant :

Platforms/Windows/Package.appxmanifest

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

2. Gérez l’activation dans Platforms/Windows/App.xaml.cs. Ajoutez l’appel à CheckRedirectionActivation comme première ligne du constructeur :

Platforms/Windows/App.xaml.cs

public App()
{
    if (Auth0.OidcClient.Platforms.Windows.Activator.Default.CheckRedirectionActivation())
        return;

    this.InitializeComponent();
}

Aucune configuration propre à la plateforme n’est requise. Le SDK utilise automatiquement ASWebAuthenticationSession par l’intermédiaire du WebAuthenticator de MAUI.

Ajouter la connexion et la déconnexion

Vous devez créer ou modifier trois fichiers : un ViewModel avec la logique de connexion et de déconnexion, une page XAML pour l’interface utilisateur et un fichier code-behind pour les relier.

MainPageViewModel.cs
MainPage.xaml
MainPage.xaml.cs

Créez le ViewModel dans ViewModels/MainPageViewModel.cs :

ViewModels/MainPageViewModel.cs

using System.ComponentModel;
using System.Runtime.CompilerServices;
using System.Windows.Input;
using Auth0.OidcClient;

namespace MyMauiApp.ViewModels;

public class MainPageViewModel : INotifyPropertyChanged
{
    private readonly Auth0Client _client;
    private string _name;
    private string _email;
    private bool _isAuthenticated;

    public event PropertyChangedEventHandler PropertyChanged;

    public string Name
    {
        get => _name;
        set { _name = value; OnPropertyChanged(); }
    }

    public string Email
    {
        get => _email;
        set { _email = value; OnPropertyChanged(); }
    }

    public bool IsAuthenticated
    {
        get => _isAuthenticated;
        set
        {
            _isAuthenticated = value;
            OnPropertyChanged();
            OnPropertyChanged(nameof(IsNotAuthenticated));
        }
    }

    public bool IsNotAuthenticated => !IsAuthenticated;

    public ICommand LoginCommand { get; }
    public ICommand LogoutCommand { get; }

    public MainPageViewModel(Auth0Client client)
    {
        _client = client;
        LoginCommand = new Command(async () => await LoginAsync());
        LogoutCommand = new Command(async () => await LogoutAsync());
    }

    private async Task LoginAsync()
    {
        var loginResult = await _client.LoginAsync();

        if (loginResult.IsError)
        {
            if (loginResult.Error == "UserCancel")
                return; // L’utilisateur a fermé le navigateur — ce n’est pas une erreur

            await Shell.Current.DisplayAlert("Échec de la connexion", loginResult.Error, "OK");
            return;
        }

        // Lire les claims du profil utilisateur à partir de l’ID Token
        Name = loginResult.User.FindFirst(c => c.Type == "name")?.Value;
        Email = loginResult.User.FindFirst(c => c.Type == "email")?.Value;
        IsAuthenticated = true;
    }

    private async Task LogoutAsync()
    {
        await _client.LogoutAsync();

        Name = null;
        Email = null;
        IsAuthenticated = false;
    }

    private void OnPropertyChanged([CallerMemberName] string propertyName = null)
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }
}

Configurez l’interface utilisateur dans MainPage.xaml :

MainPage.xaml

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="MyMauiApp.MainPage">

    <VerticalStackLayout Spacing="20" Padding="30" VerticalOptions="Center">

        <!-- Affiché lorsque l’utilisateur est déconnecté -->
        <Button Text="Se connecter"
                Command="{Binding LoginCommand}"
                IsVisible="{Binding IsNotAuthenticated}" />

        <!-- Affiché lorsque l’utilisateur est connecté -->
        <Label Text="{Binding Name, StringFormat='Bienvenue, {0}!'}"
               IsVisible="{Binding IsAuthenticated}"
               FontSize="24"
               HorizontalOptions="Center" />

        <Label Text="{Binding Email}"
               IsVisible="{Binding IsAuthenticated}"
               HorizontalOptions="Center" />

        <Button Text="Se déconnecter"
                Command="{Binding LogoutCommand}"
                IsVisible="{Binding IsAuthenticated}" />

    </VerticalStackLayout>
</ContentPage>

Définissez le BindingContext dans MainPage.xaml.cs :

MainPage.xaml.cs

namespace MyMauiApp;

public partial class MainPage : ContentPage
{
    public MainPage(MainPageViewModel viewModel)
    {
        InitializeComponent();
        BindingContext = viewModel;
    }
}

Votre projet contient maintenant un ViewModel avec des commandes de connexion et de déconnexion, une page XAML avec liaison de données et un code-behind relié.

Enregistrer les services et instancier le client Auth0

Maintenant, enregistrez Auth0Client, le ViewModel et la page à l’aide de l’injection de dépendances dans MauiProgram.cs. Cela connecte le tout de sorte que le client Auth0 soit injecté dans le ViewModel, et que le ViewModel soit injecté dans la page :

MauiProgram.cs

using Auth0.OidcClient;
using MyMauiApp.ViewModels;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
            });

        // Configurer l'application Auth0 avec vos identifiants de l'étape 1
        builder.Services.AddSingleton(new Auth0Client(new Auth0ClientOptions
        {
            Domain = "{yourDomain}",
            ClientId = "{yourClientId}",
            RedirectUri = "myapp://callback",
            PostLogoutRedirectUri = "myapp://callback"
        }));

        // Enregistrer la page et le ViewModel créés à l'étape 5
        builder.Services.AddTransient<MainPage>();
        builder.Services.AddTransient<MainPageViewModel>();

        return builder.Build();
    }
}

Remplacez {yourDomain} et {yourClientId} par les valeurs indiquées dans les paramètres de votre application Auth0 (étape 1). RedirectUri et PostLogoutRedirectUri sont obligatoires pour les applications MAUI. Utilisez la même URL de rappel que celle saisie dans l’Auth0 Dashboard.

Lancez votre application

Compilez et exécutez votre application .NET MAUIFlux attendu :

L’application se lance et affiche le bouton Se connecter
Touchez Se connecter → le navigateur système s’ouvre sur Universal Login d’Auth0
Terminez l’authentification (créez un compte ou connectez-vous)
Le navigateur vous redirige vers votre application
L’application affiche votre nom et votre courriel avec un bouton Se déconnecter

Vous avez maintenant une expérience de connexion Auth0 entièrement fonctionnelle dans votre application .NET MAUI.

Dépannage

Incompatibilité de l’URL de rappel

Symptôme : Le navigateur affiche « Callback URL mismatch. The provided redirect_uri is not in the list of allowed callback URLs. »Correctif :

Vérifiez que le Client ID dans votre code correspond à l’application que vous avez configurée dans l’Auth0 Dashboard
Videz le champ Allowed Callback URLs et retapez myapp://callback manuellement — le copier-coller ajoute souvent des espaces ou des sauts de ligne invisibles à la fin
Assurez-vous que la valeur correspond exactement : pas de barre oblique finale, uniquement des minuscules, aucun espace
Sélectionnez Save Changes dans l’Auth0 Dashboard et vérifiez que la valeur a bien été enregistrée
Vérifiez le paramètre de requête redirect_uri dans la barre d’adresse du navigateur pour voir ce que votre application envoie réellement

Android : l’application ne revient pas depuis le navigateur

Symptôme : Le navigateur s’ouvre pour la connexion, mais ne redirige jamais vers l’application.Correctif :

Vérifiez que DataScheme dans WebAuthenticatorActivity.cs correspond au schéma de votre RedirectUri
Assurez-vous que l’activité a Exported = true
Vérifiez que les Allowed Callback URLs dans l’Auth0 Dashboard correspondent exactement

Windows : la connexion semble bloquée

Symptôme : Le navigateur s’ouvre, mais une deuxième instance de l’application s’ouvre au lieu de reprendre la session.Correctif : Assurez-vous que Auth0.OidcClient.Platforms.Windows.Activator.Default.CheckRedirectionActivation() est appelée comme toute première ligne du constructeur App dans Platforms/Windows/App.xaml.cs, et que le nom du protocole dans Package.appxmanifest correspond au schéma de votre URI de rappel.

Windows : l’activation du protocole ne fonctionne pas

Symptôme : Après la connexion, le navigateur affiche une erreur ou rien ne se passe — l’application ne reçoit jamais l’URL de rappel.Correctif : Votre application doit être une application packagée (MSIX). Vérifiez votre fichier .csproj pour y trouver un élément <WindowsPackageType> :

S’il est défini à None, l’activation du protocole n’est pas disponible. Supprimez la ligne ou remplacez-la par <WindowsPackageType>MSIX</WindowsPackageType>.
Si l’élément est absent, votre application est déjà packagée par défaut — vérifiez que Package.appxmanifest contient l’extension <uap:Protocol> de l’étape 4.

Claims manquantes dans le profil de l’utilisateur

Symptôme : Les claims name, email ou picture sont absentes de loginResult.User.Correctif : Vérifiez que openid profile email sont inclus dans Auth0ClientOptions.Scope. Si vous avez personnalisé le scope, assurez-vous que openid est toujours présent.

Prochaines étapes

Vous disposez maintenant d’une intégration Auth0 fonctionnelle dans votre application .NET MAUI. Explorez les sujets suivants pour approfondir votre implémentation :

Jetons d’actualisation

Le SDK Auth0 MAUI prend en charge les jetons d’actualisation pour renouveler les sessions de façon silencieuse, sans redemander à l’utilisateur de s’authentifier.

Activer les jetons d’actualisation

Ajoutez offline_access à la propriété Scope :

builder.Services.AddSingleton(new Auth0Client(new Auth0ClientOptions
{
    Domain = "{yourDomain}",
    ClientId = "{yourClientId}",
    RedirectUri = "myapp://callback",
    PostLogoutRedirectUri = "myapp://callback",
    Scope = "openid profile email offline_access"
}));

Utiliser les jetons d’actualisation

Après la connexion, stockez le jeton d’actualisation et utilisez-le pour renouveler la session de façon silencieuse :

// Après la connexion
var refreshToken = loginResult.RefreshToken;

// Plus tard, renouveler la session
var refreshResult = await _client.RefreshTokenAsync(refreshToken);

if (!refreshResult.IsError)
{
    var newAccessToken = refreshResult.AccessToken;
    var newIdToken = refreshResult.IdentityToken;
}

Si RefreshToken est null après la connexion, assurez-vous que Allow Offline Access est activé dans les paramètres de votre API dans l’Auth0 Dashboard (lorsque vous utilisez un paramètre audience).

Appeler une API protégée

Pour obtenir un jeton d’accès associé à votre API, définissez Scope et transmettez un paramètre audience à LoginAsync() :

var loginResult = await _client.LoginAsync(new
{
    audience = "https://myapi.example.com"
});

// Le jeton d’accès est maintenant associé à votre API
var accessToken = loginResult.AccessToken;

var httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", accessToken);

var response = await httpClient.GetAsync("https://myapi.example.com/posts");

Organisations (B2B/entreprise)

Authentifiez les utilisateurs au sein d’une organisation Auth0 précise :

var loginResult = await _client.LoginAsync(new
{
    organization = "org_abc123"
});

Pour en savoir plus, consultez Organisations.

Forcer une nouvelle authentification

Utilisez MaxAge pour forcer une nouvelle authentification après un délai défini :

new Auth0ClientOptions
{
    Domain = "{yourDomain}",
    ClientId = "{yourClientId}",
    RedirectUri = "myapp://callback",
    PostLogoutRedirectUri = "myapp://callback",
    MaxAge = TimeSpan.FromMinutes(30)
}

Personnaliser Universal Login

Ressources supplémentaires

Dépôt du SDK

Code source, exemples et référence de l’API

Bonnes pratiques relatives aux jetons

Bonnes pratiques de sécurité pour les jetons

Flux PKCE

Comment les applications natives s’authentifient en toute sécurité

Forum de la communauté

Obtenez de l’aide auprès de la communauté Auth0

​Prérequis

​Premiers pas

​Dépannage

​Prochaines étapes

​Activer les jetons d’actualisation

​Utiliser les jetons d’actualisation

​Ressources supplémentaires

Dépôt du SDK

Bonnes pratiques relatives aux jetons

Flux PKCE

Forum de la communauté

Prérequis

Premiers pas

Dépannage

Prochaines étapes

Activer les jetons d’actualisation

Utiliser les jetons d’actualisation

Ressources supplémentaires