From f8d6dba4dc06031eebf2d40578cc811430340a56 Mon Sep 17 00:00:00 2001 From: Xoconoch Date: Thu, 7 Aug 2025 14:07:43 -0600 Subject: [PATCH] Minor order tweaks --- .dockerignore | 6 + AUTH_SETUP.md | 168 ------------- SSO_IMPLEMENTATION.md | 225 ------------------ .../API_DOCUMENTATION.md | 0 4 files changed, 6 insertions(+), 393 deletions(-) delete mode 100644 AUTH_SETUP.md delete mode 100644 SSO_IMPLEMENTATION.md rename API_DOCUMENTATION.md => docs/API_DOCUMENTATION.md (100%) diff --git a/.dockerignore b/.dockerignore index 51e482d..0a31b95 100755 --- a/.dockerignore +++ b/.dockerignore @@ -4,6 +4,8 @@ .gitattributes # Docker +docker-compose.yaml +docker-compose.yml Dockerfile .dockerignore @@ -54,3 +56,7 @@ static/js/* logs/ data tests/ + +# Non-essential files +docs/ +README.md diff --git a/AUTH_SETUP.md b/AUTH_SETUP.md deleted file mode 100644 index 19ee544..0000000 --- a/AUTH_SETUP.md +++ /dev/null @@ -1,168 +0,0 @@ -# Authentication Setup - -This document outlines how to configure authentication for Spotizerr, including both traditional username/password authentication and SSO (Single Sign-On) with Google and GitHub. - -## Environment Variables - -### Basic Authentication -- `ENABLE_AUTH`: Enable/disable authentication system (default: false) -- `DISABLE_REGISTRATION`: Disable public registration (default: false) -- `JWT_SECRET`: Secret key for JWT token signing (required in production) -- `JWT_ALGORITHM`: JWT algorithm (default: HS256) -- `JWT_EXPIRATION_HOURS`: JWT token expiration time in hours (default: 24) -- `DEFAULT_ADMIN_USERNAME`: Default admin username (default: admin) -- `DEFAULT_ADMIN_PASSWORD`: Default admin password (default: admin123) - -### SSO Configuration -- `SSO_ENABLED`: Enable/disable SSO functionality (default: true) -- `SSO_BASE_REDIRECT_URI`: Base redirect URI for SSO callbacks (default: http://localhost:8000/api/auth/sso/callback) -- `FRONTEND_URL`: Frontend URL for post-authentication redirects (default: http://localhost:3000) - -#### Google SSO -- `GOOGLE_CLIENT_ID`: Google OAuth2 client ID -- `GOOGLE_CLIENT_SECRET`: Google OAuth2 client secret - -#### GitHub SSO -- `GITHUB_CLIENT_ID`: GitHub OAuth2 client ID -- `GITHUB_CLIENT_SECRET`: GitHub OAuth2 client secret - -## Setup Instructions - -### 1. Traditional Authentication Only - -1. Set environment variables: -```bash -ENABLE_AUTH=true -JWT_SECRET=your-super-secret-jwt-key-change-in-production -DEFAULT_ADMIN_USERNAME=admin -DEFAULT_ADMIN_PASSWORD=your-secure-password -``` - -2. Start the application - a default admin user will be created automatically. - -### 2. Google SSO Setup - -1. Go to [Google Cloud Console](https://console.cloud.google.com/) -2. Create a new project or select existing one -3. Enable Google+ API -4. Go to "Credentials" → "Create Credentials" → "OAuth 2.0 Client IDs" -5. Configure OAuth consent screen with your application details -6. Set authorized redirect URIs: - - `http://localhost:8000/api/auth/sso/callback/google` (development) - - `https://yourdomain.com/api/auth/sso/callback/google` (production) -7. Copy Client ID and Client Secret to environment variables: - -```bash -GOOGLE_CLIENT_ID=your-google-client-id -GOOGLE_CLIENT_SECRET=your-google-client-secret -``` - -### 3. GitHub SSO Setup - -1. Go to GitHub Settings → Developer settings → OAuth Apps -2. Click "New OAuth App" -3. Fill in application details: - - Application name: Your app name - - Homepage URL: Your app URL - - Authorization callback URL: - - `http://localhost:8000/api/auth/sso/callback/github` (development) - - `https://yourdomain.com/api/auth/sso/callback/github` (production) -4. Copy Client ID and Client Secret to environment variables: - -```bash -GITHUB_CLIENT_ID=your-github-client-id -GITHUB_CLIENT_SECRET=your-github-client-secret -``` - -### 4. Complete Environment Configuration - -Create a `.env` file with all required variables: - -```bash -# Basic Authentication -ENABLE_AUTH=true -JWT_SECRET=your-super-secret-jwt-key-change-in-production -JWT_EXPIRATION_HOURS=24 -DEFAULT_ADMIN_USERNAME=admin -DEFAULT_ADMIN_PASSWORD=your-secure-password - -# SSO Configuration -SSO_ENABLED=true -SSO_BASE_REDIRECT_URI=http://localhost:8000/api/auth/sso/callback -FRONTEND_URL=http://localhost:3000 - -# Google SSO (optional) -GOOGLE_CLIENT_ID=your-google-client-id -GOOGLE_CLIENT_SECRET=your-google-client-secret - -# GitHub SSO (optional) -GITHUB_CLIENT_ID=your-github-client-id -GITHUB_CLIENT_SECRET=your-github-client-secret -``` - -## API Endpoints - -### Authentication Status -- `GET /api/auth/status` - Get authentication status and available SSO providers - -### Traditional Authentication -- `POST /api/auth/login` - Login with username/password -- `POST /api/auth/register` - Register new user (if enabled) -- `POST /api/auth/logout` - Logout current user - -### SSO Authentication -- `GET /api/auth/sso/status` - Get SSO status and providers -- `GET /api/auth/sso/login/google` - Initiate Google SSO login -- `GET /api/auth/sso/login/github` - Initiate GitHub SSO login -- `GET /api/auth/sso/callback/google` - Google SSO callback (automatic) -- `GET /api/auth/sso/callback/github` - GitHub SSO callback (automatic) -- `POST /api/auth/sso/unlink/{provider}` - Unlink SSO provider from account - -### User Management (Admin only) -- `GET /api/auth/users` - List all users -- `POST /api/auth/users/create` - Create new user -- `DELETE /api/auth/users/{username}` - Delete user -- `PUT /api/auth/users/{username}/role` - Update user role - -## Security Considerations - -1. **HTTPS in Production**: Always use HTTPS in production and set `allow_insecure_http=False` -2. **Secure JWT Secret**: Use a strong, randomly generated JWT secret -3. **Environment Variables**: Never commit sensitive credentials to version control -4. **CORS Configuration**: Configure CORS appropriately for your frontend domain -5. **Cookie Security**: Ensure secure cookie settings in production - -## User Types - -The system supports two types of users: - -1. **Traditional Users**: Created via username/password registration or admin creation -2. **SSO Users**: Created automatically when users authenticate via Google or GitHub - -SSO users: -- Have `sso_provider` and `sso_id` fields populated -- Cannot use password-based authentication -- Can be unlinked from SSO providers by admins -- Get `user` role by default (first user gets `admin` role) - -## Troubleshooting - -### Common Issues - -1. **SSO Login Fails** - - Check OAuth app configuration in Google/GitHub - - Verify redirect URIs match exactly - - Ensure client ID and secret are correct - -2. **CORS Errors** - - Configure CORS middleware to allow your frontend domain - - Check if frontend and backend URLs match configuration - -3. **JWT Token Issues** - - Verify JWT_SECRET is set and consistent - - Check token expiration time - - Ensure clock synchronization between services - -4. **SSO Module Not Available** - - Install fastapi-sso: `pip install fastapi-sso==0.18.0` - - Restart the application after installation \ No newline at end of file diff --git a/SSO_IMPLEMENTATION.md b/SSO_IMPLEMENTATION.md deleted file mode 100644 index d863ed7..0000000 --- a/SSO_IMPLEMENTATION.md +++ /dev/null @@ -1,225 +0,0 @@ -# SSO (Single Sign-On) Implementation for Spotizerr - -## Overview - -I have successfully implemented comprehensive SSO backend logic for Google and GitHub authentication in your Spotizerr application. This implementation integrates seamlessly with your existing JWT-based authentication system. - -## What Was Implemented - -### 1. Dependencies Added -- Added `fastapi-sso==0.18.0` to `requirements.txt` - -### 2. New Files Created -- `routes/auth/sso.py` - Complete SSO implementation with Google & GitHub support -- `routes/auth/sso_example.py` - Example client for testing SSO functionality -- `SSO_IMPLEMENTATION.md` - This documentation file - -### 3. Updated Files -- `routes/auth/__init__.py` - Extended User model to support SSO fields -- `routes/auth/auth.py` - Updated authentication status to include SSO info -- `routes/auth/middleware.py` - Added SSO endpoints to public paths -- `AUTH_SETUP.md` - Comprehensive SSO setup documentation -- `requirements.txt` - Added fastapi-sso dependency - -### 4. Extended User Model -The `User` class now supports: -- `sso_provider` - Which SSO provider was used (google/github) -- `sso_id` - Provider-specific user ID -- `is_sso_user` - Boolean flag for frontend use - -## Environment Configuration - -Create a `.env` file with the following variables: - -```bash -# Basic Authentication -ENABLE_AUTH=true -JWT_SECRET=your-super-secret-jwt-key-change-in-production -JWT_EXPIRATION_HOURS=24 -DEFAULT_ADMIN_USERNAME=admin -DEFAULT_ADMIN_PASSWORD=your-secure-password - -# SSO Configuration -SSO_ENABLED=true -SSO_BASE_REDIRECT_URI=http://localhost:8000/api/auth/sso/callback -FRONTEND_URL=http://localhost:3000 - -# Google SSO (optional) -GOOGLE_CLIENT_ID=your-google-client-id -GOOGLE_CLIENT_SECRET=your-google-client-secret - -# GitHub SSO (optional) -GITHUB_CLIENT_ID=your-github-client-id -GITHUB_CLIENT_SECRET=your-github-client-secret -``` - -## API Endpoints Added - -### SSO Status & Information -- `GET /api/auth/sso/status` - Get SSO configuration and available providers - -### Google SSO -- `GET /api/auth/sso/login/google` - Initiate Google OAuth flow -- `GET /api/auth/sso/callback/google` - Handle Google OAuth callback (automatic) - -### GitHub SSO -- `GET /api/auth/sso/login/github` - Initiate GitHub OAuth flow -- `GET /api/auth/sso/callback/github` - Handle GitHub OAuth callback (automatic) - -### SSO Management -- `POST /api/auth/sso/unlink/{provider}` - Unlink SSO provider from user account - -### Enhanced Authentication Status -- `GET /api/auth/status` - Now includes SSO status and available providers - -## OAuth Provider Setup - -### Google SSO Setup - -1. Go to [Google Cloud Console](https://console.cloud.google.com/) -2. Create a new project or select existing one -3. Enable Google+ API -4. Go to "Credentials" → "Create Credentials" → "OAuth 2.0 Client IDs" -5. Configure OAuth consent screen -6. Set authorized redirect URIs: - - Development: `http://localhost:8000/api/auth/sso/callback/google` - - Production: `https://yourdomain.com/api/auth/sso/callback/google` -7. Copy Client ID and Client Secret to environment variables - -### GitHub SSO Setup - -1. Go to GitHub Settings → Developer settings → OAuth Apps -2. Click "New OAuth App" -3. Fill in application details: - - Application name: Your app name - - Homepage URL: Your app URL - - Authorization callback URL: - - Development: `http://localhost:8000/api/auth/sso/callback/github` - - Production: `https://yourdomain.com/api/auth/sso/callback/github` -4. Copy Client ID and Client Secret to environment variables - -## How It Works - -### SSO Flow -1. User clicks "Login with Google/GitHub" button in frontend -2. Frontend redirects to `/api/auth/sso/login/{provider}` -3. User is redirected to provider's OAuth consent screen -4. After consent, provider redirects to `/api/auth/sso/callback/{provider}` -5. Backend validates OAuth code and retrieves user info -6. System creates or updates user account -7. JWT token is generated and set as HTTP-only cookie -8. User is redirected to frontend with authentication complete - -### User Management -- **New SSO Users**: Automatically created with `user` role (first user gets `admin`) -- **Existing Users**: SSO provider linked to existing account by email -- **Username Generation**: Uses email prefix, ensures uniqueness -- **Password**: SSO users have `password_hash: null` (cannot use password login) - -## Testing the Implementation - -### 1. Install Dependencies -```bash -pip install fastapi-sso==0.18.0 -``` - -### 2. Configure Environment -Set up your `.env` file with the OAuth credentials from Google/GitHub - -### 3. Start the Application -```bash -uvicorn app:app --reload -``` - -### 4. Test SSO Status -```bash -curl http://localhost:8000/api/auth/sso/status -``` - -### 5. Test Authentication Flow -1. Visit `http://localhost:8000/api/auth/sso/login/google` in browser -2. Complete OAuth flow -3. Should redirect to frontend with authentication - -### 6. Programmatic Testing -Run the example script: -```bash -python routes/auth/sso_example.py -``` - -## Security Features - -### Production Ready -- **HTTPS Support**: Set `allow_insecure_http=False` in production -- **Secure Cookies**: HTTP-only cookies with secure flag -- **CORS Configuration**: Properly configured for your frontend domain -- **Token Validation**: Full server-side JWT validation -- **Provider Verification**: Validates OAuth responses from providers - -### OAuth Security -- **State Parameter**: CSRF protection in OAuth flow -- **Redirect URI Validation**: Strict redirect URI matching -- **Token Expiration**: Configurable JWT token expiration -- **Provider Validation**: Ensures tokens come from legitimate providers - -## Integration Points - -### Frontend Integration -The authentication status endpoint now returns SSO information: - -```json -{ - "auth_enabled": true, - "sso_enabled": true, - "sso_providers": ["google", "github"], - "authenticated": false, - "user": null, - "registration_enabled": true -} -``` - -### User Data Structure -SSO users have additional fields: - -```json -{ - "username": "john_doe", - "email": "john@example.com", - "role": "user", - "sso_provider": "google", - "is_sso_user": true, - "created_at": "2024-01-15T10:30:00", - "last_login": "2024-01-15T10:30:00" -} -``` - -## Error Handling - -The implementation includes comprehensive error handling for: -- Missing OAuth credentials -- OAuth flow failures -- Provider-specific errors -- Invalid redirect URIs -- Network timeouts -- Invalid tokens - -## Backwards Compatibility - -- **Existing Users**: Unaffected, can still use password authentication -- **Existing API**: All existing endpoints work unchanged -- **Configuration**: SSO is optional, system works without it -- **Database**: Extends existing user storage, no migration needed - -## Next Steps - -1. **Configure OAuth Apps**: Set up Google and GitHub OAuth applications -2. **Update Frontend**: Add SSO login buttons that redirect to SSO endpoints -3. **Test Flow**: Test complete authentication flow end-to-end -4. **Production Setup**: Configure HTTPS and production redirect URIs -5. **User Management**: Add SSO management to your admin interface - -## Support - -The implementation follows FastAPI best practices and integrates cleanly with your existing authentication system. All SSO functionality is optional and gracefully degrades if not configured. - -For issues or questions, check the comprehensive documentation in `AUTH_SETUP.md` or refer to the example client in `routes/auth/sso_example.py`. \ No newline at end of file diff --git a/API_DOCUMENTATION.md b/docs/API_DOCUMENTATION.md similarity index 100% rename from API_DOCUMENTATION.md rename to docs/API_DOCUMENTATION.md