Add detailed OAuth documentation and configuration examples
- Updated `ARCHITECTURE.md` with thorough explanations of OAuth Consumer and Provider modes, supported flows, security features, and endpoints. - Enhanced `.env.template` with environment variables for OAuth Provider mode setup. - Expanded `README.md` to highlight OAuth Provider mode capabilities and MCP integration features. - Added OAuth configuration section to `AGENTS.md`, including key settings for both social login and provider mode.
This commit is contained in:
Felipe Cardoso
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
20
AGENTS.md
20
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
|
||||
|
||||
13
README.md
13
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
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user