Auth0 Android

Auth0 Android Integration

Add authentication to Android applications using com.auth0.android:auth0.

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

> gh api repos/auth0/Auth0.Android/releases/latest --jq '.tag_name'
> 

Prerequisites

When NOT to Use

Quick Start Workflow

1. Install SDK: Add the Auth0 Android SDK dependency to your build.gradle:

   implementation 'com.auth0.android:auth0:{LATEST_VERSION}'
   

2. Configure Auth0:

> Agent instruction: Check whether the user prompt already includes both Auth0 Client ID and Domain. > - If both are provided, proceed directly to Manual Setup in Setup Guide using those values. > - If either is missing, you MUST ask the user BEFORE writing any code or files: > - Question: "How would you like to configure Auth0 for this project?" > - Options: "Automatic setup (Recommended) — Auth0 CLI creates the app and writes credentials to strings.xml" / "Manual setup — I'll provide my Client ID and Domain" > > Then follow Setup Guide for the chosen path. > Do NOT proceed to step 3 until Auth0 credentials are confirmed.

3. Initialize: Create an Auth0 account instance:

   import com.auth0.android.Auth0
   val account = Auth0.getInstance(context)
   

4. Add Auth UI: Implement login and logout with Web Auth:

> Agent instruction: Before adding new UI elements, search the project for existing click handlers for login, logout, sign-in, or sign-out buttons (e.g., loginButton, signInButton, logoutButton, signOutButton, or setOnClickListener with auth-related naming). If existing handlers are found, hook the Auth0 code into them without modifying the existing UI. Only create new buttons if no existing handlers are found.

Login:

   import com.auth0.android.Auth0
   import com.auth0.android.authentication.AuthenticationAPIClient
   import com.auth0.android.authentication.storage.SecureCredentialsManager
   import com.auth0.android.authentication.storage.SharedPreferencesStorage
   import com.auth0.android.callback.Callback
   import com.auth0.android.authentication.AuthenticationException
   import com.auth0.android.provider.WebAuthProvider
   import com.auth0.android.result.Credentials
   val account = Auth0.getInstance(context)
   val authentication = AuthenticationAPIClient(account)
   val storage = SharedPreferencesStorage(context)
   val credentialsManager = SecureCredentialsManager(context, authentication, storage)
   WebAuthProvider.login(account)
       .withScheme(getString(R.string.com_auth0_scheme))
       .withScope("openid profile email offline_access")
       .start(this, object : Callback {
           override fun onSuccess(result: Credentials) {
               // User authenticated
               val idToken = result.idToken
               val accessToken = result.accessToken
               // Store credentials securely
               credentialsManager.saveCredentials(result)
           }
           override fun onFailure(error: AuthenticationException) {
               // Handle authentication failure
               Log.e("Auth0", "Authentication failed", error)
           }
       })
   

Logout:

   WebAuthProvider.logout(account)
       .withScheme(getString(R.string.com_auth0_scheme))
       .start(this, object : Callback {
           override fun onSuccess(result: Void) {
               // User logged out
           }
           override fun onFailure(error: AuthenticationException) {
               Log.e("Auth0", "Logout failed", error)
           }
       })
   

5. Build & Verify:

> Agent instruction: After completing the integration, build the project to verify it compiles successfully: >

   > ./gradlew assembleDebug
   > 

The callback URL must match your Auth0 application settings: {SCHEME}://{YOUR_AUTH0_DOMAIN}/android/{YOUR_APP_PACKAGE_NAME}/callback

Detailed Documentation

Common Mistakes

| Mistake | Fix | |---------|-----| | App type not set to Native in Auth0 Dashboard | Create a Native application type in your Auth0 tenant. The Android SDK requires Native app configuration, not Machine-to-Machine or other types. | | Missing callback URL in Allowed Callback URLs | Add {SCHEME}://{YOUR_AUTH0_DOMAIN}/android/{YOUR_APP_PACKAGE_NAME}/callback to your Auth0 application's Allowed Callback URLs setting, where {SCHEME} matches com_auth0_scheme in strings.xml (e.g., demo by default). | | Missing | Add the INTERNET permission to AndroidManifest.xml. The SDK requires network access for authentication. | | Custom scheme in lowercase | Android requires scheme names to be lowercase. Use https (recommended) or lowercase custom scheme like myapp://callback. | | Forgetting .validateClaims() on direct auth calls | Always call .validateClaims() when using AuthenticationAPIClient directly (for database, passwordless, or API login). Web Auth validates automatically. | | Storing tokens in SharedPreferences without encryption | Use SecureCredentialsManager to store credentials. Never store tokens manually in plain text. The manager encrypts tokens at rest. | | Missing manifest placeholders | Add manifestPlaceholders = [auth0Domain: "@string/com_auth0_domain", auth0Scheme: "@string/com_auth0_scheme"] to your build.gradle defaultConfig block. |

Related Skills

Quick Reference

Core Classes

| Class | Purpose | |-------|---------| | Auth0 | Entry point for SDK, holds app credentials | | WebAuthProvider | OAuth 2.0 login/logout via browser | | AuthenticationAPIClient | Direct API calls (database login, passwordless, MFA) | | SecureCredentialsManager | Secure storage and retrieval of credentials | | Credentials | User tokens and expiration |

Common Use Cases

References