mirror of
https://github.com/Dvorinka/Trackeep.git
synced 2026-06-04 12:32:58 +00:00
first test
This commit is contained in:
Tomas Dvorak
@@ -0,0 +1,283 @@
|
||||
# Centralized OAuth Service
|
||||
|
||||
This is a **standalone OAuth service** that handles GitHub authentication and email verification for all users. Users never need to set up their own OAuth applications - everything is centralized.
|
||||
|
||||
## 🎯 **How It Works**
|
||||
|
||||
### **For Users:**
|
||||
1. **GitHub OAuth**: Click "Connect GitHub" → GitHub authorization → Automatic login with GitHub profile
|
||||
2. **Email Verification**: Enter email → Receive verification code → Verify email for 2FA
|
||||
|
||||
### **For Developers:**
|
||||
1. **Zero setup** - No OAuth app creation needed
|
||||
2. **Simple integration** - Just redirect to our service
|
||||
3. **Secure authentication** - We handle all the complexity
|
||||
4. **User management** - Centralized user database
|
||||
|
||||
## 🚀 **Quick Start**
|
||||
|
||||
### **1. Setup the OAuth Service**
|
||||
|
||||
```bash
|
||||
# Navigate to the OAuth service
|
||||
cd oauth-service
|
||||
|
||||
# Run the setup script
|
||||
./setup.sh
|
||||
|
||||
# Edit the .env file with your GitHub OAuth credentials
|
||||
nano .env
|
||||
|
||||
# Start the service
|
||||
go run main.go
|
||||
```
|
||||
|
||||
### **2. GitHub OAuth App Setup (One Time)**
|
||||
|
||||
1. Go to GitHub Settings → Developer settings → OAuth Apps
|
||||
2. Create a new OAuth app with:
|
||||
- **Application name**: Trackeep OAuth Service
|
||||
- **Homepage URL**: `http://localhost:9090`
|
||||
- **Authorization callback URL**: `http://localhost:9090/auth/github/callback`
|
||||
3. Copy the Client ID and Client Secret to `.env`
|
||||
|
||||
### **3. Email Verification Setup (One Time)**
|
||||
|
||||
1. Configure smtp.purelymail.com for sending verification emails:
|
||||
- **SMTP Host**: `smtp.purelymail.com`
|
||||
- **SMTP Port**: `587`
|
||||
- **Username**: Your purelymail SMTP username
|
||||
- **Password**: Your purelymail SMTP password
|
||||
2. Add SMTP credentials to `.env` file
|
||||
3. The service will send 6-digit verification codes for 2FA
|
||||
|
||||
### **4. Integration in Your App**
|
||||
|
||||
```javascript
|
||||
// Redirect to GitHub OAuth
|
||||
const connectGitHub = () => {
|
||||
window.location.href = 'http://localhost:9090/auth/github?redirect_uri=' +
|
||||
encodeURIComponent(window.location.origin);
|
||||
};
|
||||
|
||||
// Send email verification code
|
||||
const sendEmailVerification = (email) => {
|
||||
fetch('http://localhost:9090/api/v1/email/send', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({ email })
|
||||
}).then(response => response.json())
|
||||
.then(data => {
|
||||
if (data.demo_code) {
|
||||
console.log('Demo verification code:', data.demo_code);
|
||||
}
|
||||
});
|
||||
};
|
||||
|
||||
// Verify email code
|
||||
const verifyEmailCode = (email, code) => {
|
||||
fetch('http://localhost:9090/api/v1/email/verify', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({ email, code })
|
||||
}).then(response => response.json())
|
||||
.then(data => {
|
||||
if (data.verified) {
|
||||
console.log('Email verified successfully!');
|
||||
}
|
||||
});
|
||||
};
|
||||
|
||||
// Handle callback (works for both GitHub and Email)
|
||||
const handleCallback = () => {
|
||||
const urlParams = new URLSearchParams(window.location.search);
|
||||
const token = urlParams.get('token');
|
||||
const username = urlParams.get('user');
|
||||
|
||||
if (token) {
|
||||
localStorage.setItem('token', token);
|
||||
localStorage.setItem('username', username);
|
||||
// Redirect to dashboard
|
||||
window.location.href = '/app';
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
## 📡 **API Endpoints**
|
||||
|
||||
### **OAuth Endpoints:**
|
||||
- `GET /auth/github` - Initiate GitHub OAuth flow
|
||||
- `GET /auth/github/callback` - Handle GitHub callback
|
||||
|
||||
### **Email Verification Endpoints:**
|
||||
- `POST /api/v1/email/send` - Send verification code to email
|
||||
- `POST /api/v1/email/verify` - Verify email code for 2FA
|
||||
|
||||
### **API Endpoints:**
|
||||
- `GET /api/v1/user/me` - Get current user info
|
||||
- `GET /api/v1/user/:username/repos` - Get user repositories
|
||||
- `POST /api/v1/webhook/github` - GitHub webhook handler
|
||||
- `POST /api/v1/email/verify` - Verify email code
|
||||
|
||||
### **Utility:**
|
||||
- `GET /health` - Service health check
|
||||
|
||||
## 🔧 **Configuration**
|
||||
|
||||
### **Environment Variables:**
|
||||
|
||||
```bash
|
||||
# GitHub OAuth (Admin Only)
|
||||
GITHUB_CLIENT_ID=your_github_client_id
|
||||
GITHUB_CLIENT_SECRET=your_github_client_secret
|
||||
GITHUB_REDIRECT_URL=http://localhost:9090/auth/github/callback
|
||||
|
||||
# Email Verification Configuration (Admin Only)
|
||||
SMTP_HOST=smtp.purelymail.com
|
||||
SMTP_PORT=587
|
||||
SMTP_USERNAME=your_purelymail_username
|
||||
SMTP_PASSWORD=your_purelymail_password
|
||||
|
||||
# Service Configuration
|
||||
PORT=9090
|
||||
JWT_SECRET=your-super-secret-jwt-key
|
||||
DEFAULT_CLIENT_URL=http://localhost:5173
|
||||
|
||||
# CORS
|
||||
CORS_ALLOWED_ORIGINS=http://localhost:5173,http://localhost:8080
|
||||
```
|
||||
|
||||
## 🏗️ **Architecture**
|
||||
|
||||
```
|
||||
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
||||
│ User App │ │ OAuth Service │ │ GitHub │
|
||||
│ │ │ │ │ │
|
||||
│ Connect GitHub ─┼───>│ /auth/github ────>│ OAuth Flow │
|
||||
│ │ │ │ │ │
|
||||
│ Handle Callback │<───>│ /auth/callback │<───>│ Return Token │
|
||||
│ │ │ │ │ │
|
||||
│ Store Token │ │ Generate JWT │ │ │
|
||||
└─────────────────┘ └──────────────────┘ └─────────────────┘
|
||||
```
|
||||
|
||||
## 🔒 **Security Features**
|
||||
|
||||
- **CSRF Protection**: State parameter validation
|
||||
- **Secure JWT**: Signed tokens with expiration
|
||||
- **CORS Support**: Configurable allowed origins
|
||||
- **Webhook Support**: Optional webhook secret validation
|
||||
- **Rate Limiting**: GitHub API rate limit awareness
|
||||
|
||||
## 📊 **User Management**
|
||||
|
||||
The service maintains a centralized user database:
|
||||
|
||||
```go
|
||||
type User struct {
|
||||
ID int `json:"id"`
|
||||
GitHubID int `json:"github_id"`
|
||||
Username string `json:"username"`
|
||||
Email string `json:"email"`
|
||||
Name string `json:"name"`
|
||||
AvatarURL string `json:"avatar_url"`
|
||||
CreatedAt time.Time `json:"created_at"`
|
||||
LastLogin time.Time `json:"last_login"`
|
||||
}
|
||||
```
|
||||
|
||||
## 🔄 **Multi-Application Support**
|
||||
|
||||
The same OAuth service can serve multiple applications:
|
||||
|
||||
```javascript
|
||||
// App 1
|
||||
window.location.href = 'http://localhost:9090/auth/github?redirect_uri=http://app1.com';
|
||||
|
||||
// App 2
|
||||
window.location.href = 'http://localhost:9090/auth/github?redirect_uri=http://app2.com';
|
||||
|
||||
// App 3
|
||||
window.location.href = 'http://localhost:9090/auth/github?redirect_uri=http://app3.com';
|
||||
```
|
||||
|
||||
## 🚀 **Production Deployment**
|
||||
|
||||
### **Docker Deployment:**
|
||||
|
||||
```dockerfile
|
||||
FROM golang:1.21-alpine AS builder
|
||||
WORKDIR /app
|
||||
COPY . .
|
||||
RUN go mod download && go build -o oauth-service
|
||||
|
||||
FROM alpine:latest
|
||||
RUN apk --no-cache add ca-certificates
|
||||
WORKDIR /root/
|
||||
COPY --from=builder /app/oauth-service .
|
||||
COPY .env .
|
||||
EXPOSE 9090
|
||||
CMD ["./oauth-service"]
|
||||
```
|
||||
|
||||
### **Docker Compose:**
|
||||
|
||||
```yaml
|
||||
version: '3.8'
|
||||
services:
|
||||
oauth-service:
|
||||
build: ./oauth-service
|
||||
ports:
|
||||
- "9090:9090"
|
||||
environment:
|
||||
- GITHUB_CLIENT_ID=${GITHUB_CLIENT_ID}
|
||||
- GITHUB_CLIENT_SECRET=${GITHUB_CLIENT_SECRET}
|
||||
- JWT_SECRET=${JWT_SECRET}
|
||||
restart: unless-stopped
|
||||
```
|
||||
|
||||
## 🛠️ **Development**
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
go mod tidy
|
||||
|
||||
# Run in development
|
||||
go run main.go
|
||||
|
||||
# Build for production
|
||||
go build -o oauth-service main.go
|
||||
|
||||
# Run tests
|
||||
go test ./...
|
||||
```
|
||||
|
||||
## 📝 **Benefits**
|
||||
|
||||
### **For Users:**
|
||||
- ✅ **Zero configuration** - No OAuth app setup
|
||||
- ✅ **Single sign-on** - One GitHub account for all apps
|
||||
- ✅ **Secure** - Enterprise-grade security
|
||||
- ✅ **Fast** - Instant authentication
|
||||
|
||||
### **For Developers:**
|
||||
- ✅ **Easy integration** - Just redirect to our service
|
||||
- ✅ **No OAuth management** - We handle everything
|
||||
- ✅ **Centralized users** - Shared user database
|
||||
- ✅ **Scalable** - Serve unlimited applications
|
||||
|
||||
### **For Administrators:**
|
||||
- ✅ **Single control point** - Manage all OAuth in one place
|
||||
- ✅ **Security oversight** - Monitor all authentication
|
||||
- ✅ **Easy updates** - Update OAuth settings once
|
||||
- ✅ **Cost effective** - One OAuth app for all services
|
||||
|
||||
## 🎯 **Use Cases**
|
||||
|
||||
- **SaaS platforms** - Multiple products, one authentication
|
||||
- **Development teams** - Internal tools with GitHub login
|
||||
- **Open source projects** - Contributor authentication
|
||||
- **Enterprise** - Internal service authentication
|
||||
- **API services** - Secure API access with GitHub OAuth
|
||||
|
||||
This service completely abstracts away OAuth complexity while providing enterprise-grade authentication for all your applications!
|
||||
Reference in New Issue
Block a user