diff --git a/.env.demo b/.env.demo index a481af1..960d8fe 100644 --- a/.env.demo +++ b/.env.demo @@ -40,6 +40,12 @@ OAUTH_AUTO_LINK_BY_EMAIL=true # OAUTH_GITHUB_CLIENT_ID=your-github-client-id # OAUTH_GITHUB_CLIENT_SECRET=your-github-client-secret +# OAuth Provider Mode (Authorization Server for MCP/third-party clients) +# Set OAUTH_PROVIDER_ENABLED=true to act as an OAuth 2.0 Authorization Server +OAUTH_PROVIDER_ENABLED=true +# IMPORTANT: Must be HTTPS in production! +OAUTH_ISSUER=http://localhost:8000 + # Frontend settings FRONTEND_PORT=3000 FRONTEND_URL=http://localhost:3000 diff --git a/.env.template b/.env.template index 13491f2..3596eb4 100644 --- a/.env.template +++ b/.env.template @@ -40,6 +40,12 @@ OAUTH_AUTO_LINK_BY_EMAIL=true # OAUTH_GITHUB_CLIENT_ID=your-github-client-id # OAUTH_GITHUB_CLIENT_SECRET=your-github-client-secret +# OAuth Provider Mode (Authorization Server for MCP/third-party clients) +# Set OAUTH_PROVIDER_ENABLED=true to act as an OAuth 2.0 Authorization Server +OAUTH_PROVIDER_ENABLED=false +# IMPORTANT: Must be HTTPS in production! +OAUTH_ISSUER=http://localhost:8000 + # Frontend settings FRONTEND_PORT=3000 FRONTEND_URL=http://localhost:3000 diff --git a/AGENTS.md b/AGENTS.md index 923b667..e59a6aa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -90,6 +90,26 @@ Full OAuth 2.0 Authorization Server for MCP (Model Context Protocol) clients: **Scopes supported:** `openid`, `profile`, `email`, `read:users`, `write:users`, `admin` +**OAuth Configuration (backend `.env`):** +```bash +# OAuth Social Login (as OAuth Consumer) +OAUTH_ENABLED=true # Enable OAuth social login +OAUTH_AUTO_LINK_BY_EMAIL=true # Auto-link accounts by email +OAUTH_STATE_EXPIRE_MINUTES=10 # CSRF state expiration + +# Google OAuth +OAUTH_GOOGLE_CLIENT_ID=your-google-client-id +OAUTH_GOOGLE_CLIENT_SECRET=your-google-client-secret + +# GitHub OAuth +OAUTH_GITHUB_CLIENT_ID=your-github-client-id +OAUTH_GITHUB_CLIENT_SECRET=your-github-client-secret + +# OAuth Provider Mode (as Authorization Server for MCP) +OAUTH_PROVIDER_ENABLED=true # Enable OAuth provider mode +OAUTH_ISSUER=https://api.yourdomain.com # JWT issuer URL (must be HTTPS in production) +``` + ### Database Pattern - **Async SQLAlchemy 2.0** with PostgreSQL - **Connection pooling**: 20 base connections, 50 max overflow diff --git a/README.md b/README.md index 2143960..a378488 100644 --- a/README.md +++ b/README.md @@ -53,12 +53,25 @@ Whether you're building a SaaS, an internal tool, or a side project, PragmaStack ### πŸ” **Authentication & Security** - JWT-based authentication with access + refresh tokens - **OAuth/Social Login** (Google, GitHub) with PKCE support +- **OAuth 2.0 Authorization Server** (MCP-ready) for third-party integrations - Session management with device tracking and revocation - Password reset flow (email integration ready) - Secure password hashing (bcrypt) - CSRF protection, rate limiting, and security headers - Comprehensive security tests (JWT algorithm attacks, session hijacking, privilege escalation) +### πŸ”Œ **OAuth Provider Mode (MCP Integration)** +Full OAuth 2.0 Authorization Server for Model Context Protocol (MCP) and third-party clients: +- **RFC 7636**: Authorization Code Flow with PKCE (S256 only) +- **RFC 8414**: Server metadata discovery at `/.well-known/oauth-authorization-server` +- **RFC 7662**: Token introspection endpoint +- **RFC 7009**: Token revocation endpoint +- **JWT access tokens**: Self-contained, configurable lifetime +- **Opaque refresh tokens**: Secure rotation, database-backed revocation +- **Consent management**: Users can review and revoke app permissions +- **Client management**: Admin endpoints for registering OAuth clients +- **Scopes**: `openid`, `profile`, `email`, `read:users`, `write:users`, `admin` + ### πŸ‘₯ **Multi-Tenancy & Organizations** - Full organization system with role-based access control (Owner, Admin, Member) - Invite/remove members, manage permissions diff --git a/backend/docs/ARCHITECTURE.md b/backend/docs/ARCHITECTURE.md index a491b7c..0172ed4 100644 --- a/backend/docs/ARCHITECTURE.md +++ b/backend/docs/ARCHITECTURE.md @@ -818,6 +818,84 @@ def add_member( pass ``` +### OAuth Integration + +The system supports two OAuth modes: + +#### OAuth Consumer Mode (Social Login) + +Users can authenticate via Google or GitHub OAuth providers: + +```python +# Get authorization URL with PKCE support +GET /oauth/authorize/{provider}?redirect_uri=https://yourapp.com/callback + +# Handle callback and exchange code for tokens +POST /oauth/callback/{provider} +{ + "code": "authorization_code_from_provider", + "state": "csrf_state_token" +} +``` + +**Security Features:** +- PKCE (S256) for Google +- State parameter for CSRF protection +- Nonce for Google OIDC replay attack prevention +- Google ID token signature verification via JWKS +- Email normalization to prevent account duplication +- Auto-linking by email (configurable) + +#### OAuth Provider Mode (MCP Integration) + +Full OAuth 2.0 Authorization Server for third-party clients (RFC compliant): + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ MCP Client β”‚ β”‚ Backend β”‚ +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ + β”‚ β”‚ + β”‚ GET /.well-known/oauth-authorization-serverβ”‚ + │─────────────────────────────────────────────>β”‚ + β”‚ {metadata} β”‚ + β”‚<─────────────────────────────────────────────│ + β”‚ β”‚ + β”‚ GET /oauth/provider/authorize β”‚ + β”‚ ?response_type=code&client_id=... β”‚ + β”‚ &redirect_uri=...&code_challenge=... β”‚ + │─────────────────────────────────────────────>β”‚ + β”‚ β”‚ + β”‚ (User consents) β”‚ + β”‚ β”‚ + β”‚ 302 redirect_uri?code=AUTH_CODE&state=... β”‚ + β”‚<─────────────────────────────────────────────│ + β”‚ β”‚ + β”‚ POST /oauth/provider/token β”‚ + β”‚ {grant_type=authorization_code, β”‚ + β”‚ code=AUTH_CODE, code_verifier=...} β”‚ + │─────────────────────────────────────────────>β”‚ + β”‚ β”‚ + β”‚ {access_token, refresh_token, expires_in} β”‚ + β”‚<─────────────────────────────────────────────│ + β”‚ β”‚ +``` + +**Endpoints:** +- `GET /.well-known/oauth-authorization-server` - RFC 8414 metadata +- `GET /oauth/provider/authorize` - Authorization endpoint +- `POST /oauth/provider/token` - Token endpoint (authorization_code, refresh_token) +- `POST /oauth/provider/revoke` - RFC 7009 token revocation +- `POST /oauth/provider/introspect` - RFC 7662 token introspection + +**Security Features:** +- PKCE S256 required for public clients (plain method rejected) +- Authorization codes are single-use with 10-minute expiry +- Code reuse detection triggers security incident (all tokens revoked) +- Refresh token rotation on use +- Opaque refresh tokens (hashed in database) +- JWT access tokens with standard claims +- Consent management per client + ## Error Handling ### Exception Hierarchy