passport-magic-login

To trigger the magic link process, POST a JSON request to your server's magic login endpoint. The payload must include a destination field (the user's email or phone number). You can include additional fields in the payload, which will be available in the backend verify method's payload argument.

Upon success, the server returns a JSON response containing success: true and a code. It is recommended to display json.code to the user so they can verify they are clicking the link for the correct login attempt.

// POST a request with the users email or phone number to the server
fetch(`/auth/magiclogin`, {
  method: `POST`,
  body: JSON.stringify({
    // `destination` is required.
    destination: email,
    // However, you can POST anything in your payload and it will show up in your verify() method
    name: name,
  }),
  headers: { 'Content-Type': 'application/json' }
})
  .then(res => res.json())
  .then(json => {
    if (json.success) {
      // The request successfully completed and the email to the user with the
      // magic login link was sent!
      // You can now prompt the user to click on the link in their email
      // We recommend you display json.code in the UI (!) so the user can verify
      // that they're clicking on the link for their _current_ login attempt
      document.body.innerText = json.code
    }
  })

To set up the backend, instantiate MagicLoginStrategy with the required configuration options. All options are mandatory.

Required Options

• secret: A long, unique, and secret string used to encrypt the authentication token.
• callbackUrl: The URL where the user is redirected after clicking the magic link.
• sendMagicLink: An async function called with the destination (e.g., email or phone) and the href (the path containing the token). Use this to deliver the link via email, SMS, etc.
• verify: A function called once the user verifies their login attempt. It receives a payload (containing the destination and any other data POSTed from the client) and a callback. You must use this to find or create a user in your database and pass the user object to the callback.

Optional Options

• jwtOptions: An object containing options passed to the jwt.sign call (compatible with node-jsonwebtoken).

import MagicLoginStrategy from "passport-magic-login"

const magicLogin = new MagicLoginStrategy({
  secret: process.env.MAGIC_LINK_SECRET,
  callbackUrl: "/auth/magiclogin/callback",
  sendMagicLink: async (destination, href) => {
    await sendEmail({
      to: destination,
      body: `Click this link to finish logging in: https://yourcompany.com${href}`
    })
  },
  verify: (payload, callback) => {
    getOrCreateUserWithEmail(payload.destination)
      .then(user => {
        callback(null, user)
      })
      .catch(err => {
        callback(err)
      })
  },
  jwtOptions: {
    expiresIn: "2 days",
  }
})

passport.use(magicLogin)

The MagicLoginStrategy requires an Options object to define how tokens are signed, where users are redirected, and how the magic link is delivered.

Key configuration properties:

• secret: The secret key used for signing and verifying JWTs.
• callbackUrl: The URL where the user is redirected after clicking the magic link (e.g., https://myapp.com/verify).
• jwtOptions: Optional SignOptions from jsonwebtoken to customize the JWT.
• sendMagicLink: An asynchronous function responsible for delivering the link. It receives the destination (e.g., email), the generated href, a verificationCode, and the req object.
• verify: A callback function used to validate the decoded token payload and identify the user.

import MagicLoginStrategy, { Options } from 'passport-magic-login';

const options: Options = {
  secret: 'your-very-secure-secret',
  callbackUrl: 'https://example.com/auth/callback',
  jwtOptions: { expiresIn: '1h' },
  sendMagicLink: async (destination, href, verificationCode, req) => {
    // Implement your own logic to send email/SMS
    await myEmailProvider.send({
      to: destination,
      body: `Click here to login: ${href}`
    });
  },
  verify: (payload, verifyCallback, req) => {
    // Logic to find or create a user based on payload
    const user = findUserByEmail(payload.destination);
    if (user) {
      verifyCallback(null, user);
    } else {
      verifyCallback(new Error('User not found'));
    }
  }
};

const strategy = new MagicLoginStrategy(options);

The .authenticate(req) method is used within a Passport strategy implementation to validate the magic link token provided in the request. It looks for the token in req.query.token or req.body.token.

Workflow:

1. Decodes the JWT using the configured secret.
2. If decoding fails, it calls fail() with an error message.
3. If decoding succeeds, it executes the verify callback provided in the Options.
4. Based on the verify callback's result, it calls success(), fail(), or error().

// Example Passport configuration
import passport from 'passport';

passport.use(strategy);

// In your route handler
app.get('/auth/callback', (req, res, next) => {
  passport.authenticate('magiclogin', (err, user, info) => {
    if (err) return next(err);
    if (!user) return res.redirect('/login?error=invalid-token');
    // User is authenticated
    req.logIn(user, () => res.redirect('/dashboard'));
  })(req, res, next);
});