---
name: auth-system
description: Implement secure authentication and authorization systems with JWT, OAuth2, Session-based auth, and RBAC. Use when: (1) implementing user login/signup, (2) setting up JWT tokens, (3) OAuth2 integration (Google, GitHub, etc.), (4) role-based access control (RBAC), (5) password hashing and validation, (6) session management, (7) API authentication middleware, (8) 2FA/MFA setup. Triggers: "authentication", "login", "JWT", "OAuth", "session", "password hash", "RBAC", "permissions", "2FA".
---
# Authentication System
Production-grade authentication and authorization implementation.
## Authentication Strategies
### 1. JWT (Stateless)
```javascript
const jwt = require('jsonwebtoken');
const bcrypt = require('bcrypt');
// Signup
async function signup(email, password) {
const hashedPassword = await bcrypt.hash(password, 12);
const user = await User.create({ email, password: hashedPassword });
return generateTokens(user);
}
// Login
async function login(email, password) {
const user = await User.findByEmail(email);
if (!user || !await bcrypt.compare(password, user.password)) {
throw new Error('Invalid credentials');
}
return generateTokens(user);
}
// Token generation
function generateTokens(user) {
const accessToken = jwt.sign(
{ userId: user.id, role: user.role },
process.env.JWT_SECRET,
{ expiresIn: '15m' }
);
const refreshToken = jwt.sign(
{ userId: user.id, tokenVersion: user.tokenVersion },
process.env.REFRESH_SECRET,
{ expiresIn: '7d' }
);
return { accessToken, refreshToken };
}
// Middleware
function authMiddleware(req, res, next) {
const token = req.headers.authorization?.split(' ')[1];
if (!token) return res.status(401).json({ error: 'Unauthorized' });
try {
req.user = jwt.verify(token, process.env.JWT_SECRET);
next();
} catch (err) {
res.status(401).json({ error: 'Invalid token' });
}
}
```
### 2. Session-Based (Stateful)
```javascript
const session = require('express-session');
const RedisStore = require('connect-redis')(session);
app.use(session({
store: new RedisStore({ client: redisClient }),
secret: process.env.SESSION_SECRET,
resave: false,
saveUninitialized: false,
cookie: {
secure: true, // HTTPS only
httpOnly: true, // No JS access
maxAge: 24 * 60 * 60 * 1000, // 24 hours
sameSite: 'strict'
}
}));
// Login
app.post('/login', async (req, res) => {
const user = await validateCredentials(req.body);
req.session.userId = user.id;
req.session.role = user.role;
res.json({ success: true });
});
// Logout
app.post('/logout', (req, res) => {
req.session.destroy();
res.json({ success: true });
});
```
### 3. OAuth2 (Social Login)
```javascript
const passport = require('passport');
const GoogleStrategy = require('passport-google-oauth20').Strategy;
passport.use(new GoogleStrategy({
clientID: process.env.GOOGLE_CLIENT_ID,
clientSecret: process.env.GOOGLE_CLIENT_SECRET,
callbackURL: '/auth/google/callback'
}, async (accessToken, refreshToken, profile, done) => {
let user = await User.findByGoogleId(profile.id);
if (!user) {
user = await User.createFromGoogle(profile);
}
done(null, user);
}));
// Routes
app.get('/auth/google', passport.authenticate('google', { scope: ['email', 'profile'] }));
app.get('/auth/google/callback',
passport.authenticate('google', { session: false }),
(req, res) => {
const tokens = generateTokens(req.user);
res.redirect(`/callback?token=${tokens.accessToken}`);
}
);
```
## Authorization (RBAC)
```javascript
// Role definitions
const ROLES = {
ADMIN: 'admin',
USER: 'user',
MODERATOR: 'moderator'
};
// Permission definitions
const PERMISSIONS = {
[ROLES.ADMIN]: ['read', 'write', 'delete', 'manage_users'],
[ROLES.MODERATOR]: ['read', 'write', 'delete'],
[ROLES.USER]: ['read', 'write']
};
// Middleware
function requirePermission(permission) {
return (req, res, next) => {
const userPermissions = PERMISSIONS[req.user.role] || [];
if (!userPermissions.includes(permission)) {
return res.status(403).json({ error: 'Forbidden' });
}
next();
};
}
// Usage
app.delete('/posts/:id',
authMiddleware,
requirePermission('delete'),
deletePost
);
```
## Password Security
```javascript
const bcrypt = require('bcrypt');
const crypto = require('crypto');
// Hash password
async function hashPassword(password) {
const salt = await bcrypt.genSalt(12);
return bcrypt.hash(password, salt);
}
// Validate password
async function validatePassword(password, hash) {
return bcrypt.compare(password, hash);
}
// Generate secure token (for password reset)
function generateResetToken() {
return crypto.randomBytes(32).toString('hex');
}
```
## 2FA (TOTP)
```javascript
const speakeasy = require('speakeasy');
const QRCode = require('qrcode');
// Setup 2FA
async function setup2FA(userId) {
const secret = speakeasy.generateSecret({
name: 'MyApp',
length: 20
});
await User.update(userId, {
twoFactorSecret: secret.base32,
twoFactorEnabled: false
});
const qrUrl = await QRCode.toDataURL(secret.otpauth_url);
return { secret: secret.base32, qrUrl };
}
// Verify 2FA
function verify2FA(secret, token) {
return speakeasy.totp.verify({
secret,
encoding: 'base32',
token,
window: 1 // Allow 1 step before/after
});
}
```
## Security Best Practices
```
✅ Always use HTTPS in production
✅ Store passwords with bcrypt (cost factor >= 12)
✅ Use short-lived access tokens (15-30 min)
✅ Implement refresh token rotation
✅ Set secure cookie flags (httpOnly, secure, sameSite)
✅ Rate limit login attempts
✅ Log failed authentication attempts
✅ Implement account lockout after N failures
✅ Never store tokens in localStorage (XSS risk)
✅ Use CSRF protection for session-based auth
```
## Scripts
- `scripts/generate_jwt_secret.js` - Generate secure JWT secret
- `scripts/hash_password.js` - CLI tool to hash passwords
- `scripts/verify_token.js` - Decode and verify JWT tokens
## References
- `references/oauth_providers.md` - OAuth2 provider setup guides
- `references/security_checklist.md` - Auth security audit checklist
- `references/token_refresh_flow.md` - Refresh token rotation patterns