OAuth Composable Interface

A reusable OAuth 2.0 interface system for building integrations with OAuth-enabled APIs. This project provides a composable architecture that allows you to easily add support for new OAuth providers by implementing provider-specific details while reusing common OAuth flow logic.

Overview

This system demonstrates how to build a composable OAuth interface where:

• Base classes handle common OAuth 2.0 Authorization Code flow logic
• Provider implementations only need to specify provider-specific details (endpoints, token exchange format, etc.)
• Each integration manages its own secrets and configuration independently

Architecture

The system is structured in three layers:

1. Base OAuth Definition (/oauth_definition/) - Reusable OAuth configuration and flow logic

   • BaseOAuthDefinition - Abstract base class defining the OAuth interface
   • OAuthFlowHandler - Interactive browser-based OAuth flow handler

2. Provider Implementations (/zendesk-support/, /github/) - Provider-specific configurations

   • Each provider extends BaseOAuthDefinition
   • Implements provider-specific endpoints and token exchange logic
   • Includes scripts for OAuth flow and API access

3. Secrets Management - Integration-specific configuration and token storage

   • Each integration has its own secrets/ folder
   • Configuration and tokens are isolated per integration
   • All secrets directories are automatically gitignored

Project Structure

oauth-testing/
├── oauth_definition/          # Reusable OAuth components
│   ├── __init__.py
│   ├── base.py                # BaseOAuthDefinition abstract class
│   └── flow_handler.py        # OAuthFlowHandler for interactive flows
├── zendesk-support/           # Zendesk Support integration
│   ├── README.md              # Zendesk-specific setup guide
│   ├── oauth_definition.py   # ZendeskOAuthDefinition
│   ├── oauth_flow.py          # Interactive OAuth flow script
│   ├── get.py                 # API client POC script
│   ├── OAUTH_FLOW.md          # Detailed OAuth flow documentation
│   └── secrets/               # Integration-specific secrets (gitignored)
│       ├── config.json        # OAuth client credentials
│       └── tokens.json        # Access/refresh tokens (generated)
├── github/                    # GitHub integration
│   ├── README.md              # GitHub-specific setup guide
│   ├── oauth_definition.py   # GitHubOAuthDefinition
│   ├── oauth_flow.py          # Interactive OAuth flow script
│   ├── get.py                 # API client POC script
│   └── secrets/               # Integration-specific secrets (gitignored)
│       ├── config.json        # OAuth client credentials
│       └── tokens.json        # Access tokens (generated)
└── README.md                  # This file

Quick Start

Zendesk Support

1. See zendesk-support/README.md for setup instructions
2. Configure OAuth client in Zendesk Admin Center
3. Add credentials to zendesk-support/secrets/config.json
4. Run python zendesk-support/oauth_flow.py
5. Test with python zendesk-support/get.py

GitHub

1. See github/README.md for setup instructions
2. Create OAuth App in GitHub Settings
3. Add credentials to github/secrets/config.json
4. Run python github/oauth_flow.py
5. Test with python github/get.py

How It Works

Base OAuth Definition

The BaseOAuthDefinition abstract class provides:

• Common OAuth properties (client_id, client_secret, redirect_uri, scopes)
• State token generation for CSRF protection
• Authorization URL building
• Abstract methods for provider-specific implementations

OAuth Flow Handler

The OAuthFlowHandler class handles:

• Interactive browser-based OAuth flow
• Local HTTP server for callback handling
• Authorization code exchange
• Token storage

Provider Implementation

Each provider (Zendesk, GitHub) implements:

• authorization_endpoint property - Provider's authorization URL
• token_endpoint property - Provider's token exchange URL
• exchange_code_for_token() method - Provider-specific token exchange logic
• from_config_file() class method - Load configuration from file

Extending for New Providers

To add support for a new OAuth provider:

1. Create provider directory (e.g., new-provider/)
2. Create OAuth definition class extending BaseOAuthDefinition:

   from oauth_definition.base import BaseOAuthDefinition
   
   class NewProviderOAuthDefinition(BaseOAuthDefinition):
       @property
       def authorization_endpoint(self) -> str:
           return "https://provider.com/oauth/authorize"
       
       @property
       def token_endpoint(self) -> str:
           return "https://provider.com/oauth/token"
       
       def exchange_code_for_token(self, code: str, state: str) -> dict:
           # Provider-specific token exchange implementation
           ...

3. Create OAuth flow script using OAuthFlowHandler
4. Create API client script to test API access
5. Create secrets directory with config.json template

See existing implementations (zendesk-support/, github/) for reference.

Key Features

• Composable: Reuse base classes across all providers
• Isolated: Each integration has its own secrets folder
• Interactive: Browser-based OAuth flow with automatic callback handling
• Extensible: Easy to add new providers by implementing provider-specific details
• Secure: CSRF protection via state tokens, secrets automatically gitignored

Security

• All secrets/ directories are automatically ignored via .gitignore
• Never commit OAuth credentials or tokens to version control
• State tokens provide CSRF protection
• Each integration's secrets are isolated

Examples

Zendesk Support

• Uses JSON for token exchange
• Requires subdomain configuration
• Supports refresh tokens

GitHub

• Uses form-encoded data for token exchange
• No subdomain required
• Tokens don't expire unless revoked

Documentation

• Zendesk: See zendesk-support/README.md and zendesk-support/OAUTH_FLOW.md
• GitHub: See github/README.md

Future Enhancements

• Automatic token refresh using refresh tokens
• PKCE support for public clients
• Token expiration checking and automatic renewal
• Support for additional OAuth grant types
• More comprehensive error handling and retry logic
• Token validation utilities
• Rate limiting handling

License

This project is provided as-is for demonstration purposes.