OAuth Sample Project

A sample Flask application demonstrating GitHub OAuth authentication and protected API endpoints.

Overview

This project provides a simple implementation of OAuth 2.0 authentication using GitHub as the identity provider. The application allows users to:

• Authenticate using their GitHub account
• Access protected API endpoints that require authentication
• Retrieve random Wikipedia article summaries (as a demo of protected content)

Prerequisites

• Python 3.10 or higher
• GitHub account (for creating OAuth credentials)
• uv package manager (for dependency management)
• Docker (optional, for containerized deployment)

Installation

Local Setup

1. Clone the repository:

   git clone <repository-url>
   cd oauth_sample_project

2. Install uv if you don't have it already:

   pip install uv

3. Create a virtual environment and activate it:

   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

4. Install dependencies using uv:

   uv pip install -r requirements.txt

   Alternatively, you can use the pyproject.toml file:

   uv pip install -e .

Setting Up GitHub OAuth Credentials

1. Go to your GitHub account settings
2. Navigate to Developer settings > OAuth Apps > New OAuth App
3. Fill in the application details:
   • Application name: OAuth Sample Project (or any name you prefer)
   • Homepage URL: http://localhost:8000
   • Authorization callback URL: http://localhost:8000/login/authorized
4. Click Register application
5. On the next page, note your Client ID
6. Click Generate a new client secret and note the generated secret

Configuration

Set the following environment variables:

# Required for authentication
export GITHUB_CLIENT_ID=your_github_client_id
export GITHUB_CLIENT_SECRET=your_github_client_secret

# Optional, but recommended for production
export SECRET_KEY=your_secret_key_for_flask_sessions

On Windows, use:

set GITHUB_CLIENT_ID=your_github_client_id
set GITHUB_CLIENT_SECRET=your_github_client_secret
set SECRET_KEY=your_secret_key_for_flask_sessions

Running the Application

Local Development

Run the Flask application:

python app.py

The application will be available at http://localhost:8000

Using Docker

1. Build the Docker image:

   docker build -t oauth-sample-project .

2. Run the container with your GitHub OAuth credentials:

   docker run -p 8000:8000 \
     -e GITHUB_CLIENT_ID=your_github_client_id \
     -e GITHUB_CLIENT_SECRET=your_github_client_secret \
     -e SECRET_KEY=your_secret_key \
     oauth-sample-project

3. Access the application at http://localhost:8000

Project Structure

• app.py: Main Flask application with OAuth implementation
• main.py: Simple entry point for the application
• requirements.txt: Python dependencies
• pyproject.toml: Project metadata and dependencies
• uv.lock: Lock file for uv package manager
• Dockerfile: Container configuration for Docker deployment

API Endpoints

• /: Main application page (requires authentication)
• /login: Initiates GitHub OAuth flow
• /logout: Logs out the current user
• /login/authorized: OAuth callback endpoint
• /api/random_summary: Returns a random Wikipedia article summary (protected endpoint)
• /api/user: Returns information about the authenticated user (protected endpoint)

Security Notes

• For production use, always set a strong SECRET_KEY
• Never commit your GitHub OAuth credentials to version control

Troubleshooting

• If you encounter authentication errors, verify your GitHub OAuth credentials are correct
• Check that your callback URL matches exactly what you registered on GitHub
• For Docker deployment issues, ensure the container has network access to GitHub's authentication servers

License

[Specify your license here]