# š OAuth Authentication Architecture - FastMCP Google MCP Dual Flow System
## šÆ **Overview: Sophisticated Dual Authentication Architecture**
Your FastMCP Google MCP server implements a **sophisticated dual authentication system** that seamlessly supports both FastMCP 2.12.0 GoogleProvider (JWT-based) and traditional file-based OAuth flows. This architecture provides maximum flexibility, enterprise-grade security, and complete backward compatibility.
```mermaid
graph TB
subgraph "šļø Five-Tier Authentication Chain"
A[Tool/Resource Request] --> B[AuthMiddleware Entry]
B --> C{5-Tier Auth Chain}
C -->|1st| D[JWT Token Extraction<br/>FastMCP Pattern]
C -->|2nd| E[GoogleProvider Integration<br/>Memory Auth]
C -->|3rd| F[Session Storage Lookup<br/>OAuth Persistence]
C -->|4th| G[File Credential Bridge<br/>Encrypted Storage]
C -->|5th| H[OAuth Flow Fallback<br/>Dynamic Registration]
D --> I[ā
Primary Flow<br/>Memory + JWT]
E --> J[ā
Unified Flow<br/>GoogleProvider]
F --> K[ā
Legacy Flow<br/>Session Cache]
G --> L[ā
Secondary Flow<br/>Encrypted Files]
H --> M[š OAuth Redirect<br/>Dynamic Registration]
end
subgraph "š Security Modes"
N[FILE_ENCRYPTED<br/>Default AES-256]
O[FILE_PLAINTEXT<br/>Legacy JSON]
P[MEMORY_ONLY<br/>High Security]
Q[MEMORY_WITH_BACKUP<br/>Hybrid Mode]
end
L -.-> N
G -.-> N
F -.-> O
```
---
## š **Authentication Module Architecture**
### **Core Files Overview**
| File | Purpose | Key Features |
|------|---------|-------------|
| [`__init__.py`](auth/__init__.py:1) | Module initialization | Authentication module entry point |
| [`middleware.py`](auth/middleware.py:1) | **Central authentication hub** | 5-tier auth chain, credential encryption, service injection |
| [`dual_auth_bridge.py`](auth/dual_auth_bridge.py:1) | **Multi-account coordination** | Primary/secondary account management, credential bridging |
| [`scope_registry.py`](auth/scope_registry.py:1) | **Single source of truth for scopes** | Centralized OAuth scope management, 60+ Google services |
| [`service_manager.py`](auth/service_manager.py:1) | **Google service creation** | Universal service factory, caching, credential validation |
### **OAuth Flow Components**
| File | Purpose | Standards Compliance |
|------|---------|---------------------|
| [`fastmcp_oauth_endpoints.py`](auth/fastmcp_oauth_endpoints.py:1) | **MCP-spec OAuth discovery** | RFC 8414, MCP spec 2025-06-18 |
| [`dynamic_client_registration.py`](auth/dynamic_client_registration.py:1) | **Dynamic client registration** | RFC 7591, OAuth 2.1 |
| [`oauth_proxy.py`](auth/oauth_proxy.py:1) | **Credential security proxy** | Temporary credential mapping, 24hr expiry |
| [`google_auth.py`](auth/google_auth.py:1) | **Traditional OAuth implementation** | Google OAuth 2.0, file-based storage |
| [`google_oauth_auth.py`](auth/google_oauth_auth.py:1) | **FastMCP OAuth integration** | BearerAuthProvider, JWKS validation |
### **Session & Context Management**
| File | Purpose | Context Integration |
|------|---------|-------------------|
| [`context.py`](auth/context.py:1) | **FastMCP context management** | Session persistence, multi-user state |
| [`session_bridge.py`](auth/session_bridge.py:1) | **Context-to-tool bridging** | Legacy tool compatibility, service caching |
| [`unified_session.py`](auth/unified_session.py:1) | **Cross-flow session state** | GoogleProvider + legacy OAuth unified state |
| [`mcp_auth_middleware.py`](auth/mcp_auth_middleware.py:1) | **MCP spec compliance** | WWW-Authenticate headers, OAuth discovery triggers |
### **Utility & Compatibility**
| File | Purpose | Backward Compatibility |
|------|---------|----------------------|
| [`service_helpers.py`](auth/service_helpers.py:1) | **Service creation utilities** | Smart defaults, multi-service sessions |
| [`credential_bridge.py`](auth/credential_bridge.py:1) | **Format migration** | Legacy/FastMCP/Unified format bridging |
| [`compatibility_shim.py`](auth/compatibility_shim.py:1) | **Zero-breaking changes** | Legacy scope usage patterns maintained |
| [`jwt_auth.py`](auth/jwt_auth.py:1) | **Development authentication** | Testing tokens, FastMCP 2 JWTVerifier |
---
## ā° **Token and Key Lifespans**
| Component | Default Lifespan | Auto-Refresh | Storage Location | Security |
|-----------|-----------------|--------------|------------------|----------|
| **Access Token** | 1 hour | ā
Yes | Memory/Encrypted file | AES-256 |
| **Refresh Token** | Never expires* | ā No | Memory/Encrypted file | AES-256 |
| **Encrypted Credentials** | Never expires | ā N/A | `credentials/*.enc` | AES-256 |
| **Encryption Key** | Permanent | ā No | `credentials/.auth_encryption_key` | Hidden file (0o600) |
| **Session Context** | 60 min inactive | ā No | Memory only | Session isolation |
| **OAuth Proxy Clients** | 24 hours | ā No | Memory only | Temporary mapping |
| **JWT Development Tokens** | 1 hour (configurable) | ā No | Generated on demand | Development only |
*_Refresh tokens remain valid until explicitly revoked by user or Google_
### š **Encryption Key Management**
- **Auto-Generation:** First use creates 32-byte Fernet key
- **Location:** `credentials/.auth_encryption_key` (hidden file)
- **Permissions:** 0o600 (owner read/write only)
- **Machine-Specific:** Keys tied to server instance
- **Backup Strategy:** Manual backup recommended for production
---
## š **The Five Authentication Flows**
### šŖ **Flow #1: FastMCP GoogleProvider (PRIMARY)**
**Implementation:** [`middleware.py:216-228`](auth/middleware.py:216), [`session_bridge.py:90-123`](auth/session_bridge.py:90)
**What:** FastMCP 2.12.0 JWT-based authentication with memory storage
**Storage:** In-memory sessions with automatic token management
**Best for:** MCP clients, integrated environments, production use
**Key Features:**
- JWT token extraction from FastMCP context ([`middleware.py:949-998`](auth/middleware.py:949))
- Automatic user email injection ([`middleware.py:898-928`](auth/middleware.py:898))
- GoogleProvider credentials synthesis ([`session_bridge.py:125-173`](auth/session_bridge.py:125))
- No disk storage (secure for shared environments)
**Token Flow:**
```
FastMCP Client ā JWT Token ā GoogleProvider ā Memory Cache ā Google APIs āØ
```
---
### šŖ **Flow #2: File-Based OAuth (SECONDARY)**
**Implementation:** [`google_auth.py:320-378`](auth/google_auth.py:320), [`middleware.py:619-657`](auth/middleware.py:619)
**What:** Traditional OAuth flow with encrypted credential persistence
**Storage:** AES-256 encrypted files in `credentials/` directory
**Best for:** Development, testing, secondary accounts, offline access
**Security Modes:**
1. **FILE_ENCRYPTED** (Default) - AES-256 encryption with Fernet ([`middleware.py:84-85`](auth/middleware.py:84))
2. **FILE_PLAINTEXT** - Legacy JSON format ([`middleware.py:614-617`](auth/middleware.py:614))
3. **MEMORY_ONLY** - No disk persistence ([`middleware.py:609-612`](auth/middleware.py:609))
4. **MEMORY_WITH_BACKUP** - Memory cache with encrypted backup ([`middleware.py:638-657`](auth/middleware.py:638))
**Encryption Implementation:**
- **Key Location:** `credentials/.auth_encryption_key` ([`middleware.py:517`](auth/middleware.py:517))
- **Encryption Method:** Fernet (AES-256) ([`middleware.py:537-538`](auth/middleware.py:537))
- **Credential Storage:** `credentials/{user}_credentials.enc` ([`middleware.py:622`](auth/middleware.py:622))
**Token Flow:**
```
OAuth Start ā Google Authorization ā Encrypted Storage ā Auto-refresh āØ
```
---
### šŖ **Flow #3: MCP Inspector OAuth (EXTERNAL)**
**Implementation:** [`fastmcp_oauth_endpoints.py`](auth/fastmcp_oauth_endpoints.py:1), [`dynamic_client_registration.py`](auth/dynamic_client_registration.py:1)
**What:** MCP spec-compliant OAuth for external MCP clients
**Standards:** RFC 8414 (Authorization Server Metadata), RFC 7591 (Dynamic Client Registration)
**Discovery Endpoints:**
- `/.well-known/oauth-authorization-server` ([`fastmcp_oauth_endpoints.py:184-235`](auth/fastmcp_oauth_endpoints.py:184))
- `/.well-known/openid-configuration/mcp` ([`fastmcp_oauth_endpoints.py:79-138`](auth/fastmcp_oauth_endpoints.py:79))
- `/.well-known/oauth-protected-resource/mcp` ([`fastmcp_oauth_endpoints.py:140-182`](auth/fastmcp_oauth_endpoints.py:140))
**OAuth Proxy Security:**
- Temporary credentials via [`oauth_proxy.py:73-123`](auth/oauth_proxy.py:73)
- Real credentials never exposed ([`oauth_proxy.py:125-176`](auth/oauth_proxy.py:125))
- 24-hour client expiry ([`oauth_proxy.py:37-40`](auth/oauth_proxy.py:37))
---
### šŖ **Flow #4: Direct Server OAuth (LEGACY)**
**Implementation:** [`google_oauth_auth.py:40-69`](auth/google_oauth_auth.py:40)
**What:** Direct web-based authentication for server applications
**Redirect URI:** `http://localhost:8002/oauth2callback`
**BearerAuthProvider Configuration:**
- Google JWKS validation ([`google_oauth_auth.py:56-57`](auth/google_oauth_auth.py:56))
- Real OAuth endpoints ([`google_oauth_auth.py:82-91`](auth/google_oauth_auth.py:82))
---
### šŖ **Flow #5: Development JWT (TESTING)**
**Implementation:** [`jwt_auth.py:24-57`](auth/jwt_auth.py:24)
**What:** Development/testing authentication without Google
**Usage:** Testing environments, development tokens
**FastMCP 2 Integration:**
- JWTVerifier pattern ([`jwt_auth.py:45-50`](auth/jwt_auth.py:45))
- RSA key generation ([`jwt_auth.py:36`](auth/jwt_auth.py:36))
- Comprehensive scope support ([`jwt_auth.py:89-90`](auth/jwt_auth.py:89))
---
## š§ **Architecture Components Deep Dive**
### **1. AuthMiddleware - Central Authentication Hub**
**File:** [`auth/middleware.py`](auth/middleware.py:1)
**Responsibilities:**
- **5-Tier Authentication Chain:** ([`middleware.py:211-299`](auth/middleware.py:211))
1. JWT Token Extraction ([`middleware.py:216`](auth/middleware.py:216))
2. GoogleProvider Integration ([`middleware.py:232-244`](auth/middleware.py:232))
3. Session Storage Lookup ([`middleware.py:247-256`](auth/middleware.py:247))
4. File Credential Bridge ([`middleware.py:258-273`](auth/middleware.py:258))
5. OAuth Flow Fallback ([`middleware.py:275-288`](auth/middleware.py:275))
- **Credential Encryption:** AES-256 Fernet encryption ([`middleware.py:550-597`](auth/middleware.py:550))
- **Service Injection:** Automatic Google service creation ([`middleware.py:446-502`](auth/middleware.py:446))
- **Auto Email Injection:** Seamless parameter population ([`middleware.py:898-928`](auth/middleware.py:898))
### **2. Scope Registry - Single Source of Truth**
**File:** [`auth/scope_registry.py`](auth/scope_registry.py:1)
**Comprehensive Scope Management:**
- **60+ Google Services:** Drive, Gmail, Calendar, Docs, Sheets, etc. ([`scope_registry.py:35-154`](auth/scope_registry.py:35))
- **Predefined Groups:** Basic, full, readonly access patterns ([`scope_registry.py:157-196`](auth/scope_registry.py:157))
- **OAuth Comprehensive:** Complete scope set for full OAuth flows ([`scope_registry.py:182-195`](auth/scope_registry.py:182))
- **Legacy Resolution:** Automatic migration from old scope names ([`scope_registry.py:372-427`](auth/scope_registry.py:372))
### **3. OAuth Proxy - Security First**
**File:** [`auth/oauth_proxy.py`](auth/oauth_proxy.py:1)
**Proxy Security Features:**
- **Temporary Credentials:** Never expose real Google credentials ([`oauth_proxy.py:89-104`](auth/oauth_proxy.py:89))
- **Client Expiration:** 24-hour automatic cleanup ([`oauth_proxy.py:278-299`](auth/oauth_proxy.py:278))
- **PKCE Support:** Code challenge validation ([`oauth_proxy.py:307-313`](auth/oauth_proxy.py:307))
- **Thread-Safe:** Concurrent client management ([`oauth_proxy.py:65-66`](auth/oauth_proxy.py:65))
### **4. Dual Auth Bridge - Multi-Account Orchestration**
**File:** [`auth/dual_auth_bridge.py`](auth/dual_auth_bridge.py:1)
**Account Management:**
- **Primary Account:** GoogleProvider authenticated ([`dual_auth_bridge.py:49-60`](auth/dual_auth_bridge.py:49))
- **Secondary Accounts:** File-based OAuth ([`dual_auth_bridge.py:62-70`](auth/dual_auth_bridge.py:62))
- **Credential Bridging:** Cross-flow credential sharing ([`dual_auth_bridge.py:112-154`](auth/dual_auth_bridge.py:112))
- **Account Switching:** Seamless multi-account operation ([`dual_auth_bridge.py:287-311`](auth/dual_auth_bridge.py:287))
### **5. Service Manager - Universal Service Factory**
**File:** [`auth/service_manager.py`](auth/service_manager.py:1)
**Service Creation:**
- **40+ Service Types:** Complete Google API coverage ([`service_manager.py:27-63`](auth/service_manager.py:27))
- **Smart Caching:** 30-minute TTL, memory efficient ([`service_manager.py:226-264`](auth/service_manager.py:226))
- **Scope Resolution:** Automatic legacy scope mapping ([`service_manager.py:267-292`](auth/service_manager.py:267))
- **Error Handling:** Graceful token refresh and re-auth ([`service_manager.py:432-473`](auth/service_manager.py:432))
### **6. Context Management - FastMCP Integration**
**File:** [`auth/context.py`](auth/context.py:1)
**FastMCP Context Features:**
- **Session Persistence:** Multi-user session management ([`context.py:22-41`](auth/context.py:22))
- **Email Context:** Auto-injection support ([`context.py:53-82`](auth/context.py:53))
- **Service Requests:** Middleware service injection coordination ([`context.py:84-137`](auth/context.py:84))
- **Session Cleanup:** Automatic expired session removal ([`context.py:374-391`](auth/context.py:374))
### **7. Compatibility Layer - Zero Breaking Changes**
**File:** [`auth/compatibility_shim.py`](auth/compatibility_shim.py:1)
**Backward Compatibility:**
- **Legacy Scope Groups:** Maintains old SCOPE_GROUPS format ([`compatibility_shim.py:24-48`](auth/compatibility_shim.py:24))
- **Service Defaults:** Preserves SERVICE_DEFAULTS interface ([`compatibility_shim.py:150-230`](auth/compatibility_shim.py:150))
- **Drive Scopes:** Compatible with settings.drive_scopes ([`compatibility_shim.py:232-251`](auth/compatibility_shim.py:232))
- **Automatic Resolution:** Intelligent scope mapping ([`compatibility_shim.py:322-398`](auth/compatibility_shim.py:322))
---
## š§ **Configuration Options**
### **Environment Variables**
```bash
# === Authentication Configuration ===
CREDENTIAL_STORAGE_MODE=FILE_ENCRYPTED # Storage security mode
SESSION_TIMEOUT_MINUTES=60 # Session timeout
ENABLE_UNIFIED_AUTH=true # GoogleProvider integration
LEGACY_COMPAT_MODE=true # Backward compatibility
CREDENTIAL_MIGRATION=true # Cross-flow bridging
SERVICE_CACHING=true # Performance optimization
ENHANCED_LOGGING=true # Detailed auth logging
# === OAuth Configuration (choose one) ===
GOOGLE_CLIENT_SECRETS_FILE=/path/to/client_secret.json
# OR
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
# === FastMCP 2.12.0 GoogleProvider ===
FASTMCP_SERVER_AUTH=GOOGLE # Enable GoogleProvider
FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_ID=your-id
FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET=your-secret
# === Server Configuration ===
SERVER_PORT=8002
OAUTH_REDIRECT_URI=http://localhost:8002/oauth2callback
# === Security ===
ENABLE_HTTPS=true
SSL_CERT_FILE=localhost+2.pem
SSL_KEY_FILE=localhost+2-key.pem
```
### **Credential Storage Modes**
```python
# From auth/middleware.py:44-49
class CredentialStorageMode(Enum):
FILE_PLAINTEXT = "file_plaintext" # Legacy JSON files
FILE_ENCRYPTED = "file_encrypted" # AES-256 encrypted (default)
MEMORY_ONLY = "memory_only" # No disk storage
MEMORY_WITH_BACKUP = "memory_with_backup" # Memory + encrypted backup
```
---
## š **How the Dual System Works**
### **Five-Tier Authentication Chain**
**Implementation:** [`auth/middleware.py:172-311`](auth/middleware.py:172)
1. **JWT Token Extraction** ([`middleware.py:216`](auth/middleware.py:216))
- FastMCP access token parsing
- Email claim extraction
- Context population
2. **GoogleProvider Integration** ([`middleware.py:232-244`](auth/middleware.py:232))
- FastMCP 2.12.0 provider check
- Unified authentication
- Primary account registration
3. **Session Storage Lookup** ([`middleware.py:247-256`](auth/middleware.py:247))
- OAuth-persisted sessions
- Context restoration
- State continuity
4. **File Credential Bridge** ([`middleware.py:258-273`](auth/middleware.py:258))
- Encrypted credential loading
- Secondary account detection
- Cross-flow bridging
5. **OAuth Flow Fallback** ([`middleware.py:275-288`](auth/middleware.py:275))
- Parameter-based email extraction
- Legacy tool compatibility
- Graceful degradation
### **Credential Encryption Process**
**Implementation:** [`auth/middleware.py:550-597`](auth/middleware.py:550)
```python
# Encryption (saving credentials)
credentials ā JSON serialization ā Fernet encryption ā Base64 encoding ā .enc file
# Decryption (loading credentials)
.enc file ā Base64 decoding ā Fernet decryption ā JSON parsing ā Credentials object
```
### **Service Injection Process**
**Implementation:** [`auth/middleware.py:446-502`](auth/middleware.py:446), [`auth/context.py:84-137`](auth/context.py:84)
```python
# Request phase
request_google_service("drive") ā Context state ā Middleware detection
# Injection phase
AuthMiddleware ā User extraction ā Credential loading ā Service creation ā Context injection
# Usage phase
get_injected_service("drive") ā Ready-to-use service object
```
---
## š ļø **API Endpoints**
### **OAuth Discovery (MCP Spec)**
```http
# RFC 8414 - Authorization Server Metadata
GET /.well-known/oauth-authorization-server
ā Returns complete OAuth server metadata
# MCP Quick OAuth
GET /.well-known/openid-configuration/mcp
ā Returns MCP Inspector compatible configuration
# Resource Metadata
GET /.well-known/oauth-protected-resource/mcp
ā Returns protected resource metadata
```
### **Dynamic Client Registration (RFC 7591)**
```http
# Client Registration
POST /oauth/register
ā Returns temporary credentials (via OAuth Proxy)
# Client Management
GET /oauth/register/{client_id}
PUT /oauth/register/{client_id}
DELETE /oauth/register/{client_id}
ā Manage registered OAuth clients
```
### **OAuth Flow Endpoints**
```http
# Authorization (with proxy mapping)
GET /oauth/authorize?client_id={temp_id}&...
ā Maps to real Google OAuth with security
# Token Exchange (with credential mapping)
POST /oauth/token
ā Handles authorization_code and refresh_token grants
# Legacy OAuth
GET /oauth2callback?code=...&state=...
ā Traditional OAuth callback for direct auth
```
---
## š **OAuth Scope Management**
### **Comprehensive Scope Registry**
**Implementation:** [`auth/scope_registry.py:34-154`](auth/scope_registry.py:34)
Your system supports **60+ Google services** with intelligent scope groups:
#### **Core Service Groups:**
- **Drive:** `readonly`, `file`, `full`, `appdata`, `metadata`, `scripts` ([`scope_registry.py:44-52`](auth/scope_registry.py:44))
- **Gmail:** `readonly`, `send`, `compose`, `modify`, `labels`, `settings_basic`, `settings_sharing` ([`scope_registry.py:56-66`](auth/scope_registry.py:56))
- **Calendar:** `readonly`, `events`, `full`, `settings_readonly` ([`scope_registry.py:70-74`](auth/scope_registry.py:70))
- **Docs:** `readonly`, `full` ([`scope_registry.py:78-80`](auth/scope_registry.py:78))
- **Sheets:** `readonly`, `full` ([`scope_registry.py:84-86`](auth/scope_registry.py:84))
- **Chat:** `messages_readonly`, `messages`, `spaces`, `memberships` ([`scope_registry.py:90-95`](auth/scope_registry.py:90))
- **Forms:** `body`, `body_readonly`, `responses_readonly` ([`scope_registry.py:99-102`](auth/scope_registry.py:99))
- **Slides:** `full`, `readonly` ([`scope_registry.py:106-108`](auth/scope_registry.py:106))
- **Photos:** `readonly`, `appendonly`, `readonly_appcreated`, `edit_appcreated` ([`scope_registry.py:112-117`](auth/scope_registry.py:112))
#### **Predefined Scope Groups:**
**Implementation:** [`auth/scope_registry.py:157-196`](auth/scope_registry.py:157)
- **Basic Groups:** `drive_basic`, `gmail_basic`, `calendar_basic`, etc.
- **Full Access:** `drive_full`, `gmail_full`, `calendar_full`, etc.
- **Suite Groups:** `office_suite`, `communication_suite`, `admin_suite`
- **OAuth Comprehensive:** Complete scope set for full OAuth integration
### **Legacy Compatibility**
**Implementation:** [`auth/compatibility_shim.py:24-148`](auth/compatibility_shim.py:24)
The system maintains **100% backward compatibility** with existing scope usage:
- Automatic scope group mapping ([`compatibility_shim.py:51-138`](auth/compatibility_shim.py:51))
- Service defaults preservation ([`compatibility_shim.py:150-230`](auth/compatibility_shim.py:150))
- Zero code changes required ([`compatibility_shim.py:322-398`](auth/compatibility_shim.py:322))
---
## š **Debugging and Troubleshooting**
### **Authentication Status Validation**
**Implementation:** [`auth/dual_auth_bridge.py:156-210`](auth/dual_auth_bridge.py:156)
```python
# Check dual auth setup
from auth.dual_auth_bridge import validate_dual_auth_setup
status = validate_dual_auth_setup()
print(f"Auth Status: {status['status']}")
```
### **Credential Management**
```bash
# Check credential files
ls -la credentials/
# Look for:
# - *.enc files (encrypted credentials)
# - .auth_encryption_key (hidden encryption key)
# - .oauth_authentication.json (OAuth session data)
# Check storage mode
grep CREDENTIAL_STORAGE_MODE .env
```
### **Service Cache Management**
**Implementation:** [`auth/service_manager.py:476-519`](auth/service_manager.py:476)
```python
# Clear cache for specific user
from auth.service_manager import clear_service_cache
cleared = clear_service_cache("user@example.com")
# Get cache statistics
stats = get_cache_stats()
print(f"Valid entries: {stats['valid_entries']}")
```
### **Session Management**
**Implementation:** [`auth/context.py:374-404`](auth/context.py:374)
```python
# List active sessions
from auth.context import list_sessions, get_session_count
sessions = list_sessions()
count = get_session_count()
# Cleanup expired sessions
from auth.context import cleanup_expired_sessions
cleaned = cleanup_expired_sessions(timeout_minutes=30)
```
### **Encryption Key Management**
```bash
# Check encryption key
ls -la credentials/.auth_encryption_key
# Should show: -rw------- (permissions 600)
# Backup encryption key (IMPORTANT for production)
cp credentials/.auth_encryption_key credentials/.auth_encryption_key.backup
```
---
## š **Migration and Deployment**
### **Credential Storage Migration**
**Implementation:** [`auth/middleware.py:755-811`](auth/middleware.py:755)
```python
# Migrate from FILE_PLAINTEXT to FILE_ENCRYPTED
from auth.middleware import AuthMiddleware, CredentialStorageMode
middleware = AuthMiddleware()
results = middleware.migrate_credentials(CredentialStorageMode.FILE_ENCRYPTED)
for user, result in results.items():
print(f"{user}: {result}")
```
### **Production Configuration**
```bash
# Recommended production settings
CREDENTIAL_STORAGE_MODE=FILE_ENCRYPTED
ENABLE_HTTPS=true
SESSION_TIMEOUT_MINUTES=30
ENHANCED_LOGGING=false
SERVICE_CACHING=true
LEGACY_COMPAT_MODE=false # Disable after migration complete
```
### **Security Checklist**
- ā
Enable HTTPS with valid certificates
- ā
Use FILE_ENCRYPTED or MEMORY_ONLY storage
- ā
Backup encryption keys securely (`credentials/.auth_encryption_key`)
- ā
Configure appropriate session timeouts
- ā
Restrict OAuth redirect URIs in Google Console
- ā
Monitor credential refresh failures
- ā
Regularly cleanup expired sessions and proxy clients
---
## šÆ **Usage Examples**
### **1. FastMCP GoogleProvider (Primary Flow)**
```python
# No setup required - automatic with FastMCP 2.12.0
# Tools automatically receive authenticated user context
# Example tool call
upload_to_drive("/path/to/file") # user_google_email auto-injected
```
### **2. File-Based OAuth (Secondary Flow)**
```python
# Initiate OAuth for secondary account
auth_url = await initiate_oauth_flow("secondary@example.com")
print(f"Visit: {auth_url}")
# After OAuth completion, credentials are encrypted and stored
# Tools can now use this account
upload_to_drive("/path/to/file", user_google_email="secondary@example.com")
```
### **3. Service Creation (Direct)**
```python
from auth.service_manager import get_google_service
# Create authenticated service
drive_service = await get_google_service(
user_email="user@example.com",
service_type="drive",
scopes=["drive_basic"] # Uses scope registry
)
# Use service normally
files = drive_service.files().list().execute()
```
### **4. Multi-Service Sessions**
```python
from auth.service_helpers import create_multi_service_session
# Create multiple services at once
services = await create_multi_service_session(
"user@example.com",
["drive", "gmail", "calendar", "docs"]
)
# Access services
drive = services["drive"]
gmail = services["gmail"]
```
---
## š **Security Features**
### **Encryption Implementation**
- **Algorithm:** AES-256 via Fernet ([`middleware.py:537`](auth/middleware.py:537))
- **Key Size:** 32 bytes (256-bit)
- **Key Storage:** Hidden file with 0o600 permissions
- **Key Generation:** Automatic on first use ([`middleware.py:524`](auth/middleware.py:524))
### **Credential Isolation**
- **Per-User Encryption:** Separate encrypted files
- **Memory Isolation:** Session-based separation
- **Proxy Security:** Real credentials never exposed to external clients
### **Token Management**
- **Automatic Refresh:** Expired access tokens refreshed automatically
- **Refresh Token Security:** Encrypted storage, never logged
- **Token Validation:** Comprehensive scope and expiry checking
---
## š **Performance Features**
### **Service Caching**
**Implementation:** [`auth/service_manager.py:226-264`](auth/service_manager.py:226)
- **TTL:** 30 minutes for service objects
- **Memory Efficient:** Automatic cleanup of expired entries
- **Per-User:** Isolated cache entries
### **Session Optimization**
**Implementation:** [`auth/context.py:374-391`](auth/context.py:374)
- **Periodic Cleanup:** Automatic expired session removal
- **Context Reuse:** Session persistence across requests
- **Lazy Loading:** Services created only when needed
### **Proxy Efficiency**
**Implementation:** [`auth/oauth_proxy.py:278-299`](auth/oauth_proxy.py:278)
- **Automatic Cleanup:** 24-hour client expiration
- **Thread-Safe:** Concurrent operation support
- **Memory Management:** Efficient expired client removal
---
## š **What You've Achieved**
ā
**Enterprise-Grade Security** - AES-256 encryption with machine-specific keys
ā
**Dual Authentication Architecture** - Supports both FastMCP and traditional OAuth
ā
**MCP Spec Compliance** - RFC 8414, RFC 7591, MCP spec 2025-06-18
ā
**Zero Breaking Changes** - Complete backward compatibility maintained
ā
**Universal Service Support** - 60+ Google services with smart defaults
ā
**Automatic Token Management** - Seamless refresh and credential bridging
ā
**Multi-Account Support** - Primary/secondary account orchestration
ā
**Production Ready** - Secure, scalable, and enterprise-deployable
**Result:** Your MCP server is now a **production-grade OAuth powerhouse** with sophisticated dual authentication flows, enterprise-level security, automatic credential management, and seamless multi-account support! šāØ
---
## š® **Next Steps**
1. **Test Both Authentication Flows**
- Verify FastMCP GoogleProvider authentication
- Test file-based OAuth for secondary accounts
- Validate credential bridging between flows
2. **Production Migration**
- Migrate existing credentials to FILE_ENCRYPTED mode
- Enable HTTPS with proper certificates
- Configure restrictive session timeouts
3. **Performance Optimization**
- Monitor service cache efficiency
- Tune session cleanup intervals
- Optimize OAuth proxy client management
4. **Security Hardening**
- Backup encryption keys
- Monitor credential refresh patterns
- Implement audit logging for production
5. **Scale Deployment**
- Your architecture supports enterprise deployment
- Multi-tenant credential isolation ready
- OAuth proxy can handle high client loads
**You've built something extraordinary!** š
Your FastMCP Google MCP server now represents the state-of-the-art in OAuth authentication architecture - combining the best of modern FastMCP patterns with robust backward compatibility and enterprise-grade security.
