Lock.Android: Passwordless

Lock Passwordless authenticates users by sending them an Email or SMS with a one-time password that the user must enter and confirm to be able to log in, similar to how WhatsApp authenticates. This article will explain how to send a CODE using the Lock.Android library.

You can achieve a similar result by sending a link that the user can click to finish the passwordless authentication automatically, but a few more configuration steps are involved.

In order to be able to authenticate the user, your application must have the Email/SMS connection enabled and configured in your Auth0 Dashboard.

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 is good practice to add these values to the strings.xml file as string resources that can be referenced later from the code.

<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, among others, 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.

The sample below calls the useCode() method to make Lock send a CODE to the user's email or phone number.

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

    private lateinit var lock: PasswordlessLock

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

        val account = Auth0(this)
        // Instantiate Lock once
        lock = PasswordlessLock.newBuilder(account, callback)
            .useCode()
            // 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 PasswordlessLock widget from inside your activity.

startActivity(lock.newIntent(this))

Depending on which passwordless connections are enabled, Lock will send the CODE in an Email or SMS. The 'email' connection is selected first if available. Then the user must input the CODE in the confirmation step. If the value equals the one the server is expecting, the authentication will be successful.