0x1115/github-oauth repository overview

⁠Github OAuth

⁠Overview

This image implements a GitHub OAuth 2.0 authorization code flow server designed for popup-based authentication in web applications. It provides two main endpoints:

• GET /auth: Initiates the OAuth flow by redirecting to GitHub's authorization URL with appropriate query parameters and state management for CSRF protection.
• GET /auth/github/callback: Handles the callback from GitHub after user authorization, verifies the state, exchanges the authorization code for an access token, and returns a client-compatible response via HTML postMessage.

⁠Quick Start

1. Pull image from Docker Hub:

   docker pull 0x1115/github-oauth:latest
   

   Copy
2. Run container with required environment variables:

   docker run -d --name github-oauth \
     -e CLIENT_ID="your-github-client-id" \
     -e CLIENT_SECRET="your-github-client-secret" \
     -e DOMAIN_NAME="https://your-domain.com" \
     -p 8080:8080 \
     0x1115/github-oauth:latest
   

   Copy
3. The server will be accessible at http://localhost:8080. Integrate the /auth endpoint into your web application to start the OAuth flow.

⁠Configuration

The server is configured via environment variables:

• CLIENT_ID: GitHub OAuth Application Client ID (required)
• CLIENT_SECRET: GitHub OAuth Application Client Secret (required)
• DOMAIN_NAME: Fully qualified domain where this server is deployed (required)
• STATE_SIGNING_SECRET: Secret for HMAC signing OAuth state values (optional, defaults to CLIENT_SECRET)
• OAUTH_SCOPE: Comma-separated GitHub OAuth scopes (optional, default: user:email)
• OAUTH_CALLBACK_PATH: Callback endpoint path (optional, default: /auth/github/callback)
• OAUTH_MESSAGE_TYPE: postMessage event type sent to opener window (optional, default: authorization:github)
• POST_MESSAGE_TARGET_ORIGIN: Target origin used in window.opener.postMessage() (optional, default: *)
• STATE_TTL_SECONDS: Time-to-live for OAuth state in signed cookie (optional, default: 600 seconds)

⁠Security Considerations

• The server implements state-based CSRF protection using HMAC-signed HttpOnly cookies with TTL expiry.
• Access tokens are delivered to client opener windows via HTML postMessage, never in URLs or logs, to prevent token leakage.
• Origin validation is configurable for postMessage responses to restrict where tokens can be sent.
• Proper error handling is implemented to avoid leaking sensitive information in error responses or logs.

⁠Testing

The server includes comprehensive unit tests covering all critical functionality, including:

• State generation and validation
• OAuth flow initiation and callback handling
• Access token exchange with GitHub
• Error handling for various failure scenarios
• Popup postMessage response format

⁠Contact

If you want to discuss the design, implementation, or have any questions, please contact the maintainers at [email protected]⁠.