Add Login to Your .NET Android & iOS Application

Get Started

Create a new .NET project

Create a new .NET MAUI or .NET Android/iOS project for this quickstart.

.NET MAUI
.NET Android
.NET iOS

In Visual Studio 2022 or later:

File → New → Project
Select .NET MAUI App template
Configure your project:
- Project name: Auth0MauiSample
- Location: Choose your preferred location
- Framework: .NET 8.0 or later
Click Create

In Visual Studio 2022 or later:

File → New → Project
Select Android App (.NET) template
Configure your project:
- Project name: Auth0AndroidSample
- Framework: .NET 8.0 or later
Click Create

In Visual Studio 2022 (Mac) or Visual Studio for Mac:

File → New → Project
Select iOS App (.NET) template
Configure your project:
- Project name: Auth0iOSSample
- Framework: .NET 8.0 or later
Click Create

This quickstart focuses on .NET Android and iOS, which are the next generation of Xamarin.Android and Xamarin.iOS. If you’re still using Xamarin, you can follow this guide as the integration is identical and the SDKs are compatible.

Install Auth0 SDK

Add the Auth0 OIDC Client SDK to your project.

Package Manager Console
Visual Studio for Mac
.NET CLI

Open the Package Manager Console (View → Other Windows → Package Manager Console) and install the appropriate package:For .NET Android:

Package Manager Console

Install-Package Auth0.OidcClient.AndroidX

For .NET iOS:

Package Manager Console

Install-Package Auth0.OidcClient.iOS

For .NET MAUI (both platforms):

Package Manager Console

Install-Package Auth0.OidcClient.MAUI

In the Solution Pad, Ctrl+click (or right-click) on the Packages folder
Select Add Packages…
Search for:
- Auth0.OidcClient.AndroidX for Android
- Auth0.OidcClient.iOS for iOS
- Auth0.OidcClient.MAUI for MAUI projects
Select the package and click Add Package

Run the following command in your project directory:For .NET Android:

Terminal

dotnet add package Auth0.OidcClient.AndroidX

For .NET iOS:

Terminal

dotnet add package Auth0.OidcClient.iOS

For .NET MAUI:

Terminal

dotnet add package Auth0.OidcClient.MAUI

The Auth0 OIDC Client SDK handles all the OAuth 2.0 and OIDC protocol details, providing a simple API for authentication.

Setup your Auth0 App

Create a new application in your Auth0 tenant and configure it for mobile.

Head to the Auth0 Dashboard
Click on Applications → Applications → Create Application
Enter a name for your app, select Native as the app type, and click Create
Switch to the Settings tab on the Application Details page
Note your Domain and Client ID - you’ll need these in the next step

Configure Callback URLs:On the Settings tab, add the following URLs:Allowed Callback URLs:

Android
iOS

YOUR_ANDROID_PACKAGE_NAME://{yourDomain}/android/YOUR_ANDROID_PACKAGE_NAME/callback

Replace:

YOUR_ANDROID_PACKAGE_NAME with your app’s package name (e.g., com.mycompany.myapp)
{yourDomain} with your Auth0 domain (e.g., dev-abc123.us.auth0.com)

Example: com.mycompany.myapp://dev-abc123.us.auth0.com/android/com.mycompany.myapp/callback

YOUR_BUNDLE_IDENTIFIER://{yourDomain}/ios/YOUR_BUNDLE_IDENTIFIER/callback

Replace:

YOUR_BUNDLE_IDENTIFIER with your app’s bundle identifier (e.g., com.mycompany.myapp)
{yourDomain} with your Auth0 domain (e.g., dev-abc123.us.auth0.com)

Example: com.mycompany.myapp://dev-abc123.us.auth0.com/ios/com.mycompany.myapp/callback

Allowed Logout URLs:Use the same URLs as your callback URLs.

Ensure that callback and logout URLs are in lowercase. Mismatched URLs will cause authentication to fail.

Allowed Callback URLs are essential for security - they ensure users are safely returned to your application after authentication. Without a matching URL, the login process will fail.Allowed Logout URLs provide a seamless experience when users sign out, redirecting them back to your app instead of leaving them on an Auth0 page.

Initialize the Auth0 Client

Create an Auth0Client instance to communicate with Auth0.

Android - MainActivity
iOS - AppDelegate

MainActivity.cs

