Use this file to discover all available pages before exploring further.
This guide demonstrates how to integrate Auth0 with a .NET MAUI application using the Auth0.OidcClient.MAUI SDK. By the end, your app will support login, logout, and displaying user profile information across Android, iOS, macOS, and Windows from a single codebase.This guide uses Auth0.OidcClient.MAUI version 1.x.
Enter a name for your app (for example, “My MAUI App”), select Native as the application type, and select Create
Go to the Settings tab on the Application Details page
Note the Domain and Client ID values — you need these later
On the Settings tab, scroll to Application URIs and configure the following URLs. .NET MAUI apps use a custom URI scheme (for example, myapp://callback) rather than an HTTP URL.Allowed Callback URLs:
myapp://callback
Allowed Logout URLs:
myapp://callback
Choose a scheme that is unique to your app. A reversed domain name works well, for example com.mycompany.myapp://callback.
Select Save Changes.
You have a Native application in Auth0 with your Domain and Client ID noted, and the callback and logout URLs configured.
2
Create your MAUI project
If you already have a .NET MAUI project, skip to Step 3. Otherwise, create one using the .NET CLI:
dotnet new maui -n MyMauiAppcd MyMauiApp
3
Install the Auth0 MAUI SDK
Add the Auth0.OidcClient.MAUI NuGet package to your project:
dotnet add package Auth0.OidcClient.MAUI
Run dotnet restore to confirm the package installed without errors.
4
Configure platform-specific callback handling
.NET MAUI apps must register a callback handler on each platform so the system browser can redirect back to your app after authentication. Follow the instructions for each platform you are targeting.
Android
Windows
iOS / macOS
Create a new file at Platforms/Android/WebAuthenticatorActivity.cs:
Replace myapp with the URI scheme you configured in Step 1.
The CALLBACK_SCHEME value must exactly match the scheme in your RedirectUri and the Allowed Callback URLs in Auth0.
The Auth0 callback flow on Windows relies on URI protocol activation, which requires your app to be packaged (MSIX). The default .NET MAUI template creates a packaged app, so no changes are needed if you used dotnet new maui or the Visual Studio MAUI template.
If your .csproj contains <WindowsPackageType>None</WindowsPackageType>, your app is unpackaged and protocol activation will not work. Remove that line or set it to <WindowsPackageType>MSIX</WindowsPackageType> to use a packaged app. To learn more, see the .NET MAUI Windows packaging documentation.
Two changes are required: registering the URI protocol and handling protocol activation.1. Register the protocol in Platforms/Windows/Package.appxmanifest. Add the <Extensions> block inside the existing <Application> element:
namespace MyMauiApp;public partial class MainPage : ContentPage{ public MainPage(MainPageViewModel viewModel) { InitializeComponent(); BindingContext = viewModel; }}
Your project now has a ViewModel with login and logout commands, a data-bound XAML page, and wired-up code-behind.
6
Register services and instantiate the Auth0 client
Now register the Auth0Client, the ViewModel, and the page with dependency injection in MauiProgram.cs. This wires everything together so the Auth0 client is injected into the ViewModel, and the ViewModel is injected into the 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"); }); // Configure the Auth0 client with your credentials from Step 1 builder.Services.AddSingleton(new Auth0Client(new Auth0ClientOptions { Domain = "{yourDomain}", ClientId = "{yourClientId}", RedirectUri = "myapp://callback", PostLogoutRedirectUri = "myapp://callback" })); // Register the page and ViewModel created in Step 5 builder.Services.AddTransient<MainPage>(); builder.Services.AddTransient<MainPageViewModel>(); return builder.Build(); }}
Replace {yourDomain} and {yourClientId} with the values from your Auth0 application settings (Step 1).
RedirectUri and PostLogoutRedirectUri are required for MAUI apps. Use the same callback URL you entered in the Auth0 Dashboard.
7
Run your app
Build and run your .NET MAUI applicationExpected flow:
App launches and shows the Log In button
Tap Log In → system browser opens with Auth0 Universal Login
Complete authentication (sign up or log in)
Browser redirects back to your app
The app displays your name and email with a Log Out button
You now have a fully functional Auth0 login experience in your .NET MAUI application.
Symptom: The browser shows “Callback URL mismatch. The provided redirect_uri is not in the list of allowed callback URLs.”Fix:
Confirm the Client ID in your code matches the application you configured in the Auth0 Dashboard
Clear the Allowed Callback URLs field and retype myapp://callback manually — copy-paste often introduces invisible trailing spaces or newlines
Ensure the match is exact: no trailing slash, lowercase only, no whitespace
Select Save Changes in the Dashboard and verify the value persisted
Check the browser address bar for the redirect_uri query parameter to see what your app is actually sending
Android: app does not return from browser
Symptom: Browser opens for login but never redirects back to the app.Fix:
Verify DataScheme in WebAuthenticatorActivity.cs matches your RedirectUri scheme
Ensure the Activity has Exported = true
Confirm the Allowed Callback URLs in Auth0 Dashboard match exactly
Windows: login appears to hang
Symptom: Browser opens but a second instance of the app opens instead of resuming.Fix: Ensure Auth0.OidcClient.Platforms.Windows.Activator.Default.CheckRedirectionActivation() is called as the very first line of the App constructor in Platforms/Windows/App.xaml.cs, and that the protocol name in Package.appxmanifest matches your callback URI scheme.
Windows: protocol activation does not work
Symptom: After login, the browser shows an error or nothing happens — the app never receives the callback.Fix: Your app must be a packaged (MSIX) application. Check your .csproj file for a <WindowsPackageType> element:
If it is set to None, protocol activation is not available. Remove the line or change it to <WindowsPackageType>MSIX</WindowsPackageType>.
If the element is absent, your app is already packaged by default — verify that Package.appxmanifest contains the <uap:Protocol> extension from Step 4.
Missing claims in user profile
Symptom: name, email, or picture claims are absent from loginResult.User.Fix: Verify that openid profile email are included in Auth0ClientOptions.Scope. If you have customized the scope, ensure openid is always present.
After login, store the refresh token and use it to silently renew the session:
// After loginvar refreshToken = loginResult.RefreshToken;// Later, renew the sessionvar refreshResult = await _client.RefreshTokenAsync(refreshToken);if (!refreshResult.IsError){ var newAccessToken = refreshResult.AccessToken; var newIdToken = refreshResult.IdentityToken;}
If RefreshToken is null after login, ensure Allow Offline Access is enabled in your API settings in the Auth0 Dashboard (when using an audience parameter).
Call a protected API
To get an access token scoped to your API, set the Scope and pass an audience parameter to LoginAsync():
var loginResult = await _client.LoginAsync(new{ audience = "https://myapi.example.com"});// The access token is now scoped to your APIvar 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");
Organizations (B2B/enterprise)
Authenticate users within a specific Auth0 Organization:
var loginResult = await _client.LoginAsync(new{ organization = "org_abc123"});