Auth0.OidcClient.MAUI version 1.x.
Prerequisites
- .NET 8 or .NET 9 SDK installed (download)
- MAUI workload installed
- An Auth0 account (sign up for free)
- Visual Studio 2022 (17.8+), JetBrains Rider, or VS Code with the .NET MAUI extension
Get started
Configure your Auth0 application
Set up your Auth0 application so you have the credentials your MAUI app needs.Allowed Logout URLs:Select Save Changes.
- Go to Auth0 Dashboard > Applications > Applications
- Select Create Application
- 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
myapp://callback) rather than an HTTP URL.Allowed Callback URLs:You have a Native application in Auth0 with your Domain and Client ID noted, and the callback and logout URLs configured.
Create your MAUI project
If you already have a .NET MAUI project, skip to Step 3. Otherwise, create one using the .NET CLI:
Install the Auth0 MAUI SDK
Add the
Auth0.OidcClient.MAUI NuGet package to your project:Run
dotnet restore to confirm the package installed without errors.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 Replace
Platforms/Android/WebAuthenticatorActivity.cs:Platforms/Android/WebAuthenticatorActivity.cs
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.Add login and logout
You need to create/modify three files: a ViewModel with the login/logout logic, a XAML page for the UI, and a code-behind file to wire them together.
- MainPageViewModel.cs
- MainPage.xaml
- MainPage.xaml.cs
Create the ViewModel at
ViewModels/MainPageViewModel.cs:ViewModels/MainPageViewModel.cs
Your project now has a ViewModel with login and logout commands, a data-bound XAML page, and wired-up code-behind.
Register services and instantiate the Auth0 client
Now register the Replace
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
{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.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.
Troubleshooting
Callback URL mismatch
Callback URL mismatch
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://callbackmanually — 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_uriquery parameter to see what your app is actually sending
Android: app does not return from browser
Android: app does not return from browser
Symptom: Browser opens for login but never redirects back to the app.Fix:
- Verify
DataSchemeinWebAuthenticatorActivity.csmatches yourRedirectUrischeme - Ensure the Activity has
Exported = true - Confirm the Allowed Callback URLs in Auth0 Dashboard match exactly
Windows: login appears to hang
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
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.appxmanifestcontains the<uap:Protocol>extension from Step 4.
Missing claims in user profile
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.Next steps
You now have a working Auth0 integration in your .NET MAUI app. Explore these topics to extend your implementation:Refresh tokens
Refresh tokens
The Auth0 MAUI SDK supports refresh tokens for silently renewing sessions without re-prompting the user.
Enable refresh tokens
Addoffline_access to the Scope property:Use refresh tokens
After login, store the refresh token and use it to silently renew the session: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
Call a protected API
To get an access token scoped to your API, set the
Scope and pass an audience parameter to LoginAsync():Organizations (B2B/enterprise)
Organizations (B2B/enterprise)
Force re-authentication
Force re-authentication
Use
MaxAge to force re-authentication after a specified time:Customize Universal Login
Customize Universal Login
Tailor the Auth0 login page to match your brand, including colors, logos, and text.To learn more, see Customize Universal Login.
Additional resources
SDK Repository
Source code, samples, and API reference
Token Best Practices
Security best practices for tokens
PKCE Flow
How native apps authenticate securely
Community Forum
Get help from the Auth0 community