Rustelo/info/env_config.md

Environment Configuration

This document describes the environment variables needed for the authentication system.

Required Environment Variables

Database Configuration

DATABASE_URL=postgres://username:password@localhost:5432/database_name

JWT Configuration

JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
JWT_ISSUER=rustelo-auth
JWT_ACCESS_TOKEN_EXPIRES_IN=15  # minutes
JWT_REFRESH_TOKEN_EXPIRES_IN=7  # days

Password Security

# Argon2 uses secure defaults, no configuration needed

OAuth2 Configuration

Google OAuth

GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

GitHub OAuth

GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

Discord OAuth

DISCORD_CLIENT_ID=your-discord-client-id
DISCORD_CLIENT_SECRET=your-discord-client-secret

Microsoft OAuth

MICROSOFT_CLIENT_ID=your-microsoft-client-id
MICROSOFT_CLIENT_SECRET=your-microsoft-client-secret
MICROSOFT_TENANT_ID=common  # or your specific tenant ID

OAuth Redirect URLs

OAUTH_REDIRECT_BASE_URL=http://localhost:3030/api/auth/oauth/callback

OAuth Provider Setup

Google OAuth Setup

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google+ API
4. Create OAuth 2.0 credentials
5. Add authorized redirect URIs:
   • http://localhost:3030/api/auth/oauth/callback/google (development)
   • https://yourdomain.com/api/auth/oauth/callback/google (production)

GitHub OAuth Setup

1. Go to GitHub Settings > Developer settings > OAuth Apps
2. Create a new OAuth App
3. Set Authorization callback URL:
   • http://localhost:3030/api/auth/oauth/callback/github (development)
   • https://yourdomain.com/api/auth/oauth/callback/github (production)

Discord OAuth Setup

1. Go to Discord Developer Portal
2. Create a new application
3. Go to OAuth2 settings
4. Add redirect URIs:
   • http://localhost:3030/api/auth/oauth/callback/discord (development)
   • https://yourdomain.com/api/auth/oauth/callback/discord (production)

Microsoft OAuth Setup

1. Go to Azure Portal
2. Register a new application in Azure AD
3. Configure authentication platform (Web)
4. Add redirect URIs:
   • http://localhost:3030/api/auth/oauth/callback/microsoft (development)
   • https://yourdomain.com/api/auth/oauth/callback/microsoft (production)

Database Setup

PostgreSQL Setup

1. Install PostgreSQL
2. Create a database for your application
3. Run the application - tables will be created automatically

Example Database Creation

CREATE DATABASE rustelo_dev;
CREATE USER rustelo_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE rustelo_dev TO rustelo_user;

Security Considerations

Production Environment

• Use strong, unique JWT secrets
• Use HTTPS for all OAuth redirect URLs
• Set secure cookie flags
• Use environment-specific database credentials
• Enable rate limiting
• Use secure password hashing costs (12 or higher)

Development Environment

• Use different credentials than production
• OAuth redirect URLs should point to localhost
• JWT secrets can be simpler for development
• Database can be local

Sample .env File

# Database
DATABASE_URL=postgres://rustelo_user:password@localhost:5432/rustelo_dev

# JWT
JWT_SECRET=development-secret-change-in-production
JWT_ISSUER=rustelo-auth
JWT_ACCESS_TOKEN_EXPIRES_IN=15
JWT_REFRESH_TOKEN_EXPIRES_IN=7

# Password
# Argon2 uses secure defaults, no configuration needed

# OAuth Base URL
OAUTH_REDIRECT_BASE_URL=http://localhost:3030/api/auth/oauth/callback

# Google OAuth (optional)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

# GitHub OAuth (optional)
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

# Discord OAuth (optional)
DISCORD_CLIENT_ID=your-discord-client-id
DISCORD_CLIENT_SECRET=your-discord-client-secret

# Microsoft OAuth (optional)
MICROSOFT_CLIENT_ID=your-microsoft-client-id
MICROSOFT_CLIENT_SECRET=your-microsoft-client-secret
MICROSOFT_TENANT_ID=common

API Endpoints

Authentication Endpoints

• POST /api/auth/register - Register new user
• POST /api/auth/login - Login with email/password
• POST /api/auth/logout - Logout current user
• POST /api/auth/refresh - Refresh access token
• GET /api/auth/profile - Get current user profile
• PUT /api/auth/profile - Update user profile
• POST /api/auth/change-password - Change password

OAuth Endpoints

• GET /api/auth/oauth/providers - Get available OAuth providers
• GET /api/auth/oauth/:provider/authorize - Get OAuth authorization URL
• GET /api/auth/oauth/:provider/callback - Handle OAuth callback

Password Reset Endpoints

• POST /api/auth/password-reset/request - Request password reset
• POST /api/auth/password-reset/confirm - Confirm password reset

Admin Endpoints

• GET /api/auth/admin/users/:id - Get user by ID
• POST /api/auth/admin/users/:id/verify-email - Verify user email
• POST /api/auth/admin/cleanup - Clean up expired tokens/sessions

Usage Examples

Register User

curl -X POST http://localhost:3030/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "username": "newuser",
    "password": "SecurePass123!",
    "display_name": "New User"
  }'

Login

curl -X POST http://localhost:3030/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!",
    "remember_me": true
  }'

Get Profile (with JWT token)

curl -X GET http://localhost:3030/api/auth/profile \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Troubleshooting

Common Issues

1. Database connection failed: Check DATABASE_URL and ensure PostgreSQL is running
2. OAuth callback errors: Verify redirect URLs match exactly in OAuth provider settings
3. JWT token invalid: Check JWT_SECRET and ensure it's the same across restarts
4. Password validation fails: Review password strength requirements

Logging

The system logs authentication events. Check server logs for detailed error messages.