Appwrite 0.10 recently released and along with it came a new authentication method; Magic URL. Using this new method, a user is able to create an account from a link sent to their e-mail, without providing a password.

This feature is especially useful if you want to provide a password-less authentication process for your application.

⚙️ Setup

Let's learn how we can add Magic URL Authentication to an Android Application using the Appwrite Android SDK. The same can be done with the Appwrite Web SDK or Flutter SDK. As this feature needs to send an email, you must properly set up SMTP service in Appwrite. If you have not already, you can follow this guide to set up SMTP in your Appwrite server.

👷 Setup Appwrite's Android SDK

Appwrite's Android SDK is hosted on Maven Central, so you'll first need to add the mavenCentral() repository to your project's build.gradle file (if it's not already present).

allprojects {
    repositories {
        google()
        mavenCentral()
    }
}

Then add the dependency to your app's build.gradle(.kts) file.

implementation("io.appwrite:sdk-for-android:0.2.0")

The next step is to initialize your SDK Client and Account service with your project ID which can be found in your project settings page:

val client = Client(context)
        .setEndpoint("http://localhost/v1") // Your Appwrite Endpoint
        .setProject("[YOUR_PROJECT_ID]") // Your Appwrite Project ID

val account = Account(client)

Finally, add the following activity to your AndroidManifest.xml file to handle the redirection after handling the login with magic URL as follows:

<activity android:name="io.appwrite.views.CallbackActivity" >
    <intent-filter android:label="android_web_auth">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="appwrite-callback-[PROJECT_ID]"  />
    </intent-filter>
</activity>

🎩 Create a Magic URL

Once your SDK is set up, you can create a new magic URL using the function createMagicURLSession(). This function accepts an e-mail address and an optional redirect URL as arguments.

// Initiate the Magic URL login
val response = account.createMagicURLSession("email@example.com")
val json = response.body?.string()

If the createMagicURLSession() method completes without error, the request sends the user an email with a URL containing a secret key for the next step. When the user clicks the link, they are redirected back to the URL you provided with the secret key and userId values attached to the URL query string. This link is valid for 1 hour. If the e-mail passed did not belong to any existing user - this request will also create a user for the passed e-mail address.

For mobile apps, you don't need to provide a redirect URL as your Appwrite instance will automatically handle the completion and redirection, and you should be redirected back to your app. For this to work you need to be able to access your Appwrite instance from your mobile; it's best to host it somewhere with a proper domain. Otherwise services such as ngrok can be used to tunnel your localhost to a temporary domain.

🔐 Login with a Magic URL

If you didn't provide a redirect URL when creating your magic URL, you can skip this step.

If you do want to handle the completion of magic URL session and redirection yourself, you need to build a web app that can handle the process.

You can use the updateMagicURLSession() method and call it with the secret and userId values from the URL's query string.

Please note that in order to avoid a Redirect Attack the only valid redirect URLs are the ones from domains you have set when adding your platforms in the console interface.

 const urlParams = new URLSearchParams(window.location.search);
 const userId = urlParams.get('userId');
 const secret = urlParams.get('secret');

 let promise = appwrite.account.updateMagicURLSession(userId, secret);

 promise.then(function (response) {
     console.log(response); // Success
 }, function (error) {
     console.log(error); // Failure
 });

If the updateMagicURLSession() succeeded, the user is now logged in. Note that once a link is used, it cannot be used again.

🏁 Conclusion

We hope you will enjoy this new feature of Appwrite and hope this will be useful for lots of Applications. If you need help or encounter any difficulties setting up Magic URL Login with Appwrite, please join our Discord.

🔖 References

• Appwrite Discord
• Getting Started with Android
• Appwrite Documentation