using Auth0.OidcClient;
using Android.App;
using Android.Content;

[Activity(Label = "Auth0Sample", MainLauncher = true, Icon = "@drawable/icon",
    LaunchMode = LaunchMode.SingleTask)]
[IntentFilter(
    new[] { Intent.ActionView },
    Categories = new[] { Intent.CategoryDefault, Intent.CategoryBrowsable },
    DataScheme = "YOUR_ANDROID_PACKAGE_NAME",
    DataHost = "{yourDomain}",
    DataPathPrefix = "/android/YOUR_ANDROID_PACKAGE_NAME/callback")]
public class MainActivity : Activity
{
    private Auth0Client auth0Client;

    protected override void OnCreate(Bundle savedInstanceState)
    {
        base.OnCreate(savedInstanceState);

        // Initialize Auth0 client
        auth0Client = new Auth0Client(new Auth0ClientOptions
        {
            Domain = "{yourDomain}",
            ClientId = "{yourClientId}"
        }, this);
    }

    protected override async void OnNewIntent(Intent intent)
    {
        base.OnNewIntent(intent);
        Auth0.OidcClient.ActivityMediator.Instance.Send(intent.DataString);
    }
}

Replace YOUR_ANDROID_PACKAGE_NAME, {yourDomain}, and {yourClientId} with your actual values. Ensure all text in DataScheme, DataHost, and DataPathPrefix is lowercase.

The IntentFilter registers your app to handle the callback URL. The LaunchMode.SingleTask ensures Android doesn’t create a new activity instance when the callback is invoked.

First, register the URL scheme in your Info.plist:

Info.plist

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleTypeRole</key>
        <string>None</string>
        <key>CFBundleURLName</key>
        <string>Auth0</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>YOUR_BUNDLE_IDENTIFIER</string>
        </array>
    </dict>
</array>

Then, set up your AppDelegate.cs:

AppDelegate.cs

using Auth0.OidcClient;
using Foundation;
using UIKit;

[Register("AppDelegate")]
public class AppDelegate : UIApplicationDelegate
{
    private Auth0Client auth0Client;

    public override bool FinishedLaunching(UIApplication application, NSDictionary launchOptions)
    {
        // Initialize Auth0 client
        auth0Client = new Auth0Client(new Auth0ClientOptions
        {
            Domain = "{yourDomain}",
            ClientId = "{yourClientId}"
        });

        return true;
    }

    public override bool OpenUrl(UIApplication application, NSUrl url,
        string sourceApplication, NSObject annotation)
    {
        ActivityMediator.Instance.Send(url.AbsoluteString);
        return true;
    }
}

Replace YOUR_BUNDLE_IDENTIFIER, {yourDomain}, and {yourClientId} with your actual values.

Store your Auth0 domain and client ID in a configuration file or app settings instead of hardcoding them for better maintainability.

Implement Login and Logout

Add methods to handle user authentication.Implement Login:

Authentication.cs

public async Task LoginAsync()
{
    var loginResult = await auth0Client.LoginAsync();

    if (!loginResult.IsError)
    {
        // Authentication successful
        var accessToken = loginResult.AccessToken;
        var idToken = loginResult.IdentityToken;
        var user = loginResult.User;

        // Store credentials and update UI
        Console.WriteLine($"Logged in as: {user.FindFirst("name")?.Value}");
    }
    else
    {
        // Handle authentication error
        Console.WriteLine($"Login error: {loginResult.Error}");
    }
}

Implement Logout:

Authentication.cs

public async Task LogoutAsync()
{
    var logoutResult = await auth0Client.LogoutAsync();

    if (logoutResult == BrowserResultType.Success)
    {
        // Clear stored credentials
        // Update UI to logged-out state
        Console.WriteLine("Logged out successfully");
    }
}

The LoginAsync() method launches the system browser (or Chrome Custom Tabs on Android) to display Auth0’s Universal Login page. After authentication, the user is redirected back to your app via the callback URL.

Add these methods to your MainActivity (Android) or a ViewController (iOS) and call them when users tap Login/Logout buttons.

Run your app

Build and run your application.

Visual Studio (Windows)
Visual Studio for Mac
.NET CLI

For Android:

Select an Android emulator or connected device from the device dropdown
Press F5 or click the Run button
The app will build, deploy, and launch

For iOS (requires Mac build host):

