Add Login to Your Android Application using the Auth0.Android SDK

Use AI to integrate Auth0

If you use an AI coding assistant like Claude Code, Cursor, or GitHub Copilot, you can add Auth0 authentication automatically in minutes using agent skills.Install:

npx skills add auth0/agent-skills --skill auth0-quickstart --skill auth0-android

Then ask your AI assistant:

Add Auth0 authentication to my Android app

Your AI assistant will automatically create your Auth0 application, fetch credentials, add the Auth0 Android SDK dependency, configure manifest placeholders, and implement login/logout flows. Full agent skills documentation →

Get Started

Create a new Android project

Create a new Android project for this quickstart.In Android Studio:

File → New → New Project
Select Phone and Tablet → Empty Activity template
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
Click Finish

This creates a modern Android app with Kotlin and Gradle Kotlin DSL, following current Android development best practices.

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.14.0")
}

Add manifest placeholders in your app-level build.gradle.kts:

app/build.gradle.kts

android {
    defaultConfig {
        // Add these manifest placeholders
        manifestPlaceholders += mapOf(
            "auth0Domain" to "@string/com_auth0_domain", // this will be set in the next step
            "auth0Scheme" to "https"
        )
    }
}

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.

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">{yourDomain}</string>
    <string name="com_auth0_client_id">YOUR_AUTH0_CLIENT_ID</string>
    <string name="com_auth0_scheme">https</string>
</resources>

Head to the Auth0 Dashboard
Click on Applications > Applications > Create Application
In the popup, 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
Replace {yourDomain} 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://{yourDomain}/android/PACKAGE_NAME/callback

Allowed Logout URLs:

https://{yourDomain}/android/PACKAGE_NAME/callback

Replace {yourDomain} 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.

When using the https scheme (as configured above), you must set up Android App Links so that Android routes the callback URL directly to your app instead of opening it in a browser. See the Configure Android App Links section under Troubleshooting & Advanced below.

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.getInstance(
            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.

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
            }
        })
}

MainActivity.kt

private fun login() {
    lifecycleScope.launch {
        try {
            val credentials = WebAuthProvider.login(auth0)
                .withScheme("https")
                .withScope("openid profile email offline_access")
                .await(this@MainActivity)
            // Save the credentials
            // User is authenticated
        } catch (exception: AuthenticationException) {
            // Handle error
        }
    }
}

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
            }
        })
}

MainActivity.kt

private fun logout() {
    lifecycleScope.launch {
        try {
            WebAuthProvider.logout(auth0)
                .withScheme("https")
                .await(this@MainActivity)
            // Clear saved credentials
            // User is logged out
        } catch (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.

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:

App launches with “Log In” button and shield icon
Tap “Log In” → Chrome Custom Tab opens → Complete login
Returns to app automatically
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

Common Issues & Solutions

Chrome Custom Tab doesn’t redirect back to app

Solutions:

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

App crashes: ‘Auth0 domain not found’

Fix:

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

Build errors with dependencies

Fix:

Update to latest Android Gradle Plugin in build.gradle (project level)
Sync project: File → Sync Project with Gradle Files
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

Configure Android App Links

Android App Links allow your app to designate itself as the default handler for Auth0 callback URLs, providing a more secure and seamless authentication experience. Without App Links, Android may show a disambiguation dialog asking the user to choose between your app and a browser.

App Links use verified https scheme callbacks. This is more secure than custom URL schemes, which can be subject to client impersonation attacks.

Get your signing certificate fingerprint

You need the SHA256 fingerprint of your app’s signing certificate. Run the following command in your terminal:

# For debug builds
keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android

# For release builds
keytool -list -v -keystore my-release-key.keystore

Copy the SHA256 fingerprint value from the output.

Configure in the Auth0 Dashboard

Go to Auth0 Dashboard > Applications > Applications, and select your application
Scroll to the bottom of the Settings page and select Show Advanced Settings
Select the Device Settings tab
Under Android, provide:
- App Package Name: Your applicationId (e.g., com.auth0.samples.android)
- SHA256 Cert Fingerprints: The fingerprint you copied above
Click Save Changes

Verify the configuration

Auth0 automatically generates the assetlinks.json file used by Android to verify your app. Test it by navigating to:

https://{yourDomain}/.well-known/assetlinks.json

You should see a JSON response containing your package name and certificate fingerprint:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "[YOUR_PACKAGE_NAME]",
    "sha256_cert_fingerprints": ["YOUR_SHA256_FINGERPRINT"]
  }
}]

The quickstart already uses https as the scheme in the manifest placeholders and WebAuthProvider calls, which is required for App Links. No code changes are needed if you followed the steps above.

To learn more, see the Enable Android App Links Support documentation and Android’s Verify App Links guide.

Use a custom URL scheme

If you cannot use Android App Links (for example, when targeting Android API versions below 23), you can configure a custom URL scheme instead.

Custom URL schemes are less secure than App Links because they can be subject to client impersonation attacks. Use App Links whenever possible.

Update the auth0Scheme manifest placeholder in your app/build.gradle.kts:

app/build.gradle.kts

android {
    defaultConfig {
        manifestPlaceholders += mapOf(
            "auth0Domain" to "@string/com_auth0_domain",
            "auth0Scheme" to "myapp" // Use a unique custom scheme
        )
    }
}

Update the Allowed Callback URLs and Allowed Logout URLs in your Auth0 Dashboard application settings to use the custom scheme:

myapp://{yourDomain}/android/PACKAGE_NAME/callback

Pass the custom scheme when calling WebAuthProvider:

MainActivity.kt

WebAuthProvider.login(auth0)
    .withScheme("myapp")
    .withScope("openid profile email offline_access")
    .start(this, callback)

Custom schemes can only contain lowercase letters.

Production Deployment

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

Advanced Android Integration

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"
    ... />

Single Page App

Regular Web App

Native/Mobile App

Backend/API

Add Login to Your Android Application using the Auth0.Android SDK

Get Started

Troubleshooting & Advanced

Chrome Custom Tab doesn’t redirect back to app

App crashes: ‘Auth0 domain not found’

Build errors with dependencies

Authentication cancelled by user

No compatible browser error

Get your signing certificate fingerprint

Configure in the Auth0 Dashboard

Verify the configuration

App Store Preparation

Security Considerations

Enhanced Credential Security

Custom Scopes and Audience

Network Configuration

Single Page App

Regular Web App

Native/Mobile App

Backend/API

​Get Started

​Troubleshooting & Advanced

​Chrome Custom Tab doesn’t redirect back to app

​App crashes: ‘Auth0 domain not found’

​Build errors with dependencies

​Authentication cancelled by user

​No compatible browser error

​Get your signing certificate fingerprint

​Configure in the Auth0 Dashboard

​Verify the configuration

​App Store Preparation

​Security Considerations

​Enhanced Credential Security

​Custom Scopes and Audience

​Network Configuration

Get Started

Troubleshooting & Advanced

Chrome Custom Tab doesn’t redirect back to app

App crashes: ‘Auth0 domain not found’

Build errors with dependencies

Authentication cancelled by user

No compatible browser error

Get your signing certificate fingerprint

Configure in the Auth0 Dashboard

Verify the configuration

App Store Preparation

Security Considerations

Enhanced Credential Security

Custom Scopes and Audience

Network Configuration