Magic URL authentication with Flutter + Appwrite

Appwrite 0.10 introduced Magic URL a password-less authentication method. This allows developers to authenticate their users using an email and a URL sent via an E-Mail.

⚙️ Setup

In this tutorial we will learn how we can use Magic URL Authentication in our Flutter applications using Appwrite's Flutter SDK. The same can be done with our Web SDK and Android SDK. As this feature needs to send an email, you must properly setup SMTP service in Appwrite. If you have not already, you can follow this guide to setup SMTP in your Appwrite server.

First, add the Flutter SDK to our Flutter project. From the terminal, in your project's directory enter the following command to add the SDK

flutter pub add appwrite

Next, import and initialize the SDK with your project ID which can be found in your project settings page in Appwrite's console:

import 'package:appwrite/appwrite.dart';

final client = new Client();

client
    .setEndpoint('http://localhost/v1') // Your Appwrite Endpoint
    .setProject('455x34dfkj') // Your Appwrite Project ID
;

Finally, update the AndroidManifest.xml file if you are on Android to handle the redirection after handling the login with magic URL as follows:

<manifest>
  <application>
    <!-- ... -->
    <activity android:name="com.linusu.flutter_web_auth.CallbackActivity" >
      <intent-filter android:label="flutter_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>
    <!-- ... -->
  </application>
</manifest>

🎩 Create a Magic URL

Once your SDK is setup, access the Account service and call the createMagicURLSession() method. This method accepts an e-mail address and a redirect URL as arguments. The redirect URL is optional, but should be provided if you want to handle the completion of magic URL session and redirection yourself.

// Initiate the Magic URL login
final account = Account(client);
try {
    final res = await account.createMagicURLSession(email: '[e-mail]');
    print(res.data);
} on AppwriteException catch(e) {
    print(e.message);
}

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. If the URL is not provided, the URL of your Appwrite instance is used where there is an inbuilt function to handle the completion of magic URL session. When the user clicks the link, they are redirected back to the URL 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.

If you do not provide a redirect URL, your Appwrite instance will automatically handle the completion and redirection and you should be redirected back to your mobile App. For this, make sure you are able to access the Appwrite instance from your mobile. It's best to host it somewhere with a proper domain. If not use services like ngrok to tunnel your localhost to a temporary domain.

🔐 Login with a Magic URL

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. And you need to pass the URL of this web app in the URL parameter while calling createMagicURLSession.

For that, 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 Appwrite feature 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 Flutter
• Appwrite Documentation