How to Add Auth to a Node.js App with Magic
End-to-end example showing how Magic works with the Node.js Express framework.
#Overview
Welcome to our end-to-end example to demonstrate how Magic works with your own Node.js server using the popular Express framework! If you haven't gone through the Hello World Example, we strongly recommend going through it before starting this tutorial.
In this example, we'll be implementing an additional feature in the Hello World example - letting only authorized users buy apples ๐ and see how many they own.
#Tutorial
#Set Up Tutorial Template
Use our Node Tutorial Template to follow along with this tutorial.
The full stack Node.js server is set up using the vanilla Express template on CodeSandBox, using NeDB as an ultra lightweight database (you can switch it to other databases like MongoDB too) and the express-session NPM package to manage sessions. We'll make use of the Magic Admin SDK for this example. You can learn how to install it via npm or yarn in the Node.js reference.
#Setup Environment Variables
From the CodeSandBox's Node Tutorial Template, click "Fork" to create your own instance to play with.
Once you've forked the template, click on the "Server Rack" icon in the left menu, and then update your "Secret Keys".
To grab these two values, you need to sign up or log in to the Magic Dashboard to view your API keys. Once you are logged in you, you can add MAGIC_SECRET_KEY as Name, and your actual secret API key, which looks something like sk_live_********* as Value.
Once that's done, you can add MAGIC_PUBLISHABLE_KEY as Name, and your publishable API key, which looks something like pk_live_********* as Value.
Once the keys are copy and pasted in the Secret Keys section, click Restart Server to load these environment variables in the CodeSandBox container.
Note that the MAGIC_SECRET_KEY environment variable is used to initialize the Magic Admin SDK.
01/* 1. Setup Magic Admin SDK */
02const { Magic } = require('@magic-sdk/admin');
03const magic = new Magic(process.env.MAGIC_SECRET_KEY);
Your very own full-stack Magic Apple Store application is now running! ๐
The next steps explain each of major sections of the code base.
#Implement Auth Strategy
Magic leverages the popular and battle-tested Passport authentication middleware package for Express to provide our passwordless authentication service. This way it will be very seamless and easy to integrate for developers who are already familiar with Passport! (Don't worry if you are not, we'll go through comprehensive examples in this tutorial)
Magic's authentication is based on the Decentralized ID (DID) token standard, and the strategy implemented by passport-magic already takes care of the heavy-lifting by verifying the token and returning the authenticated user object. In this strategy, we'd like to define what to do if this user is a new user versus a returning user.
Note that in the DID standard we use issuer quite a lot, which looks something like did:ethr:0xE0cef...839b0D6D6D, it represents a unique blockchain public address that can often be used as an identifier field. The issuer can be used to fetch the authenticated user's metadata, which includes their associated email address.
01/* In routes/user.js */
02
03/* 2. Implement Auth Strategy */
04const passport = require('passport');
05const MagicStrategy = require('passport-magic').Strategy;
06
07const strategy = new MagicStrategy(async function (user, done) {
08 const userMetadata = await magic.users.getMetadataByIssuer(user.issuer);
09 const existingUser = await users.findOne({ issuer: user.issuer });
10 if (!existingUser) {
11 /* Create new user if doesn't exist */
12 return signup(user, userMetadata, done);
13 } else {
14 /* Login user if otherwise */
15 return login(user, done);
16 }
17});
18
19passport.use(strategy);
#Implement Auth Behaviors
#Implement User Signup
The user signup behavior is pretty straightforward in this case, where a new user would be inserted into the NeDB database.
01/* In routes/user.js */
02
03/* 3. Implement Auth Behaviors */
04
05/* Implement User Signup */
06const signup = async (user, userMetadata, done) => {
07 let newUser = {
08 issuer: user.issuer,
09 email: userMetadata.email,
10 lastLoginAt: user.claim.iat,
11 };
12 await users.insert(newUser);
13 return done(null, newUser);
14};
#Implement User Login
Since authentication is token-based, the user login behavior needs to implement a timestamp check to protect against replay attacks - here's a simple reference implementation, but you can make adjustments depending on your security preference.
01/* In routes/user.js */
02
03/* Implement User Login */
04const login = async (user, done) => {
05 /* Replay attack protection (https://go.magic.link/replay-attack) */
06 if (user.claim.iat <= user.lastLoginAt) {
07 return done(null, false, {
08 message: `Replay attack detected for user ${user.issuer}}.`,
09 });
10 }
11 await users.update({ issuer: user.issuer }, { $set: { lastLoginAt: user.claim.iat } });
12 return done(null, user);
13};
14
15/* Attach middleware to login endpoint */
16router.post('/login', passport.authenticate('magic'));
Here's an example of how to call the Login Endpoint from the client-side:
01/* In views/index.js */
02
03...
04
05const didToken = await magic.auth.loginWithMagicLink({ email });
06await fetch(`${serverUrl}user/login`, {
07 headers: new Headers({
08 Authorization: "Bearer " + didToken
09 }),
10 withCredentials: true,
11 credentials: "same-origin",
12 method: "POST"
13});
14
15...
#Implement Session Behavior
An awesome feature from the Passport middleware is the possibility to populate the req.user object with an actual database record, so that the data can be conveniently used in your endpoints. See the next section for more examples.
01/* In routes/user.js */
02
03/* 4. Implement Session Behavior */
04
05/* Defines what data are stored in the user session */
06passport.serializeUser((user, done) => {
07 done(null, user.issuer);
08});
09
10/* Populates user data in the req.user object */
11passport.deserializeUser(async (id, done) => {
12 try {
13 const user = await users.findOne({ issuer: id });
14 done(null, user);
15 } catch (err) {
16 done(err, null);
17 }
18});
#Implement User Endpoints
#Implement Get Data Endpoint
This endpoint is responsible for grabbing the currently authenticated user's data, including the number of apples ๐ to be displayed in the front-end! Note how this endpoint uses req.isAuthenticated() to check if the current user is authenticated, and req.user can be passed to the front-end without fetching from the database again!
01/* In routes/user.js */
02
03/* 5. Implement User Endpoints */
04
05/* Implement Get Data Endpoint */
06router.get('/', async (req, res) => {
07 if (req.isAuthenticated()) {
08 return res.status(200).json(req.user).end();
09 } else {
10 return res.status(401).end(`User is not logged in.`);
11 }
12});
Here's how you would call the Get Data Endpoint from the client-side:
01/* In views/index.js */
02
03...
04
05let res = await fetch(`${serverUrl}/user/`);
06if (res.status == 200) {
07 let userData = await res.json();
08 let appleCount = userData.appleCount;
09 ...
10}
11
12...
#Implement Buy Apple Endpoint
Follows similar pattern as the Get Data Endpoint, instead authenticated user can now update and increment their apple count!
01/* In routes/user.js */
02
03/* Implement Buy Apple Endpoint */
04router.post('/buy-apple', async (req, res) => {
05 if (req.isAuthenticated()) {
06 await users.update({ issuer: req.user.issuer }, { $inc: { appleCount: 1 } });
07 return res.status(200).end();
08 } else {
09 return res.status(401).end(`User is not logged in.`);
10 }
11});
Here's how you would call the Buy Apple Endpoint from the client-side:
01/* In views/index.js */
02
03const handleBuyApple = async () => {
04 await fetch(`${serverUrl}/user/buy-apple`, { method: 'POST' });
05 render();
06};
#Implement Logout Endpoint
To log out the user, you can use the Magic Admin SDK to logout the current user based on the user ID, remember to also call req.logout() to clear the Express user session as well!
01/* In routes/user.js */
02
03/* Implement Logout Endpoint */
04router.post('/logout', async (req, res) => {
05 if (req.isAuthenticated()) {
06 await magic.users.logoutByIssuer(req.user.issuer);
07 req.logout();
08 return res.status(200).end();
09 } else {
10 return res.status(401).end(`User is not logged in.`);
11 }
12});
With this, you no longer have to call magic.user.logout() on the client-side.
01/* In views/index.js */
02
03const handleLogout = async () => {
04 // await magic.user.logout(); NO LONGER NEEDED!
05 await fetch(`${serverUrl}/user/logout`, { method: 'POST' });
06 render();
07};
๐ Congratulations! Now that you've completed the tutorial, you should have a working version of the ๐ Apple Store app!
#What's Next
#Use Magic with existing tools
Firebase โ Magic provides much flexibility and composability to be combined with many other powerful platforms such as Firebase. Learn how to plug Magic into the entire Firebase suite of tools!
Next.js (Vercel) โ Learn how to use the popular Next.js framework to build a React app and deploy it with Vercel.
#Customize your Magic flow
You can customize the login experience using your own UI instead of Magic's default one and/or customize the magic link email with your brand. Learn how to customize.
