Complete tutorial on how to plug Magic into Firebase Auth to access the full power of Google Firebase!

Magic works out of the box with Firebase - seamlessly connecting state-of-the-art, no lock-in identity and authentication to the immense power of the Google platform.

This end-to-end example will adapt the Magic Apple Store example into a Magic + Firebase application leveraging Firebase's powerful Cloud Functions and Firestore.

#Setup Cloud Functions Project

This section is to help new developers who don't already have a project with Firebase Cloud Functions setup. If you already have an existing Cloud Functions project, feel free to skip to the Next Section!

#1. Create a Firebase Project

1. In the Firebase console, click Add project, then select or enter a Project name.
2. Click Continue through the steps and then click Create project.
3. After a minute or so, your project will be created. Then continue to your project home page and enable the Firestore database feature.
4. Click on the Create database button and you will be directed through a short flow to complete the setup. Don't worry too much about the secure rules yet as we'll get to those later.

#2. Setup Node.js and the Firebase CLI

Now that your project is setup. You'll need a Node.js environment to write functions and properly initialize your project locally, and you'll need the Firebase CLI to deploy functions to the Cloud Functions runtime. Node.js versions 8 and 10 are supported. For installing Node.js and npm, Node Version Manager is recommended.

Once you have Node.js and npm installed, install the Firebase CLI via your preferred method. To install the CLI via npm, use:

01npm install -g firebase-tools

#3. Initialize Firebase SDK for Cloud Functions

When you initialize Firebase SDK for Cloud Functions, you create an empty project containing dependencies and some minimal sample code, and you choose either TypeScript or JavaScript for composing functions.

To initialize your project:

• Run firebase login to log in via the browser and authenticate the firebase tool.
• Go to your Firebase project directory or create a new empty directory.
• Run firebase init command to initialize your project.

Now you will see some options you'll be able to multi-select, pick both the Firestore and Functions options to be able to go through this tutorial.

• After that you will be presented an option to Use an existing project, pick this option and select the project name you just created on the Firebase console.

• Select Default or Yes to every step after to initialize the Firestore configurations.

• For the purpose of this tutorial, select the JavaScript language option when presented for Cloud Functions configurations.

• Continue the steps and after the npm packages are installed, your project will be fully initialized and ready to go! 🔥

#Connect Magic to Firebase Auth

Magic doesn't replace Firebase Auth, and can actually integrate seamlessly into it so you will be able to have the same permissions and database rules configurations as if it's native Firebase Auth. Before we go into writing the Magic + Firebase adapter Cloud Function, understanding the data flow on the front-end code will be very helpful.

#Auth Data Flow

1. User logs in in with Magic link, which upon successful login, generates a DID token
2. The DID token is passed into the auth Firebase httpsCallable Cloud Function that we will be implementing in later section
3. The auth Cloud Function takes in the DID token and converts it into a Firebase user access token
4. Pass the Firebase user access token into the firebase.auth().signInWithCustomToken method to authenticate user natively with Firebase

Here's a sample front-end code snippet to implement this data flow:

01/* Your Front-end Code */

02

03...

04

05/* User login with Magic link to get DID token */

06const didToken = await magic.auth.loginWithMagicLink({ email });

07const auth = firebase.functions().httpsCallable("auth");

08/* DID token is passed into the auth callable function */

09let result = (await auth({ didToken })).data;

10/* Firebase user access token is used to authenticate */

11await firebase.auth().signInWithCustomToken(result.token);

12

13...

#Get Firebase Config

Setting up your Firebase front-end project properly can help avoid a lot of headaches later. Note that there's a firebaseConfig configuration in our example source code. You'll be able to get this configuration in your project's settings view.

Navigate to settings for your project

Copy and paste this configuration to your front-end code

#Implement Auth Callable Function

The Auth callable Cloud Function will be the crucial piece to converting a Magic DID token into a Firebase user access token to enable this entire experience. We'll go through the configuration steps first.

