173 lines
4.5 KiB
Markdown
173 lines
4.5 KiB
Markdown
# BetterAuth Quick Reference
|
|
|
|
## 🚀 Quick Start (5 minutes)
|
|
|
|
### 1. Generate Secret
|
|
```bash
|
|
npx @better-auth/cli secret
|
|
# Output: abc123... (copy this)
|
|
```
|
|
|
|
### 2. Update .env
|
|
```bash
|
|
BETTER_AUTH_SECRET=abc123...
|
|
```
|
|
|
|
### 3. Start Dev Server
|
|
```bash
|
|
npm run dev
|
|
# Opens http://localhost:3001
|
|
```
|
|
|
|
### 4. Test Login
|
|
- Click "Sign Up" / "Sign In" button
|
|
- Enter email and password
|
|
- Should redirect to /account/webinars
|
|
|
|
## 📦 What's in the Box
|
|
|
|
### Files Created
|
|
```
|
|
lib/auth.ts - BetterAuth server config
|
|
lib/auth-client.ts - BetterAuth frontend client
|
|
app/api/auth/[...route]/ - Unified auth handler
|
|
app/auth/*/callback/ - OAuth callbacks (4 files)
|
|
BETTERAUTH_MIGRATION.md - Detailed migration guide
|
|
BETTERAUTH_SETUP_GUIDE.md - Complete setup guide
|
|
```
|
|
|
|
### Database Tables
|
|
```
|
|
User ↔ Account (OAuth links)
|
|
User ↔ Session (Active sessions)
|
|
User ↔ Verification (Tokens)
|
|
```
|
|
|
|
### API Endpoints
|
|
```
|
|
/api/auth/sign-up/email - Register
|
|
/api/auth/sign-in/email - Login
|
|
/api/auth/sign-out - Logout
|
|
/api/auth/[provider] - OAuth start
|
|
/auth/[provider]/callback - OAuth callback
|
|
/api/auth/get-session - Get user
|
|
```
|
|
|
|
## 🔑 Key Features
|
|
|
|
✅ Email/Password authentication
|
|
✅ 4 OAuth providers (Google, GitHub, Facebook, Discord)
|
|
✅ Session-based auth (secure cookies)
|
|
✅ Email verification
|
|
✅ Password reset
|
|
✅ Admin-configurable providers
|
|
✅ Role-based access control
|
|
|
|
## 🛡️ Security
|
|
|
|
- Passwords: 8-20 chars, bcrypt hashed
|
|
- Sessions: HTTP-only, secure cookies
|
|
- OAuth: Industry-standard 2.0
|
|
- Tokens: TTL-based (email & reset)
|
|
|
|
## 📝 Environment Variables
|
|
|
|
**Required:**
|
|
```bash
|
|
DATABASE_URL=postgresql://...
|
|
BETTER_AUTH_SECRET=abc123...
|
|
```
|
|
|
|
**Optional (set via admin setup or .env):**
|
|
```bash
|
|
GOOGLE_CLIENT_ID=...
|
|
GOOGLE_CLIENT_SECRET=...
|
|
# Same for GITHUB, FACEBOOK, DISCORD
|
|
```
|
|
|
|
## 🔗 OAuth Setup (per provider)
|
|
|
|
### Google
|
|
1. Go to [Google Cloud Console](https://console.cloud.google.com)
|
|
2. Create OAuth 2.0 Client ID
|
|
3. Add Authorized redirect URI: `http://localhost:3001/auth/google/callback`
|
|
4. Copy Client ID and Secret to .env
|
|
|
|
### GitHub
|
|
1. Go to Settings > Developer settings > OAuth Apps
|
|
2. Create new OAuth App
|
|
3. Set Authorization callback URL: `http://localhost:3001/auth/github/callback`
|
|
4. Copy Client ID and Secret to .env
|
|
|
|
### Facebook
|
|
1. Go to [Facebook Developers](https://developers.facebook.com)
|
|
2. Create App > Select Consumer category
|
|
3. Add Facebook Login product
|
|
4. Add Valid OAuth Redirect URIs: `http://localhost:3001/auth/facebook/callback`
|
|
5. Copy App ID and App Secret to .env
|
|
|
|
### Discord
|
|
1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
|
|
2. Create New Application
|
|
3. Add OAuth2 > Redirects: `http://localhost:3001/auth/discord/callback`
|
|
4. Copy Client ID and Client Secret to .env
|
|
|
|
## 🧪 Testing Checklist
|
|
|
|
- [ ] Register with email/password
|
|
- [ ] Login with email/password
|
|
- [ ] Check user in database
|
|
- [ ] Verify password hashing
|
|
- [ ] Test Google OAuth
|
|
- [ ] Test GitHub OAuth
|
|
- [ ] Test logout
|
|
- [ ] Check /account/webinars redirects correctly
|
|
- [ ] Check /admin redirects correctly
|
|
- [ ] Verify session persists on page reload
|
|
|
|
## 🐛 Common Issues
|
|
|
|
| Issue | Fix |
|
|
|-------|-----|
|
|
| "Module not found" | Run `npm install` |
|
|
| "Database error" | Check DATABASE_URL, run `npm run db:migrate` |
|
|
| "Session not working" | Check BETTER_AUTH_SECRET is set |
|
|
| "OAuth not working" | Verify Client ID/Secret and redirect URI |
|
|
| "Role always USER" | Database migrated correctly? Check User table |
|
|
|
|
## 📞 Support
|
|
|
|
- BetterAuth Docs: https://better-auth.com/
|
|
- GitHub Issues: https://github.com/better-auth/better-auth
|
|
- Discord: https://discord.gg/better-auth
|
|
|
|
## ✨ Advanced Features
|
|
|
|
Want to add later?
|
|
- Two-factor authentication (TOTP)
|
|
- Social account linking
|
|
- Custom email templates
|
|
- Rate limiting
|
|
- Activity logging
|
|
- API tokens
|
|
|
|
Check BetterAuth docs for plugins and extensions!
|
|
|
|
## 🎯 Production Checklist
|
|
|
|
- [ ] BETTER_AUTH_SECRET at least 32 characters
|
|
- [ ] APP_BASE_URL set to production domain
|
|
- [ ] OAuth redirect URIs updated to production domain
|
|
- [ ] SMTP configured for email (if needed)
|
|
- [ ] Database backups configured
|
|
- [ ] Rate limiting configured
|
|
- [ ] Security headers configured
|
|
- [ ] CORS configured (if API used externally)
|
|
|
|
---
|
|
|
|
**Status**: ✅ Ready to test
|
|
**Est. Setup Time**: 5 minutes
|
|
**Database**: PostgreSQL with BetterAuth schema
|
|
**Auth Methods**: 5 (Email, Google, GitHub, Facebook, Discord)
|