spotizerr-dev/AUTH_SETUP.md

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:

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
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:

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:

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:

# 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