#Configure and Initialize

• In your Cloud Functions file, you'll have to initialize Firebase with its admin SDK and your service account credential.

01require('dotenv').config();

02

03const functions = require('firebase-functions');

04const admin = require('firebase-admin');

05const serviceAccount = require('./path/to/my-project.json');

06

07admin.initializeApp({

08  credential: admin.credential.cert(serviceAccount),

09  databaseURL: 'https://my-project.firebaseio.com',

10});

• Getting the service account credential is extremely important to make sure you have the right permissions to create the Firebase user access token. You can find it in your Project settings page, under the Service accounts tab, and then click on Generate new private key.

• After downloading the credential, you can put the .json credential file into your project directory and update the path in the const serviceAccount = require("./path/to/my-project.json"); line, as well as updating the databaseURL to the one you see in your project settings dashboard.

#Function Implementation

After all the setup, now let's finally get to the fun part! 🎉 Essentially the auth callable function handles authentication for two types of scenarios (1) existing users who already have email addresses set, including legacy Firebase users, and (2) create new users based on their email addresses and DID token generated by Magic. This callable function will return a unique Firebase user access token and pass it back to the client.

This is a sample implementation on how you can implement this auth function based on those two scenarios via two handler functions:

01exports.auth = functions.https.onCall(async (data, context) => {

02  const { Magic } = require('@magic-sdk/admin');

03  const magic = new Magic('YOUR_SECRET_API_KEY');

04  const didToken = data.didToken;

05  const metadata = await magic.users.getMetadataByToken(didToken);

06  const email = metadata.email;

07  try {

08    /* Get existing user by email address,

09       compatible with legacy Firebase email users */

10    let user = (await admin.auth().getUserByEmail(email)).toJSON();

11    const claim = magic.token.decode(didToken)[1];

12    return await handleExistingUser(user, claim);

13  } catch (err) {

14    if (err.code === 'auth/user-not-found') {

15      /* Create new user */

16      return await handleNewUser(email);

17    } else {

18      throw err;

19    }

20  }

21});

The existing user handler function takes in the existing user object from Firebase and the claim from the DID token to check for replay attack, and if successful, generates and returns a valid Firebase user access token.

01const handleExistingUser = async (user, claim) => {

02  /* Check for replay attack (https://go.magic.link/replay-attack) */

03  let lastSignInTime = Date.parse(user.metadata.lastSignInTime) / 1000;

04  let tokenIssuedTime = claim.iat;

05  if (tokenIssuedTime <= lastSignInTime) {

06    throw new functions.https.HttpsError('invalid-argument', 'This DID token is invalid.');

07  }

08  let firebaseToken = await admin.auth().createCustomToken(user.uid);

09  return {

10    uid: user.uid,

11    token: firebaseToken,

12  };

13};

The new user handler function takes in the email and creates a new Firebase user based on it, and then generates and returns a valid Firebase user access token.

01const handleNewUser = async email => {

02  const newUser = await admin.auth().createUser({

03    email: email,

04    emailVerified: true,

05  });

06  let firebaseToken = await admin.auth().createCustomToken(newUser.uid);

07  return {

08    uid: newUser.uid,

09    token: firebaseToken,

10  };

11};

#Wrapping Up

#Configure Firestore Rules

After you've implemented the auth callable function, go to the firestore.rules file in your local project directory and update it with the following - essentially only allowing the currently authenticated user to perform CRUD in the users collection.

01rules_version = '2';

02service cloud.firestore {

03  match /databases/{database}/documents {

04    match /users/{userId} {

05      allow read, write: if request.auth.uid == userId;

06    }

07  }

08}

#Deploy to Firebase

Now you can simply run the following command with the Firebase CLI in your project directory to deploy your code to Firebase! 🎉

01firebase deploy

#Troubleshooting

#EAI_AGAIN Error

If you are seeing an error like below in your Firebase Cloud Functions log, it's because Firebase requires project Billing to be configured before enabling access to external networks.