Lock.Android: Get Started

Lock for Android can integrate into your native Android apps to provide a beautiful way to log your users in and to sign them up in your app. It provides support for social identity providers such as Facebook, Google, or X, as well as enterprise providers such as Active Directory.

Check out the Lock.Android repository on GitHub.

To use Lock's UI or your own UI via the Auth0.Android library the minimum required Android API level is 21+ and Java version 8 or above. You will also require an Auth0 application of type "Native".

Here’s what you need in build.gradle to target Java 8 byte code for the Android and Kotlin plugins respectively.

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }

    kotlinOptions {
        jvmTarget = '1.8'
    }
}

Lock is available in Maven Central. To start using Lock add these lines to your build.gradle dependencies file:

implementation 'com.auth0.android:lock:3.+'

You can check for the latest version on the repository Readme or in Maven.

After adding your Gradle dependency, remember to sync your project with Gradle files.

You need to fill in a few settings in your Auth0 Dashboard before you get started.

Head over to your Auth0 Dashboard and go to the application's settings. Add the following URL to the application's Allowed Callback URLs:

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

Replace {yourAppPackageName} with your actual application's package name, available in your app/build.gradle file as the applicationId value.

Android applications need to be signed before they can be installed on a device. For this purpose, the Android Studio IDE the first time it runs generates a default "Android Debug Keystore" that it will use to sign development builds. This Keystore will probably be different for your production build, as it will be used to identify you as the developer.

When using the Web Authentication feature (i.e. social connections), Lock will be set up by default to attempt to use Android App Links. This requires an additional setting in the Auth0 application's dashboard. Use our Android Keystores and Key Hashes Guide to complete this step.

The following instructions discuss implementing Classic Lock for Android. If you specifically are looking to implement Passwordless Lock for Android, see Lock.Android: Passwordless.

In your app/build.gradle file add the Manifest Placeholders for the Auth0 Domain and the Auth0 Scheme properties, which are going to be used internally by the library to register an intent-filter that captures the authentication result.

plugins {
    id "com.android.application"
    id "kotlin-android"
}

android {
    compileSdkVersion 30
    defaultConfig {
        applicationId "com.auth0.samples"
        minSdkVersion 21
        targetSdkVersion 30
        // ...

        // ---> Add the next line
        manifestPlaceholders = [auth0Domain: "@string/com_auth0_domain", auth0Scheme: "https"]
        // <---
    }
}

It's good practice to add these values to the strings.xml file as string resources that can be referenced later from the code. This guide will follow that practice.

<resources>
    <string name="com_auth0_client_id">{yourClientId}</string>
    <string name="com_auth0_domain">{yourDomain}</string>
</resources>

In the activity where you plan to invoke Lock, create an instance of Auth0 with your application's information. The easiest way to create it is by passing an Android Context. This will use the values previously defined in the strings.xml file. For this to work, the string resources must be defined using the same keys as the ones listed above.

val account = Auth0(context)

Declare an AuthenticationCallback implementation that will handle user authentication events. The Credentials object returned in successful authentication scenarios will contain the tokens that your application or API will end up consuming. See Tokens for more specifics.

private val callback = object : AuthenticationCallback() {
    override fun onAuthentication(credentials: Credentials) {
        // Authenticated
    }

    override fun onError(error: AuthenticationException) {
        // Exception occurred
    }
}

Prepare a new Lock instance by using the Builder class to configure it. Provide the account details and the callback implementation declared above. Values like audience, scope, and available connections can be configured here.

When done, build the Lock instance. This instance is meant to be reused and must be disposed of when it is no longer needed. A good place to do this is in your activity's onDestroy method.

// This activity will show Lock
class MyActivity : AppCompatActivity() {

    private lateinit var lock: Lock

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val account = Auth0(this)
        // Instantiate Lock once
        lock = Lock.newBuilder(account, callback)
            // Customize Lock
            .build(this)
    }

    override fun onDestroy() {
        super.onDestroy()
        // Important! Release Lock and its resources
        lock.onDestroy(this)
    }

    private val callback = object : AuthenticationCallback() {
        override fun onAuthentication(credentials: Credentials) {
            // Authenticated
        }

        override fun onError(error: AuthenticationException) {
            // An exception occurred
        }
    }
}

Finally, launch the Lock widget from inside your activity.

startActivity(lock.newIntent(this))

That's it! Lock will handle the rest for you.

The Callback URI scheme used in this article and by default by Lock is https. This works best for Android Marshmallow (API 23) or newer if you're using Android App Links, but in previous Android versions, this may show the intent chooser dialog prompting the user to chose either your application or the browser to resolve the intent. This is called the "disambiguation dialog". You can change this behavior by using a custom unique scheme so that the OS opens the link directly with your app.

1. Update the auth0Scheme Manifest Placeholder value in the app/build.gradle file or directly in the Intent Filter definition in the AndroidManifest.xml file by changing the existing scheme to the new one.

2. Update the "Allowed Callback URLs" in your Auth0 Dashboard Application's settings to match URLs that begin with the new scheme.

3. Call withScheme() when configuring Lock with the builder, passing the scheme you want to use.

For a full list of Lock's configuration options, check out Lock.Android: Configuration.

For descriptions of common error messages, check out the Error Messages page. Also, if your callback receives an AuthenticationException you can check source to learn how to identify each error scenario.

• Lock.Android: Custom Theming
• Lock.Android: Configuration
• Lock.Android: Custom Fields at Signup
• Lock.Android Internationalization
• Logout