Skip to main content

​
Get Started

1

Create a new Android project

Create a new Android project for this quickstart.In Android Studio:
  1. File → New → New Project
  2. Select Phone and Tablet → Empty Activity template
  3. Configure your project:
    • Name: Auth0-Android-Sample
    • Package name: com.auth0.samples.android
    • Language: Kotlin
    • Minimum SDK: API 24 (Android 7.0)
    • Build configuration language: Kotlin DSL
  4. Click Finish
This creates a modern Android app with Kotlin and Gradle Kotlin DSL, following current Android development best practices.
2

Add Auth0 SDK via Gradle

Add the Auth0 Android SDK to your project using Gradle.Update your app-level build.gradle.kts file:
app/build.gradle.kts
dependencies {   
    // Auth0 SDK
    implementation("com.auth0.android:auth0:3.10.0")
}
Add Internet permission to AndroidManifest.xml:
app/src/main/AndroidManifest.xml
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">
    <uses-permission android:name="android.permission.INTERNET" />
</manifest>
The Auth0 SDK automatically handles dependency resolution and includes secure token storage capabilities.
3

Setup your Auth0 App

Next up, you need to create a new app on your Auth0 tenant and add the configuration to your Android project.First, prepare your app/src/main/res/values/strings.xml file with placeholder values:
app/src/main/res/values/strings.xml
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="com_auth0_domain">YOUR_AUTH0_DOMAIN</string>
    <string name="com_auth0_client_id">YOUR_AUTH0_CLIENT_ID</string>
    <string name="com_auth0_scheme">https</string>
</resources>
  1. Head to the Auth0 Dashboard
  2. Click on Applications > Applications > Create Application
  3. In the popup, enter a name for your app, select Native as the app type and click Create
  4. Switch to the Settings tab on the Application Details page
  5. Replace YOUR_AUTH0_DOMAIN and YOUR_AUTH0_CLIENT_ID in the strings.xml file with the Domain and Client ID values from the dashboard
Finally, on the Settings tab of your Application Details page, configure the following URLs:Allowed Callback URLs:
https://YOUR_AUTH0_DOMAIN/android/PACKAGE_NAME/callback
Allowed Logout URLs:
https://YOUR_AUTH0_DOMAIN/android/PACKAGE_NAME/callback
Replace YOUR_AUTH0_DOMAIN with your actual Auth0 domain (e.g., dev-abc123.us.auth0.com).
Allowed Callback URLs are a critical security measure to ensure users are safely returned to your application after authentication. Without a matching URL, the login process will fail, and users will be blocked by an Auth0 error page instead of accessing your app.Allowed Logout URLs are essential for providing a seamless user experience upon signing out. Without a matching URL, users will not be redirected back to your application after logout and will instead be left on a generic Auth0 page.The URL scheme includes your package name (com.auth0.samples.android) to ensure the callback is routed to your specific app.
Important: Ensure the package name in your callback URLs matches your applicationId in build.gradle.kts. If authentication fails, verify these values are identical.
4

Initialize the Auth0 SDK

Create an Auth0 instance in your Activity to communicate with Auth0.In your MainActivity.kt:
MainActivity.kt
import com.auth0.android.Auth0
import com.auth0.android.authentication.AuthenticationException
import com.auth0.android.callback.Callback
import com.auth0.android.provider.WebAuthProvider
import com.auth0.android.result.Credentials

class MainActivity : ComponentActivity() {
    private lateinit var auth0: Auth0

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        // Initialize Auth0
        auth0 = Auth0(
            getString(R.string.com_auth0_client_id),
            getString(R.string.com_auth0_domain)
        )
    }
}
The Auth0 instance is initialized with your client ID and domain from the strings.xml file you configured earlier. This instance will be used for all authentication operations.
5

Implement Login and Logout

Implement Login: Use WebAuthProvider to launch the universal login page.Add these methods to your MainActivity:
  • Kotlin Callback
  • Coroutine
MainActivity.kt
private fun login() {
    WebAuthProvider.login(auth0)
        .withScheme("https")
        .withScope("openid profile email offline_access")
        .start(this, object : Callback<Credentials, AuthenticationException> {
            override fun onSuccess(credentials: Credentials) {
                // Save the credentials
                // User is authenticated
            }

            override fun onFailure(exception: AuthenticationException) {
                // Handle error cases
            }
        })
}
Implement Logout: Use WebAuthProvider to clear the user’s session.
  • Kotlin Callback
  • Coroutine
