324 lines
7.7 KiB
Markdown
324 lines
7.7 KiB
Markdown
# Django REST API - Authentication System
|
||
|
||
Django 6.0 tabanlı, email authentication, JWT tokens ve social login desteği olan modern bir REST API.
|
||
|
||
## 🚀 Özellikler
|
||
|
||
- ✅ **Email-based Authentication** (username yok)
|
||
- ✅ **JWT Tokens** (access + refresh)
|
||
- ✅ **Email Activation** (kayıt sonrası aktivasyon)
|
||
- ✅ **Social Login** (Google, GitHub, Facebook)
|
||
- ✅ **Password Reset** (email ile)
|
||
- ✅ **Rate Limiting** (güvenlik için)
|
||
- ✅ **CORS Support** (SPA frontend'ler için)
|
||
- ✅ **Modern Email Templates** (HTML + plain text)
|
||
|
||
## 📋 Gereksinimler
|
||
|
||
- Python 3.10+
|
||
- Django 6.0
|
||
- PostgreSQL (production) veya SQLite (development)
|
||
- MailPit (development için email testing)
|
||
|
||
## 🛠️ Kurulum
|
||
|
||
### 1. Repository'yi Clone'layın
|
||
```bash
|
||
git clone <your-repo-url>
|
||
cd server
|
||
```
|
||
|
||
### 2. Virtual Environment Oluşturun
|
||
```bash
|
||
python -m venv .venv
|
||
source .venv/bin/activate # Linux/Mac
|
||
# veya
|
||
.venv\Scripts\activate # Windows
|
||
```
|
||
|
||
### 3. Bağımlılıkları Yükleyin
|
||
```bash
|
||
pip install -r req.txt
|
||
```
|
||
|
||
### 4. Environment Variables
|
||
```bash
|
||
cp .env.example .env
|
||
# .env dosyasını düzenleyin
|
||
```
|
||
|
||
### 5. Database Migration
|
||
```bash
|
||
python manage.py migrate
|
||
```
|
||
|
||
### 6. Superuser Oluşturun
|
||
```bash
|
||
python manage.py createsuperuser
|
||
```
|
||
|
||
### 7. Development Server'ı Başlatın
|
||
```bash
|
||
python manage.py runserver
|
||
```
|
||
|
||
API: `http://localhost:8000/api/v1/`
|
||
Admin: `http://localhost:8000/admin/`
|
||
|
||
## 📧 Email Testing (MailPit)
|
||
|
||
Development ortamında email'leri test etmek için MailPit kullanıyoruz.
|
||
|
||
### MailPit Kurulumu
|
||
```bash
|
||
# Docker ile
|
||
docker run -d -p 1025:1025 -p 8025:8025 axllent/mailpit
|
||
|
||
# veya binary ile
|
||
# https://github.com/axllent/mailpit/releases
|
||
```
|
||
|
||
### MailPit Web UI
|
||
`http://localhost:8025` - Gönderilen email'leri görüntüleyin
|
||
|
||
## 🔐 Authentication Endpoints
|
||
|
||
### Register
|
||
```bash
|
||
POST /api/v1/auth/users/
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"email": "user@example.com",
|
||
"password": "StrongP@ssw0rd123",
|
||
"re_password": "StrongP@ssw0rd123",
|
||
"first_name": "Ali",
|
||
"last_name": "Veli"
|
||
}
|
||
```
|
||
|
||
### Activate Account
|
||
```bash
|
||
POST /api/v1/auth/users/activation/
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"uid": "MQ",
|
||
"token": "c4h7vu-..."
|
||
}
|
||
```
|
||
|
||
### Login
|
||
```bash
|
||
POST /api/v1/auth/jwt/create/
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"email": "user@example.com",
|
||
"password": "StrongP@ssw0rd123"
|
||
}
|
||
```
|
||
|
||
### Social Login
|
||
```bash
|
||
POST /api/v1/auth/social/google-oauth2/
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"access_token": "ya29.a0AfH6SMBx..."
|
||
}
|
||
```
|
||
|
||
Detaylı API dokümantasyonu için: [AUTH.md](./AUTH.md)
|
||
|
||
## 🏗️ Proje Yapısı
|
||
|
||
```
|
||
server/
|
||
├── accounts/ # Custom user app
|
||
│ ├── migrations/
|
||
│ ├── models.py # CustomUser model
|
||
│ ├── serializers.py # DRF serializers
|
||
│ ├── views.py # Social login view
|
||
│ ├── admin.py # Admin configuration
|
||
│ ├── pipeline.py # Social auth pipeline
|
||
│ └── urls.py # URL routing
|
||
├── core/ # Project settings
|
||
│ ├── settings.py # Main settings
|
||
│ ├── urls.py # Root URL config
|
||
│ └── wsgi.py
|
||
├── templates/
|
||
│ └── email/ # Email templates
|
||
│ ├── activation_email.html
|
||
│ ├── activation_email.txt
|
||
│ ├── confirmation_email.html
|
||
│ ├── confirmation_email.txt
|
||
│ ├── password_reset_email.html
|
||
│ └── password_reset_email.txt
|
||
├── manage.py
|
||
├── req.txt # Python dependencies
|
||
├── .env.example # Environment variables template
|
||
├── AUTH.md # API documentation
|
||
├── COPILOT_MEMORY.md # Development log
|
||
└── README.md # This file
|
||
```
|
||
|
||
## 🔧 Konfigürasyon
|
||
|
||
### Social Auth Setup
|
||
|
||
#### Google OAuth2
|
||
1. [Google Cloud Console](https://console.developers.google.com/) → Create Project
|
||
2. APIs & Services → Credentials → Create OAuth 2.0 Client ID
|
||
3. Authorized redirect URIs: `http://localhost:8000/api/v1/social/complete/google-oauth2/`
|
||
4. `.env` dosyasına ekleyin:
|
||
```bash
|
||
SOCIAL_AUTH_GOOGLE_OAUTH2_KEY=your-client-id
|
||
SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET=your-client-secret
|
||
```
|
||
|
||
#### GitHub OAuth
|
||
1. [GitHub Settings](https://github.com/settings/developers) → OAuth Apps → New OAuth App
|
||
2. Authorization callback URL: `http://localhost:8000/api/v1/social/complete/github/`
|
||
3. `.env` dosyasına ekleyin:
|
||
```bash
|
||
SOCIAL_AUTH_GITHUB_KEY=your-client-id
|
||
SOCIAL_AUTH_GITHUB_SECRET=your-client-secret
|
||
```
|
||
|
||
#### Facebook OAuth
|
||
1. [Facebook Developers](https://developers.facebook.com/) → Create App
|
||
2. Add Facebook Login product
|
||
3. Valid OAuth Redirect URIs: `http://localhost:8000/api/v1/social/complete/facebook/`
|
||
4. `.env` dosyasına ekleyin:
|
||
```bash
|
||
SOCIAL_AUTH_FACEBOOK_KEY=your-app-id
|
||
SOCIAL_AUTH_FACEBOOK_SECRET=your-app-secret
|
||
```
|
||
|
||
## 🧪 Testing
|
||
|
||
### Manuel Test
|
||
```bash
|
||
# Register
|
||
curl -X POST http://localhost:8000/api/v1/auth/users/ \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"email":"test@example.com","password":"TestP@ss123","re_password":"TestP@ss123","first_name":"Test","last_name":"User"}'
|
||
|
||
# Check MailPit: http://localhost:8025
|
||
|
||
# Activate (uid ve token email'den alın)
|
||
curl -X POST http://localhost:8000/api/v1/auth/users/activation/ \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"uid":"MQ","token":"c4h7vu-..."}'
|
||
|
||
# Login
|
||
curl -X POST http://localhost:8000/api/v1/auth/jwt/create/ \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"email":"test@example.com","password":"TestP@ss123"}'
|
||
```
|
||
|
||
### Unit Tests (TODO)
|
||
```bash
|
||
python manage.py test accounts
|
||
```
|
||
|
||
## 📱 Frontend Entegrasyonu
|
||
|
||
### Nuxt.js / Next.js
|
||
Detaylı entegrasyon örnekleri için [AUTH.md](./AUTH.md) dosyasına bakın.
|
||
|
||
**Temel Flow:**
|
||
1. Frontend'de register form → Backend'e POST
|
||
2. Kullanıcı email'ini kontrol eder
|
||
3. Aktivasyon linkine tıklar → Frontend yakalayıp backend'e POST
|
||
4. Login form → JWT tokens alınır
|
||
5. Tokens localStorage/cookie'de saklanır
|
||
6. Her request'te `Authorization: Bearer <token>` header'ı eklenir
|
||
|
||
## 🚀 Production Deployment
|
||
|
||
### 1. Environment Variables
|
||
```bash
|
||
DEBUG=False
|
||
SECRET_KEY=<strong-random-key>
|
||
ALLOWED_HOSTS=yourdomain.com,api.yourdomain.com
|
||
|
||
# PostgreSQL
|
||
DATABASE_URL=postgresql://user:pass@host:5432/dbname
|
||
|
||
# SMTP Email
|
||
EMAIL_HOST=smtp.gmail.com
|
||
EMAIL_PORT=587
|
||
EMAIL_USE_TLS=True
|
||
EMAIL_HOST_USER=your-email@gmail.com
|
||
EMAIL_HOST_PASSWORD=your-app-password
|
||
|
||
# Social Auth Keys
|
||
SOCIAL_AUTH_GOOGLE_OAUTH2_KEY=...
|
||
SOCIAL_AUTH_GITHUB_KEY=...
|
||
```
|
||
|
||
### 2. Security Settings
|
||
`settings.py` içinde production için:
|
||
```python
|
||
DEBUG = False
|
||
CSRF_COOKIE_SECURE = True
|
||
SESSION_COOKIE_SECURE = True
|
||
SECURE_SSL_REDIRECT = True
|
||
SECURE_HSTS_SECONDS = 31536000
|
||
```
|
||
|
||
### 3. Static Files
|
||
```bash
|
||
python manage.py collectstatic
|
||
```
|
||
|
||
### 4. Database Migration
|
||
```bash
|
||
python manage.py migrate
|
||
```
|
||
|
||
### 5. Gunicorn/uWSGI
|
||
```bash
|
||
gunicorn core.wsgi:application --bind 0.0.0.0:8000
|
||
```
|
||
|
||
## 📚 Dokümantasyon
|
||
|
||
- **API Documentation:** [AUTH.md](./AUTH.md)
|
||
- **Cache Documentation:** [CACHE.md](./CACHE.md)
|
||
- **Development Log:** [COPILOT_MEMORY.md](./COPILOT_MEMORY.md)
|
||
- **Djoser Docs:** https://djoser.readthedocs.io/
|
||
- **SimpleJWT Docs:** https://django-rest-framework-simplejwt.readthedocs.io/
|
||
- **Python Social Auth:** https://python-social-auth.readthedocs.io/
|
||
|
||
## 🤝 Contributing
|
||
|
||
1. Fork the repository
|
||
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
|
||
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
|
||
4. Push to the branch (`git push origin feature/amazing-feature`)
|
||
5. Open a Pull Request
|
||
|
||
## 📝 License
|
||
|
||
This project is licensed under the MIT License.
|
||
|
||
## 👤 Author
|
||
|
||
Your Name - [@yourhandle](https://twitter.com/yourhandle)
|
||
|
||
## 🙏 Acknowledgments
|
||
|
||
- Django Team
|
||
- Django REST Framework
|
||
- Djoser
|
||
- Python Social Auth
|
||
- MailPit
|
||
|
||
---
|
||
|
||
**Happy Coding! 🎉**
|
||
|