Connect to your Mac build host
Select an iOS simulator or device from the device dropdown
Press F5 or click the Run button

For Android:

Terminal

dotnet build -f net8.0-android
dotnet run -f net8.0-android

For iOS:

Terminal

dotnet build -f net8.0-ios
dotnet run -f net8.0-ios

Expected flow:

App launches with Login button
Tap Log In → Browser/Chrome Custom Tab opens → Complete authentication
Redirects back to your app automatically
User is authenticated successfully

On first run, iOS may prompt you to confirm opening the browser for authentication. This is normal and expected behavior.

CheckpointYou now have a fully functional Auth0 login experience in your .NET Android or iOS application. The app uses the system browser for secure authentication and automatically handles the callback flow.

Access User Information

After successful authentication, you can access user information from the login result.

Authentication Result

The LoginAsync() method returns a LoginResult object containing:

UserInfo.cs

var loginResult = await auth0Client.LoginAsync();

if (!loginResult.IsError)
{
    // Access tokens
    var accessToken = loginResult.AccessToken;
    var idToken = loginResult.IdentityToken;
    var refreshToken = loginResult.RefreshToken;

    // Access user claims
    var user = loginResult.User;
    var name = user.FindFirst("name")?.Value;
    var email = user.FindFirst("email")?.Value;
    var picture = user.FindFirst("picture")?.Value;

    Console.WriteLine($"Name: {name}");
    Console.WriteLine($"Email: {email}");
}

Iterate Through All Claims

To see all available user information:

UserClaims.cs

if (!loginResult.IsError)
{
    foreach (var claim in loginResult.User.Claims)
    {
        Console.WriteLine($"{claim.Type}: {claim.Value}");
    }
}

The exact claims returned depend on the scopes requested. For more information, see Using Scopes in the Auth0 OIDC Client documentation.

Request Custom Scopes

To request additional user information, specify scopes when creating the Auth0Client:

CustomScopes.cs

var auth0Client = new Auth0Client(new Auth0ClientOptions
{
    Domain = "{yourDomain}",
    ClientId = "{yourClientId}",
    Scope = "openid profile email offline_access read:posts"
});

Troubleshooting & Advanced

Common Issues & Solutions

Browser doesn’t redirect back to app

Solutions:

Verify callback URLs in Auth0 Dashboard exactly match your app’s package name/bundle identifier
Ensure callback URLs are in lowercase
Check that DataScheme, DataHost, and DataPathPrefix (Android) or URL scheme (iOS) match your configuration
Clean and rebuild your project

Authentication fails with “Invalid Callback URL” error

Fix:

Double-check that your callback URL in the Auth0 Dashboard matches the format:
- Android: packagename://yourdomain/android/packagename/callback
- iOS: bundleidentifier://yourdomain/ios/bundleidentifier/callback
Ensure the URL is in lowercase
Verify the Domain in your code matches the Domain in the Auth0 Dashboard

LoginAsync() hangs or never completes

Solutions:

Ensure the Intent filter (Android) or URL scheme (iOS) is properly configured
Check that OnNewIntent() (Android) or OpenUrl() (iOS) calls the ActivityMediator
Verify your app can open the system browser
Check network connectivity

Error: “Default App must use Token Endpoint Authentication Method ‘None’”

Fix:

Go to your Auth0 Application Settings in the Dashboard
Scroll to Application Properties
Set Application Type to Native
Set Token Endpoint Authentication Method to None
Click Save Changes

iOS: Browser doesn’t open

Solutions:

Verify Info.plist contains the correct URL scheme configuration
Check that OpenUrl() is implemented in AppDelegate
Ensure iOS deployment target is compatible with your Auth0 SDK version

Production Considerations

Security Best Practices

Secure Token Storage: Use platform-specific secure storage (Android Keystore, iOS Keychain) to store tokens
Token Refresh: Implement refresh token handling to maintain user sessions
Certificate Pinning: Consider certificate pinning for additional API security
ProGuard/Code Obfuscation: Add appropriate rules if using code obfuscation on Android

App Store Requirements

Privacy Policy: Ensure your app has a privacy policy that describes Auth0 usage
User Data Handling: Follow platform guidelines for handling user authentication data
Deep Linking: Test callback URL handling thoroughly across different scenarios
Network Requirements: Handle offline scenarios gracefully

Performance Optimization

