Skip to content

GOOGLE.md

Latest commit

 

History

History
208 lines (146 loc) · 5.24 KB

GOOGLE.md

File metadata and controls

208 lines (146 loc) · 5.24 KB

📢 v1.0.0: This guide shows examples for both mark3labs/mcp-go and official modelcontextprotocol/go-sdk. See examples/README.md for complete setup guide.

Google Provider Guide

Overview

Google provider uses OIDC/JWKS for JWT validation with Google's identity platform. Ideal for Google Workspace integration.

When to Use

✅ Good for:

  • Google Workspace integration
  • Consumer applications with Google Sign-In
  • Applications requiring Google account authentication
  • Cross-platform user auth (Android, iOS, Web)

Setup in Google Cloud Console

1. Create OAuth Client

  1. Go to Google Cloud Console
  2. Select your project (or create new)
  3. Navigate to APIs & Services → Credentials
  4. Click Create Credentials → OAuth client ID
  5. Configure OAuth consent screen if prompted (see below)
  6. Select application type:
    • Web application (for proxy mode)
    • Desktop app or iOS/Android (for native mode)

2. Configure OAuth Consent Screen

Required before creating OAuth client:

  1. Navigate to APIs & Services → OAuth consent screen
  2. Choose User Type:
    • Internal - Google Workspace users only
    • External - Anyone with Google account
  3. Fill in:
    • App name: Your MCP Server
    • User support email: Your email
    • Developer contact: Your email
  4. Add scopes:
    • openid
    • profile
    • email
  5. Save and Continue

3. Create OAuth Client ID

For Web Application (Proxy Mode):

  • Authorized JavaScript origins: https://your-server.com
  • Authorized redirect URIs: https://your-server.com/oauth/callback

For Desktop App (Native Mode):

  • No redirect URIs needed (client handles it)

4. Get Configuration Values

After creation, note:

  • Client ID: <id>.apps.googleusercontent.com
  • Client Secret: (for proxy mode only)
  • Issuer: Always https://accounts.google.com

Configuration (Native Mode)

When: Client handles OAuth (Claude Desktop, mobile apps)

oauth.WithOAuth(mux, &oauth.Config{
    Provider: "google",
    Issuer:   "https://accounts.google.com",
    Audience: "123456789.apps.googleusercontent.com",  // Your Client ID
})

Important: For Google, Audience must be your Client ID, not a custom value.

Configuration (Proxy Mode)

When: Server proxies OAuth for simple clients

oauth.WithOAuth(mux, &oauth.Config{
    Provider:     "google",
    Issuer:       "https://accounts.google.com",
    Audience:     "123456789.apps.googleusercontent.com",  // Your Client ID
    ClientID:     "123456789.apps.googleusercontent.com",
    ClientSecret: "GOCSPX-...",                           // From Google Console
    ServerURL:    "https://your-server.com",
    RedirectURIs: "https://your-server.com/oauth/callback",
})

Testing

1. Start MCP Server

export GOOGLE_CLIENT_ID="123456789.apps.googleusercontent.com"
export GOOGLE_CLIENT_SECRET="GOCSPX-..."
go run main.go

2. Test OAuth Flow (Browser)

# Get authorization URL
curl https://your-server.com/.well-known/oauth-authorization-server

# Open in browser to authenticate
open "https://your-server.com/oauth/authorize?..."

3. Test Token Validation

Get token from Google Sign-In, then:

curl -X POST https://your-server.com/mcp \
  -H "Authorization: Bearer <google-id-token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"hello","arguments":{}}}'

User Claims

Google ID tokens include:

{
  "sub": "1234567890",
  "email": "user@gmail.com",
  "email_verified": true,
  "name": "John Doe",
  "picture": "https://...",
  "aud": "your-client-id.apps.googleusercontent.com",
  "iss": "https://accounts.google.com",
  "exp": 1234567890,
  "iat": 1234567890
}

oauth-mcp-proxy extracts:

  • sub → User.Subject
  • email → User.Email
  • name or email → User.Username

Troubleshooting

"Failed to initialize OIDC provider"

  • Check: Can reach https://accounts.google.com/.well-known/openid-configuration
  • Check: No typo in issuer URL (must be exact)

"Invalid audience"

  • Google uses Client ID as audience
  • Check: Config.Audience matches your Client ID exactly
  • Example: 123456789.apps.googleusercontent.com

"redirect_uri_mismatch" error

  • Check: Redirect URI in Google Console matches Config.RedirectURIs
  • Must be exact match (including https://)
  • No localhost in production

"invalid_client" error

  • Check: ClientID and ClientSecret correct
  • Check: Client type matches mode (Web app for proxy mode)

Production Checklist

  • Use HTTPS for all endpoints
  • Store ClientSecret in environment variables
  • Configure OAuth consent screen properly
  • Set appropriate token expiration
  • Verify email domain restrictions if needed
  • Enable Google Account security features
  • Monitor Google API quotas

References