MainActivity.kt
private fun logout() {
    WebAuthProvider.logout(auth0)
        .withScheme("https")
        .start(this, object : Callback<Void?, AuthenticationException> {
            override fun onSuccess(result: Void?) {
                // Clear saved credentials
                // User is logged out
            }

            override fun onFailure(exception: AuthenticationException) {
                // Handle error
            }
        })
}
The login() and logout() methods should be called when the user taps the respective buttons in your UI. The code uses this (referring to the Activity) as the context parameter, which is required for WebAuthProvider to launch Chrome Custom Tabs and handle the authentication flow.
6

Run your app

Build and run your Android application.In Android Studio:
# Sync project with Gradle files (or use Android Studio's "Sync Now")
./gradlew clean build

# Build and install on connected device or emulator
./gradlew installDebug

# Or run directly from Android Studio
# Click the "Run" button or press Shift+F10
Expected flow:
  1. App launches with “Log In” button and shield icon
  2. Tap “Log In” → Chrome Custom Tab opens → Complete login
  3. Returns to app automatically
  4. Success!!
Android will show a browser selection dialog if multiple browsers are installed. Chrome Custom Tabs provide the best user experience for Auth0 authentication.
CheckpointYou should now have a fully functional Auth0 login experience running on your Android device or emulator. The app uses Chrome Custom Tabs for secure authentication and automatically stores credentials.

​
Troubleshooting & Advanced

​
Chrome Custom Tab doesn’t redirect back to app

Solutions:
  1. Check Allowed Callback URLs in Auth0 Dashboard match your applicationId exactly
  2. Verify manifest placeholders in build.gradle.kts are correct
  3. Ensure both HTTPS and custom scheme URLs are configured
  4. Clean and rebuild: Build → Clean Project → Rebuild Project

​
App crashes: ‘Auth0 domain not found’

Fix:
  1. Check com_auth0_domain and com_auth0_client_id values are correct
  2. Ensure no typos in domain format (should not include https://)

​
Build errors with dependencies

Fix:
  1. Update to latest Android Gradle Plugin in build.gradle (project level)
  2. Sync project: File → Sync Project with Gradle Files
  3. Clean build: ./gradlew clean build

​
Authentication cancelled by user

Handle gracefully in your error callback:
override fun onFailure(exception: AuthenticationException) {
    when {
        exception.isAuthenticationCanceled -> 
            showMessage("Login was cancelled")
        exception.isBrowserAppNotAvailable -> 
            showMessage("No browser available")
        else -> 
            showMessage("Login failed: ${exception.getDescription()}")
    }
}

​
No compatible browser error

  • Install Chrome or another modern browser on your device/emulator
  • Enable Chrome Custom Tabs for better user experience
  • Test on real device with Chrome installed

​
App Store Preparation

  • Configure Android App Links for seamless authentication
  • Test on multiple Android versions and screen sizes
  • Implement proper error handling for network failures
  • Add ProGuard rules for Auth0 SDK if using code obfuscation
  • Follow Google Play Store policies for authentication flows

​
Security Considerations

  • Use SecureCredentialsManager for production credential storage
  • Implement certificate pinning for additional API security
  • Consider Android Keystore for enhanced credential protection
  • Enable biometric authentication for sensitive operations

​
Enhanced Credential Security

Implement biometric authentication for credential access:
AuthenticationManager.kt
class AuthenticationManager(private val context: Context) {
    
    private val credentialsManager: SecureCredentialsManager
    
    init {
        val authentication = AuthenticationAPIClient(auth0)
        val storage = SharedPreferencesStorage(context)
        credentialsManager = SecureCredentialsManager(context, authentication, storage)
        
        // Enable biometric authentication
        credentialsManager.requireAuthentication(
            context as FragmentActivity,
            REQUEST_CODE_BIOMETRIC,
            "Biometric Authentication",
            "Please authenticate to access your account"
        )
    }
    
    companion object {
        private const val REQUEST_CODE_BIOMETRIC = 321
    }
}

​
Custom Scopes and Audience

Request specific scopes and audience for your API:
AuthenticationManager.kt
fun login() {
    WebAuthProvider.login(auth0)
        .withScheme("https")
        .withScope("openid profile email offline_access read:posts")
        .withAudience("https://myapi.example.com")
        .withParameter("prompt", "login")
        .start(context as MainActivity, loginCallback)
}

​
Network Configuration

Handle network security and certificate pinning:
app/src/main/res/xml/network_security_config.xml
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config>
        <domain includeSubdomains="true">your-auth0-domain.auth0.com</domain>
        <pin-set>
            <pin digest="SHA-256">AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=</pin>
        </pin-set>
    </domain-config>
</network-security-config>
Add to AndroidManifest.xml:
<application
    android:networkSecurityConfig="@xml/network_security_config"
    ... />