Cache Auth0Client: Create a single instance and reuse it throughout your app
Lazy Loading: Initialize Auth0Client only when needed
Background Refresh: Implement background token refresh for long-running sessions

Advanced Configuration

Custom Scopes and Audience

Request specific scopes and set an audience for your API:

AdvancedAuth.cs

var auth0Client = new Auth0Client(new Auth0ClientOptions
{
    Domain = "{yourDomain}",
    ClientId = "{yourClientId}",
    Scope = "openid profile email offline_access read:posts write:posts",
    Audience = "https://myapi.example.com"
});

var loginResult = await auth0Client.LoginAsync();

Additional Parameters

Pass additional parameters to the authorization request:

ExtraParams.cs

var extraParameters = new Dictionary<string, string>
{
    { "prompt", "login" },
    { "ui_locales", "es" },
    { "custom_param", "value" }
};

var loginResult = await auth0Client.LoginAsync(extraParameters);

Refresh Tokens

Use refresh tokens to get new access tokens without user interaction:

RefreshToken.cs

var refreshResult = await auth0Client.RefreshTokenAsync(loginResult.RefreshToken);

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

To receive a refresh token, include the offline_access scope in your authentication request.

Platform-Specific Browser Configuration

Android - Use Chrome Custom Tabs with custom colors:

AndroidBrowser.cs

var auth0Client = new Auth0Client(new Auth0ClientOptions
{
    Domain = "{yourDomain}",
    ClientId = "{yourClientId}",
    Browser = new AndroidBrowser
    {
        ToolbarColor = Android.Graphics.Color.ParseColor("#FF6B35")
    }
}, this);

iOS - Use SFSafariViewController with custom presentation:

iOSBrowser.cs

var auth0Client = new Auth0Client(new Auth0ClientOptions
{
    Domain = "{yourDomain}",
    ClientId = "{yourClientId}",
    Browser = new ASWebAuthenticationSessionBrowser
    {
        PrefersEphemeralWebBrowserSession = false
    }
});

Next Steps

Configure Identity Providers

Add social login providers like Google, Facebook, and GitHub

Enable Multi-Factor Authentication

Add an extra layer of security with MFA

Attack Protection

Learn how to protect against brute force and bot attacks

Customize Login Experience

Customize the Universal Login page to match your brand

Single Page App

Regular Web App

Native/Mobile App

Backend/API

Add Login to Your .NET Android & iOS Application

Get Started

Access User Information

Authentication Result

Iterate Through All Claims

Request Custom Scopes

Troubleshooting & Advanced

Browser doesn’t redirect back to app

Authentication fails with “Invalid Callback URL” error

LoginAsync() hangs or never completes

Error: “Default App must use Token Endpoint Authentication Method ‘None’”

iOS: Browser doesn’t open

Security Best Practices

App Store Requirements

Performance Optimization

Custom Scopes and Audience

Additional Parameters

Refresh Tokens

Platform-Specific Browser Configuration

Next Steps

Configure Identity Providers

Enable Multi-Factor Authentication

Attack Protection

Customize Login Experience

Single Page App

Regular Web App

Native/Mobile App

Backend/API

​Get Started

​Access User Information

​Authentication Result

​Iterate Through All Claims

​Request Custom Scopes

​Troubleshooting & Advanced

​Browser doesn’t redirect back to app

​Authentication fails with “Invalid Callback URL” error

​LoginAsync() hangs or never completes

​Error: “Default App must use Token Endpoint Authentication Method ‘None’”

​iOS: Browser doesn’t open

​Security Best Practices

​App Store Requirements

​Performance Optimization

​Custom Scopes and Audience

​Additional Parameters

​Refresh Tokens

​Platform-Specific Browser Configuration

​Next Steps

Configure Identity Providers

Enable Multi-Factor Authentication

Attack Protection

Customize Login Experience

Get Started

Access User Information

Authentication Result

Iterate Through All Claims

Request Custom Scopes

Troubleshooting & Advanced

Browser doesn’t redirect back to app

Authentication fails with “Invalid Callback URL” error

LoginAsync() hangs or never completes

Error: “Default App must use Token Endpoint Authentication Method ‘None’”

iOS: Browser doesn’t open

Security Best Practices

App Store Requirements

Performance Optimization

Custom Scopes and Audience

Additional Parameters

Refresh Tokens

Platform-Specific Browser Configuration

Next Steps