Initial commit

references/oauth-providers.md

@@ -0,0 +1,190 @@
+# OAuth Provider Setup Guides
+
+Quick setup guides for common OAuth providers with Cloudflare MCP servers.
+
+---
+
+## GitHub
+
+### 1. Create OAuth App
+1. Go to https://github.com/settings/developers
+2. Click "New OAuth App"
+3. Fill in:
+   - **Application name**: My MCP Server
+   - **Homepage URL**: https://my-mcp.workers.dev
+   - **Authorization callback URL**: https://my-mcp.workers.dev/oauth/callback
+4. Click "Register application"
+5. Copy Client ID and Client Secret
+
+### 2. Configure Worker
+```typescript
+import { GitHubHandler } from "@cloudflare/workers-oauth-provider";
+
+defaultHandler: new GitHubHandler({
+  clientId: (env) => env.GITHUB_CLIENT_ID,
+  clientSecret: (env) => env.GITHUB_CLIENT_SECRET,
+  scopes: ["repo", "user:email"],
+})
+```
+
+### 3. Add Secrets
+```bash
+npx wrangler secret put GITHUB_CLIENT_ID
+npx wrangler secret put GITHUB_CLIENT_SECRET
+```
+
+### Common Scopes
+- `repo` - Full repo access
+- `user:email` - Read user email
+- `read:org` - Read org membership
+- `write:org` - Manage org
+- `admin:repo_hook` - Manage webhooks
+
+---
+
+## Google
+
+### 1. Create OAuth Client
+1. Go to https://console.cloud.google.com/apis/credentials
+2. Click "Create Credentials" → "OAuth client ID"
+3. Application type: "Web application"
+4. Authorized redirect URIs: https://my-mcp.workers.dev/oauth/callback
+5. Click "Create"
+6. Copy Client ID and Client Secret
+
+### 2. Configure Worker
+```typescript
+import { GoogleHandler } from "@cloudflare/workers-oauth-provider";
+
+defaultHandler: new GoogleHandler({
+  clientId: (env) => env.GOOGLE_CLIENT_ID,
+  clientSecret: (env) => env.GOOGLE_CLIENT_SECRET,
+  scopes: ["openid", "email", "profile"],
+})
+```
+
+### Common Scopes
+- `openid` - Required for OpenID Connect
+- `email` - User email
+- `profile` - Basic profile
+- `https://www.googleapis.com/auth/drive.readonly` - Read Drive files
+- `https://www.googleapis.com/auth/gmail.readonly` - Read Gmail
+
+---
+
+## Azure AD
+
+### 1. Register Application
+1. Go to https://portal.azure.com → Azure Active Directory
+2. App registrations → New registration
+3. Name: My MCP Server
+4. Redirect URI: https://my-mcp.workers.dev/oauth/callback
+5. Click "Register"
+6. Copy Application (client) ID
+7. Certificates & secrets → New client secret
+8. Copy secret value
+
+### 2. Configure Worker
+```typescript
+import { AzureADHandler } from "@cloudflare/workers-oauth-provider";
+
+defaultHandler: new AzureADHandler({
+  clientId: (env) => env.AZURE_CLIENT_ID,
+  clientSecret: (env) => env.AZURE_CLIENT_SECRET,
+  tenant: "common", // or specific tenant ID
+  scopes: ["openid", "email", "User.Read"],
+})
+```
+
+### Common Scopes
+- `openid` - Required
+- `email` - User email
+- `User.Read` - Read user profile
+- `Files.Read` - Read OneDrive files
+- `Mail.Read` - Read email
+
+---
+
+## Generic OAuth Provider
+
+### For any OAuth 2.1 provider
+```typescript
+import { GenericOAuthHandler } from "@cloudflare/workers-oauth-provider";
+
+defaultHandler: new GenericOAuthHandler({
+  authorizeUrl: "https://provider.com/oauth/authorize",
+  tokenUrl: "https://provider.com/oauth/token",
+  userInfoUrl: "https://provider.com/oauth/userinfo",
+
+  clientId: (env) => env.OAUTH_CLIENT_ID,
+  clientSecret: (env) => env.OAUTH_CLIENT_SECRET,
+  scopes: ["openid", "email"],
+
+  context: async (accessToken) => {
+    const response = await fetch("https://provider.com/oauth/userinfo", {
+      headers: { Authorization: `Bearer ${accessToken}` }
+    });
+    const user = await response.json();
+
+    return {
+      userId: user.id,
+      email: user.email,
+      accessToken
+    };
+  }
+})
+```
+
+---
+
+## Dynamic Client Registration
+
+Skip manual OAuth app creation - let clients register automatically:
+
+```typescript
+export default new OAuthProvider({
+  allowDynamicClientRegistration: true,
+  // No clientId or clientSecret needed!
+})
+```
+
+**How it works**:
+1. Client sends registration request
+2. Server generates client credentials
+3. Stored in KV namespace
+4. Client uses credentials for OAuth flow
+
+**Pros**:
+✅ No manual setup
+✅ Works immediately
+✅ No provider configuration
+
+**Cons**:
+❌ Less control
+❌ Can't track clients externally
+
+---
+
+## Security Best Practices
+
+### Scopes
+✅ Request minimal scopes needed
+❌ Don't request `admin` or `delete` unless necessary
+
+### Secrets
+✅ Use `npx wrangler secret put`
+❌ Never commit secrets to git
+❌ Never put secrets in wrangler.jsonc
+
+### Redirect URIs
+✅ Use HTTPS in production
+✅ Specify exact URI (not wildcard)
+❌ Don't use localhost in production
+
+### Consent Screen
+✅ Always enable in production: `allowConsentScreen: true`
+❌ Never disable consent screen for public apps
+
+---
+
+**Need help?** See `authentication.md` for full OAuth patterns.