Magic Link authentication, also known as "Passwordless Login," is a user-friendly authentication method that eliminates the need for users to remember passwords. Instead, users simply enter their email address, and the system sends them a unique, time-limited URL that logs them in automatically when clicked.

This approach enhances user experience, reduces password-related support tickets, and improves security by removing phishing-prone passwords.

How Magic Link Authentication Works

1. Initiation: User enters their email on a login form.
2. Token Generation: The backend generates a cryptographically secure, unique token and associates it with the user's email and an expiration timestamp.
3. Email Dispatch: The system sends an email containing a login link with the token (e.g., https://yourapp.com/auth/verify?token=abc123...).
4. Verification: User clicks the link. The backend validates the token, checks its expiration, and authenticates the user.
5. Session Creation: A traditional session or JWT is established upon successful verification.

Java Implementation Guide

We'll build a simple Magic Link service using Spring Boot with a clean, layered architecture.

1. Project Dependencies (pom.xml)

<dependencies> <!-- Spring Boot Starter Web --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!-- Spring Data JPA for persistence --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-jpa</artifactId> </dependency> <!-- H2 Database (for demo) --> <dependency> <groupId>com.h2database</groupId> <artifactId>h2</artifactId> <scope>runtime</scope> </dependency> <!-- Java Mail Sender --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-mail</artifactId> </dependency> <!-- Validation --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-validation</artifactId> </dependency> </dependencies>

2. Data Model: MagicToken Entity

@Entity @Table(name = "magic_tokens") public class MagicToken { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id; @Column(nullable = false, unique = true) private String token; @Column(nullable = false) private String email; @Column(nullable = false) private Instant expiryDate; @Column(nullable = false) private boolean used = false; // Constructors, Getters, and Setters public MagicToken() {} public MagicToken(String token, String email, Instant expiryDate) { this.token = token; this.email = email; this.expiryDate = expiryDate; } public boolean isExpired() { return Instant.now().isAfter(expiryDate); } // Standard getters and setters... }

3. Repository Layer

@Repository public interface MagicTokenRepository extends JpaRepository<MagicToken, Long> { Optional<MagicToken> findByTokenAndUsedFalse(String token); void deleteByExpiryDateBefore(Instant expiryDate); // Prevent multiple active tokens for the same email @Modifying @Query("DELETE FROM MagicToken mt WHERE mt.email = :email AND mt.used = false") void deleteExistingTokensForEmail(@Param("email") String email); }

4. Service Layer

The service handles token generation, email sending, and verification logic.

@Service public class MagicLinkService { private final MagicTokenRepository tokenRepository; private final JavaMailSender mailSender; // Configurable values (should be in application.properties) @Value("${app.magic-link.base-url:http://localhost:8080}") private String baseUrl; @Value("${app.magic-link.expiry-minutes:15}") private int expiryMinutes; public MagicLinkService(MagicTokenRepository tokenRepository, JavaMailSender mailSender) { this.tokenRepository = tokenRepository; this.mailSender = mailSender; } public void initiateMagicLinkLogin(String email) { // 1. Clean up existing tokens for this email tokenRepository.deleteExistingTokensForEmail(email); // 2. Generate secure token String token = generateSecureToken(); // 3. Calculate expiry date Instant expiryDate = Instant.now().plus(expiryMinutes, ChronoUnit.MINUTES); // 4. Save to database MagicToken magicToken = new MagicToken(token, email, expiryDate); tokenRepository.save(magicToken); // 5. Send email sendMagicLinkEmail(email, token); } public String verifyToken(String token) { Optional<MagicToken> magicTokenOpt = tokenRepository.findByTokenAndUsedFalse(token); if (magicTokenOpt.isEmpty()) { throw new RuntimeException("Invalid or expired magic link."); } MagicToken magicToken = magicTokenOpt.get(); if (magicToken.isExpired()) { tokenRepository.delete(magicToken); throw new RuntimeException("Magic link has expired."); } // Mark token as used magicToken.setUsed(true); tokenRepository.save(magicToken); return magicToken.getEmail(); } private String generateSecureToken() { // Generate a cryptographically secure random token SecureRandom random = new SecureRandom(); byte[] bytes = new byte[32]; // 256 bits random.nextBytes(bytes); // Encode to hexadecimal string return HexFormat.of().formatHex(bytes); } private void sendMagicLinkEmail(String email, String token) { try { String magicLink = baseUrl + "/auth/verify?token=" + token; SimpleMailMessage message = new SimpleMailMessage(); message.setTo(email); message.setSubject("Your Magic Login Link"); message.setText("Click the link below to log in:\n\n" + magicLink + "\n\nThis link will expire in " + expiryMinutes + " minutes."); mailSender.send(message); } catch (Exception e) { throw new RuntimeException("Failed to send magic link email", e); } } // Clean up expired tokens (can be called by a scheduled task) @Scheduled(cron = "0 0 * * * *") // Run every hour public void cleanupExpiredTokens() { tokenRepository.deleteByExpiryDateBefore(Instant.now()); } }

5. REST Controller

@RestController @RequestMapping("/auth") public class AuthController { private final MagicLinkService magicLinkService; public AuthController(MagicLinkService magicLinkService) { this.magicLinkService = magicLinkService; } @PostMapping("/magic-link") public ResponseEntity<?> requestMagicLink(@Valid @RequestBody MagicLinkRequest request) { try { magicLinkService.initiateMagicLinkLogin(request.getEmail()); return ResponseEntity.ok().body( Map.of("message", "Magic link sent to your email!") ); } catch (Exception e) { return ResponseEntity.badRequest().body( Map.of("error", "Failed to send magic link: " + e.getMessage()) ); } } @GetMapping("/verify") public ResponseEntity<?> verifyMagicLink(@RequestParam String token) { try { String email = magicLinkService.verifyToken(token); // Here you would typically: // 1. Create a session or JWT // 2. Set authentication in SecurityContext // 3. Redirect to dashboard or return success response return ResponseEntity.ok().body( Map.of("message", "Login successful!", "email", email) ); } catch (RuntimeException e) { return ResponseEntity.badRequest().body( Map.of("error", e.getMessage()) ); } } } // DTO for request class MagicLinkRequest { @Email @NotBlank private String email; // Getters and Setters public String getEmail() { return email; } public void setEmail(String email) { this.email = email; } }

6. Configuration (application.properties)

# Database spring.datasource.url=jdbc:h2:mem:testdb spring.jpa.hibernate.ddl-auto=create-drop # Email Configuration (example for Gmail) spring.mail.host=smtp.gmail.com spring.mail.port=587 [email protected] spring.mail.password=your-app-password spring.mail.properties.mail.smtp.auth=true spring.mail.properties.mail.smtp.starttls.enable=true # Magic Link Configuration app.magic-link.base-url=http://localhost:8080 app.magic-link.expiry-minutes=15

Security Considerations & Best Practices

1. Cryptographically Secure Tokens: Always use SecureRandom for token generation to prevent predictability.
2. Short Expiration Time: 10-15 minutes is ideal to minimize the window of opportunity if a link is intercepted.
3. Single-Use Tokens: Mark tokens as used immediately after verification to prevent replay attacks.
4. Secure Email Transport: Ensure emails are sent over secure channels (TLS). Consider including device/browser information in the email for user awareness.
5. Rate Limiting: Implement rate limiting on the magic link request endpoint to prevent email bombing.
6. Token Cleanup: Regularly clean up expired tokens from the database.
7. Frontend Integration: The verification endpoint should ideally redirect to a success/failure page in a Single Page Application (SPA).

Advanced Enhancements

• JWT Integration: Instead of just returning success, issue a JWT upon magic link verification.
• Custom HTML Emails: Use Thymeleaf or Freemarker templates to create beautiful, branded emails.
• Audit Logging: Log magic link requests and verifications for security monitoring.
• IP Address Tracking: Associate tokens with the IP address that requested them for additional security.

This implementation provides a solid foundation for passwordless authentication that you can extend based on your specific security and user experience requirements.