Lock for Android v2
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 Twitter, as well as enterprise providers such as Active Directory.
Get started using Lock for Android below, or if you're looking for a specific document beyond basic setup of Lock, try the listing of next steps for working with Lock for Android.
To use Lock's UI or your own UI via the Auth0.Android library the minimum required Android API level is 15+.
After adding your Gradle dependency, make sure to 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"
Keystores and key hashes
You will need a Keystore for signing your Android app. If you already have one, you can continue and skip the instructions about acquiring one.
During development, you can use the default "android debug keystore" to sign your application. For instructions on how to generate the key hashes using this keystore, use our Android Keystores and Key Hashes Guide.
For a release keystore, replace the file, alias, store password and key password with your own values.
The following instructions discuss implementing Lock for Android. If you specifically are looking to implement Passwordless Lock for Android, read the Passwordless Authentication with Lock for Android page.
Configuring the SDK
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 callback URI.
It's a good practice to define reusable resources like
@string/com_auth0_domain but you can also hard code the value to
YOUR_DOMAIN in the file.
Next, modify the
AndroidManifest.xml file. Add the
android.permission.INTERNET permission to allow Lock to make requests to the Auth0 API.
In case you are using an older version of Lock the intent-filter must be added to the
LockActivity by you:
- Make sure the
LockActivitylaunchMode is declared as
singleTaskor the result won't come back after the authentication.
- Also note that for the time being,
LockActivitycan't be launched by calling
Auth0 instance to hold your account details, which are the
AUTH0_CLIENT_ID and the
OIDC Conformant Mode
It is strongly encouraged that Lock be used in OIDC Conformant mode. When this mode is enabled, it will force Lock to use Auth0's current authentication pipeline and will prevent it from reaching legacy endpoints. By default is
For more information, please see the OIDC adoption guide.
You'll also need a
LockCallback implementation. Here is an example which will notify you about Authentication events (logins).
To create a new
Lock instance and configure it, use the
Lock.Builder class. Call the static method
Lock.newBuilder(Auth0, LockCallback), passing the account details and the callback implementation, and start configuring the Options as you need. After you're done, build the Lock instance and use it to start the
To ensure a response that complies with OpenID Connect (OIDC), you must either request an
audience or enable the OIDC Conformant switch in your Auth0 dashboard under
Application / Settings / Advanced OAuth. You can read more about this here.
This is an example of what your
Activity should look:
Remember to notify Lock's instance when your activity calls the
OnDestroy method, as it helps to keep the state.
Lock from inside your activity.
That's it! Lock will handle the rest for you.
The callback URI scheme used in this article 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. You can change this behavior by using a custom unique scheme so that the OS opens the link directly with your app.
Do so by updating the
app/build.gradle file and changing the
auth0Scheme value. Then go to your application's dashboard and update the "Allowed callback URL" value to match the new scheme. Now call
withScheme() in the Lock.Builder and pass the custom value so that Lock requests the correct redirect URI.
Implementing Passwordless authentication with Lock for Android
For instructions on how to implement Passwordless authentication with Lock for Android, please see the Passwordless Guide.
The proguard rules should be applied automatically if your application is using
minifyEnabled = true. If you want to include them manually check the proguard directory. By default you should at least use the following files:
By default you should at least use the following files:
As this library depends on
Auth0.Android, you should keep the files up to date with the proguard rules defined in that repository.
For a full list of Lock's configuration options, check out the Lock for Android Configuration Reference. Also, for users of v1 migrating to v2, read the Migration Guide to see what options have changed.
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.