Auth0.OidcClient.AndroidX

Agent instruction: Before providing SDK setup instructions, fetch the latest release version by running:

bash

gh api repos/auth0/auth0-oidc-client-net/releases --jq '[.[] | select(.tag_name | startswith("androidx-")) | .tag_name | ltrimstr("androidx-")] | .[0]'

Use the returned version in all dependency lines instead of any hardcoded version below.

• .NET 8.0 SDK or later
• Visual Studio 2022 (17.8+) with .NET Android workload, or JetBrains Rider
• Android SDK API 21+ (minimum), API 34+ recommended for net9.0-android
• Auth0 account with a Native application configured
• Node.js 20+ (for Auth0 CLI automated setup)

Agent instruction: Before starting, examine the user's project:

1. Identify the .NET version from the

   .csproj

   file (

   TargetFramework

   )
2. Check for existing authentication implementations — search for existing login/logout handlers and hook into them if found (reuse existing UI elements like login buttons rather than creating duplicates)
3. Note the project's namespace and package name from the

   .csproj

   or

   AndroidManifest.xml

4. Look for existing

   Auth0Client

   or

   Auth0ClientOptions

   usage to avoid duplicate configuration

1. Install SDK:

   dotnet add package Auth0.OidcClient.AndroidX

2. Configure Auth0: See Setup Guide for automatic or manual configuration.
3. Integrate authentication: Add

   Auth0Client

   instantiation, configure the

   IntentFilter

   on your Activity, and wire login/logout to UI actions.
4. Handle callback: Override

   OnNewIntent

   and call

   ActivityMediator.Instance.Send(intent.DataString)

   to complete the authentication flow.
5. Build and verify:

   dotnet build

Agent instruction: When writing the Auth0Client configuration:

• Pass

  this

  (the Activity) as the second argument to

  Auth0Client

  constructor.
• Always set

  Scope = "openid profile email offline_access"

  — the

  offline_access

  scope is required to receive refresh tokens, enabling silent token renewal without re-prompting the user.
• The callback URL format is

  YOUR_ANDROID_PACKAGE_NAME://YOUR_AUTH0_DOMAIN/android/YOUR_ANDROID_PACKAGE_NAME/callback

  — all lowercase.
• The

  DataScheme

  in the

  IntentFilter

  must be lowercase or Android will not receive callbacks.
• Set

  LaunchMode = LaunchMode.SingleTask

  on the Activity to prevent duplicate instances. Do NOT use

  SingleTop

  — it does not correctly handle the callback redirect and will create duplicate Activity instances.
• The Activity should either extend

  Auth0ClientActivity

  OR manually override

  OnNewIntent

  and call

  ActivityMediator.Instance.Send(intent.DataString)

  .
• Store tokens securely: After successful login, persist

  AccessToken

  and

  RefreshToken

  using

  SecureStorage

  (MAUI/Essentials) or

  EncryptedSharedPreferences

  (AndroidX Security — requires

  dotnet add package Xamarin.AndroidX.Security.SecurityCrypto

  ). Never store tokens in plain

  SharedPreferences

  or in-memory variables only.

After writing configuration and code, verify the build succeeds:

bash

dotnet build

If the build fails, attempt to fix the issue. After 5-6 failed attempts, ask the user for help.

LoginAsync()

1. Constructs the

   /authorize

   URL with PKCE parameters
2. Opens Chrome Custom Tabs with the authorization URL
3. After authentication, Auth0 redirects to the native callback URL
4. The Android system matches the URL scheme and delivers it to your Activity via

   OnNewIntent

5. ActivityMediator

   completes the token exchange

YOUR_ANDROID_PACKAGE_NAME://YOUR_AUTH0_DOMAIN/android/YOUR_ANDROID_PACKAGE_NAME/callback

YOUR_ANDROID_PACKAGE_NAME

com.mycompany.myapplication

com.mycompany.myapp://tenant.us.auth0.com/android/com.mycompany.myapp/callback

Note: Some Auth0 native SDKs use

https://{domain}/android/{package}/callback

as the callback URL format. The .NET Android SDK uses the package name as the URL scheme instead.

1. Registered in Auth0 Dashboard under Allowed Callback URLs and Allowed Logout URLs
2. Matched by the

   IntentFilter

   attributes (

   DataScheme

   ,

   DataHost

   ,

   DataPathPrefix

   ) on your Activity

• Auth0.OidcClient.AndroidX

  package installed (latest stable version)

• Auth0Client

  configured with Domain, ClientId, and

  Scope = "openid profile email offline_access"

• IntentFilter

  configured on Activity with correct DataScheme, DataHost, DataPathPrefix

• LaunchMode = LaunchMode.SingleTask

  set on Activity

• OnNewIntent

  handled with

  ActivityMediator.Instance.Send(intent.DataString)

• Callback URL added to Auth0 Dashboard Allowed Callback URLs and Allowed Logout URLs
• Tokens stored securely (SecureStorage or EncryptedSharedPreferences)
• Login/logout flow working
• Build succeeds with no errors

• Setup Guide — Auth0 tenant configuration, SDK installation, IntentFilter setup
• Integration Patterns — Login/logout flows, token access, user profile, error handling
• API Reference & Testing — Full

  Auth0ClientOptions

  reference, claims, testing checklist, troubleshooting

Agent instruction: Remind the user to test on a physical device in addition to emulators. Some WebAuth behaviors (Chrome Custom Tabs, URL scheme interception) may differ on physical devices vs. emulators. Test the full login → callback → token flow on real hardware before shipping.

• Login flow: Chrome Custom Tab opens → authenticate → returns to app
• Callback:

  OnNewIntent

  fires with correct intent data
• Logout flow: Browser opens → session cleared → returns to app
• Cancel: User presses back → app handles

  UserCancel

  gracefully

• auth0-maui — .NET MAUI cross-platform apps (iOS + Android + Windows)
• auth0-net-ios — .NET iOS-only apps
• auth0-android — Android-native Kotlin apps
• auth0-aspnetcore-authentication — ASP.NET Core server-side web apps
• auth0-aspnetcore-api — ASP.NET Core Web API with JWT validation

• .NET Android & iOS Quickstart
• GitHub Repository
• NuGet Package — Auth0.OidcClient.AndroidX
• SDK API Documentation