Introduction
Web3 authentication replaces traditional username/password with wallet-based authentication. Users prove ownership of an address by signing messages with their private key. This guide covers implementation best practices and security considerations.
Core Concepts
Wallet: Software or hardware that manages private keys and signs transactions.
Private Key: Secret key used to sign transactions and prove ownership.
Public Key: Derived from private key, used to verify signatures.
Message Signing: Proving ownership without sending transactions.
EIP-191: Standard for signing messages in Ethereum.
EIP-712: Standard for structured data signing.
Session Token: JWT or similar token issued after authentication.
Nonce: Random value preventing replay attacks.
Authentication Flow
Web3 Authentication Flow
┌─────────────────────────────────────────────────────────┐
│ 1. User Connects Wallet │
│ └─ MetaMask/WalletConnect/etc │
└────────────────┬────────────────────────────────────────┘
│
┌────────▼────────────────┐
│ 2. Request Message │
│ └─ Server generates │
│ nonce + message │
└────────┬────────────────┘
│
┌────────▼────────────────┐
│ 3. User Signs Message │
│ └─ Wallet signs with │
│ private key │
└────────┬────────────────┘
│
┌────────▼────────────────┐
│ 4. Verify Signature │
│ └─ Server verifies │
│ signature │
└────────┬────────────────┘
│
┌────────▼────────────────┐
│ 5. Issue Session Token │
│ └─ JWT or similar │
└────────────────────────┘
Implementation
1. Request Message for Signing
// Backend: Generate message to sign
async function generateAuthMessage(address) {
const nonce = Math.floor(Math.random() * 1000000);
const timestamp = new Date().toISOString();
const message = `
Welcome to My DApp!
Sign this message to authenticate.
Address: ${address}
Nonce: ${nonce}
Timestamp: ${timestamp}
`.trim();
// Store nonce in database for verification
await saveNonce(address, nonce, timestamp);
return message;
}
// Frontend: Request message
async function requestAuthMessage(address) {
const response = await fetch('/api/auth/message', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ address })
});
const { message } = await response.json();
return message;
}
2. Sign Message with Wallet
// Frontend: Sign message with MetaMask
async function signMessage(address, message) {
try {
const signature = await window.ethereum.request({
method: 'personal_sign',
params: [message, address]
});
return signature;
} catch (error) {
console.error('User denied signing:', error);
throw error;
}
}
// Alternative: Using ethers.js
import { ethers } from 'ethers';
async function signMessageWithEthers(message) {
const provider = new ethers.providers.Web3Provider(window.ethereum);
const signer = provider.getSigner();
const signature = await signer.signMessage(message);
return signature;
}
3. Verify Signature
// Backend: Verify signature
const ethers = require('ethers');
async function verifySignature(address, message, signature) {
try {
// Recover address from signature
const recoveredAddress = ethers.utils.verifyMessage(message, signature);
// Check if recovered address matches
if (recoveredAddress.toLowerCase() !== address.toLowerCase()) {
throw new Error('Signature verification failed');
}
// Verify nonce hasn't been used
const nonce = extractNonce(message);
const isValidNonce = await validateNonce(address, nonce);
if (!isValidNonce) {
throw new Error('Invalid or expired nonce');
}
return true;
} catch (error) {
console.error('Verification failed:', error);
return false;
}
}
function extractNonce(message) {
const match = message.match(/Nonce: (\d+)/);
return match ? match[1] : null;
}
4. Issue Session Token
// Backend: Create JWT after verification
const jwt = require('jsonwebtoken');
async function createSessionToken(address) {
const token = jwt.sign(
{
address: address,
iat: Math.floor(Date.now() / 1000),
exp: Math.floor(Date.now() / 1000) + (24 * 60 * 60) // 24 hours
},
process.env.JWT_SECRET
);
return token;
}
// Frontend: Store token
async function authenticate(address, message) {
const signature = await signMessage(address, message);
const response = await fetch('/api/auth/verify', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
address,
message,
signature
})
});
const { token } = await response.json();
localStorage.setItem('authToken', token);
return token;
}
Advanced Patterns
1. EIP-712 Structured Data Signing
// More secure: Sign structured data
const domain = {
name: 'My DApp',
version: '1',
chainId: 1,
verifyingContract: '0x...'
};
const types = {
Authentication: [
{ name: 'address', type: 'address' },
{ name: 'nonce', type: 'uint256' },
{ name: 'timestamp', type: 'uint256' }
]
};
const value = {
address: userAddress,
nonce: 12345,
timestamp: Math.floor(Date.now() / 1000)
};
// Sign with ethers.js
const signature = await signer._signTypedData(domain, types, value);
2. Multi-Signature Authentication
// Require multiple signatures
async function multiSigAuth(addresses, message) {
const signatures = [];
for (const address of addresses) {
const sig = await signMessage(address, message);
signatures.push(sig);
}
// Verify all signatures
for (let i = 0; i < addresses.length; i++) {
const recovered = ethers.utils.verifyMessage(
message,
signatures[i]
);
if (recovered.toLowerCase() !== addresses[i].toLowerCase()) {
throw new Error(`Signature ${i} invalid`);
}
}
return signatures;
}
3. Session Management
// Middleware: Verify token
function authMiddleware(req, res, next) {
const token = req.headers.authorization?.split(' ')[1];
if (!token) {
return res.status(401).json({ error: 'No token' });
}
try {
const decoded = jwt.verify(token, process.env.JWT_SECRET);
req.user = decoded;
next();
} catch (error) {
res.status(401).json({ error: 'Invalid token' });
}
}
// Protected route
app.get('/api/user/profile', authMiddleware, (req, res) => {
res.json({ address: req.user.address });
});
Security Best Practices
1. Prevent Replay Attacks
// Use nonce + timestamp
const message = `
Sign to authenticate
Nonce: ${nonce}
Timestamp: ${timestamp}
`;
// Verify nonce is fresh
const messageTime = new Date(timestamp);
const now = new Date();
const diffMinutes = (now - messageTime) / (1000 * 60);
if (diffMinutes > 5) {
throw new Error('Message expired');
}
2. Validate Message Format
function validateMessage(message, address) {
// Check message contains expected content
if (!message.includes(address)) {
throw new Error('Address mismatch');
}
if (!message.includes('Nonce:')) {
throw new Error('Missing nonce');
}
if (!message.includes('Timestamp:')) {
throw new Error('Missing timestamp');
}
return true;
}
3. Rate Limiting
// Limit authentication attempts
const rateLimit = require('express-rate-limit');
const authLimiter = rateLimit({
windowMs: 15 * 60 * 1000, // 15 minutes
max: 5, // 5 requests per window
keyGenerator: (req) => req.body.address
});
app.post('/api/auth/verify', authLimiter, verifyHandler);
Common Pitfalls
Pitfall 1: Reusing Messages
Problem: Same message can be replayed.
Solution: Use nonce + timestamp for each message.
Pitfall 2: Not Validating Signature
Problem: Accepting invalid signatures.
Solution: Always verify signature matches address.
Pitfall 3: Storing Private Keys
Problem: Never store private keys.
Solution: Only store public addresses and signatures.
Pros and Cons vs Traditional Auth
| Aspect | Web3 Auth | Traditional |
|---|---|---|
| Security | ✅ Cryptographic | ⚠️ Password-based |
| Privacy | ✅ Anonymous | ❌ Requires email |
| Portability | ✅ Works everywhere | ❌ Site-specific |
| Recovery | ⚠️ Complex | ✅ Simple |
| UX | ⚠️ Wallet required | ✅ Simple |
Resources
Documentation
Libraries
Tools
Conclusion
Web3 authentication provides cryptographic security and user privacy. Implement proper nonce validation, message verification, and session management for production systems.
Next Steps:
- Implement message generation with nonce
- Add signature verification
- Create session tokens
- Add rate limiting
- Test with multiple wallets
Comments