Skip to content

README.md

Latest commit

 

History

History
186 lines (133 loc) · 6.54 KB

README.md

File metadata and controls

186 lines (133 loc) · 6.54 KB

GitHub OAuth Integration

This directory contains the GitHub OAuth integration implementation, demonstrating how to use the composable OAuth interface to authenticate with GitHub API.

Setup

1. Configure GitHub OAuth App

Important: GitHub OAuth Apps support only one authorization callback URL. If you have an existing OAuth App for production, you'll need to create a separate OAuth App for local development.

  1. Log in to GitHub and go to Settings > Developer settings > OAuth Apps
  2. Click New OAuth App
  3. Fill in the required fields:
    • Application name: Your application name (e.g., "My App - Local Development")
    • Homepage URL: Your application homepage (can be http://localhost for testing)
    • Authorization callback URL: http://localhost:3000/auth_flow (or any port you prefer)
    • Note: This must be the exact callback URL you'll use locally. GitHub OAuth Apps do not support multiple callback URLs.
  4. Click Register application
  5. Copy the Client ID and generate a Client Secret

Why a separate app?: Unlike GitHub Apps, OAuth Apps are limited to a single callback URL. If your redirect_uri doesn't match exactly (including host, port, and path), the authorization will fail. For local development, create a dedicated OAuth App with a localhost callback URL.

2. Create Configuration File

Create github/secrets/config.json with your GitHub OAuth credentials:

{
  "client_id": "your-github-client-id",
  "client_secret": "your-github-client-secret",
  "redirect_uri": "http://localhost:3000/auth_flow",
  "scopes": [
    "repo",
    "read:org",
    "read:repo_hook",
    "read:user",
    "read:project",
    "read:discussion",
    "workflow"
  ]
}

Note: The scopes listed above are the default scopes. You can modify them based on your needs. See GitHub OAuth Scopes for available scopes.

3. Run OAuth Flow

Execute the OAuth flow script to obtain access tokens:

python github/oauth_flow.py

This will:

  1. Open your browser to the GitHub authorization page
  2. Start a local HTTP server on the port specified in your redirect_uri to handle the callback
  3. Exchange the authorization code for access tokens
  4. Save tokens to github/secrets/tokens.json

4. Use Tokens to Access API

Once tokens are obtained, you can use them to make authenticated API requests:

python github/get.py

This script demonstrates fetching user information and repositories from the GitHub API using the stored access token.

Files

  • oauth_definition.py - GitHubOAuthDefinition class extending BaseOAuthDefinition
  • oauth_flow.py - Interactive CLI script for OAuth flow
  • get.py - POC script demonstrating API access with tokens
  • secrets/config.json - OAuth client credentials (create this file)
  • secrets/tokens.json - Access tokens (generated by oauth_flow.py)

GitHub-Specific Details

Endpoints

  • Authorization: https://github.com/login/oauth/authorize
  • Token Exchange: https://github.com/login/oauth/access_token
  • API Base: https://api.github.com/

Token Exchange Format

GitHub uses form-encoded data for token exchange:

  • Content-Type: application/x-www-form-urlencoded
  • Accept: application/json (to receive JSON response)
  • Request body is URL-encoded form data

Scopes

Default scopes included:

  • repo - Full control of private repositories
  • read:org - Read org and team membership
  • read:repo_hook - Read repository hooks
  • read:user - Read user profile data
  • read:project - Read project data
  • read:discussion - Read discussion data
  • workflow - Update GitHub Action workflows

See GitHub OAuth Scopes for the complete list.

Troubleshooting

Port Already in Use

If the specified port is already in use, change the redirect_uri in config.json to use a different port (e.g., http://localhost:9001/auth_flow). Make sure the same redirect URI is registered in your GitHub OAuth App settings.

Authorization Failed

  • Verify your client_id and client_secret are correct
  • Ensure the redirect_uri in config matches exactly what's registered in GitHub OAuth App
  • Check that your OAuth App is active and not suspended
  • Verify the scopes requested are allowed for your OAuth App

Token Expired

GitHub tokens don't expire by default unless revoked. If you receive authentication errors:

  • Check if the token was revoked in GitHub settings
  • Run oauth_flow.py again to obtain a new token

Redirect URI Mismatch

Critical: GitHub OAuth Apps support only one callback URL, and it must match exactly (host, port, and path).

The redirect URI must match exactly between:

  • Your config.json file
  • Your GitHub OAuth App callback URL

Common issues:

  • Using https:// instead of http:// for localhost
  • Port number mismatch
  • Path mismatch (/auth_flow vs /auth_flow/)
  • Using a production OAuth App with a production callback URL for local development

Solution: Create a separate OAuth App specifically for local development with http://localhost:3000/auth_flow as the callback URL.

API Examples

Fetch User Information

import urllib.request
import json

url = "https://api.github.com/user"
access_token = "your-access-token"

req = urllib.request.Request(
    url,
    headers={
        'Authorization': f'Bearer {access_token}',
        'Accept': 'application/vnd.github+json',
        'User-Agent': 'Your-App-Name'
    }
)

with urllib.request.urlopen(req) as response:
    data = json.loads(response.read().decode('utf-8'))
    print(json.dumps(data, indent=2))

Fetch Repositories

url = "https://api.github.com/user/repos?per_page=10&sort=updated"
# Same headers as above

Key Differences from Zendesk

  1. No Subdomain: GitHub doesn't use subdomains like Zendesk
  2. Form-Encoded Token Exchange: GitHub uses application/x-www-form-urlencoded instead of JSON
  3. API Base URL: Uses https://api.github.com instead of subdomain-based URLs
  4. Scope Format: Space-separated scopes in authorization URL
  5. No Refresh Tokens: GitHub tokens don't expire unless revoked

References