OAuth Setup & Testing Guide

What You'll Learn

• Configure OAuth providers at account and app levels
• Test complete OAuth authorization flows
• Integrate OAuth credentials in agents
• Validate security and error handling
• Debug common OAuth issues

Prerequisites

System Architecture

Fiberwise provides OAuth integration at two levels:

Part 1: Account-Level OAuth Setup

Step 1: Configure OAuth Provider

Configure Gmail OAuth at the account level:

Create a JSON configuration file and import it:

# gmail-oauth.json
{
  "name": "Gmail Integration",
  "type": "oauth2", 
  "client_id": "123456-abc.apps.googleusercontent.com",
  "client_secret": "GOCSPX-your_secret_here",
  "scopes": [
    "https://www.googleapis.com/auth/gmail.readonly",
    "https://www.googleapis.com/auth/gmail.send"
  ]
}

# Import the configuration
fiber app oauth import "gmail-oauth.json"

Step 2: Verify Configuration

# Check the .fiber/oauth/{instance}/ directory for your config
ls .fiber/oauth/local/

# Or view the tracking file
cat .fiber/local/oauth_tracking.json

Expected output:

Configured OAuth Providers:
--------------------------------------------------
Provider ID: gmail
Client ID: 123456-abc.apps.googleusercontent.com
Scopes: https://www.googleapis.com/auth/gmail.readonly, https://www.googleapis.com/auth/gmail.send
Created: 2025-01-10T15:30:00Z
--------------------------------------------------

Step 3: Test OAuth Flow

fiber account oauth auth gmail \
  --config-name myinstance \
  --return-to /dashboard

This command will:

1. Open your browser to Google's OAuth consent page
2. You grant permissions to Fiberwise
3. Google redirects back with authorization code
4. Tokens are stored securely in the database
5. You're redirected to the dashboard

Part 2: App-Level OAuth Setup

Step 1: Install Your App

# Navigate to your app directory
cd my-email-app

# Install the app
fiber app install

Step 2: Create Provider Configuration

Create gmail-provider.json:

{
  "name": "gmail",
  "provider_type": "google",
  "client_id": "123456-abc.apps.googleusercontent.com",
  "client_secret": "GOCSPX-your_secret_here",
  "scopes": ["https://www.googleapis.com/auth/gmail.readonly"],
  "redirect_uri": "http://localhost:7001/api/v1/oauth/callback/gmail"
}

Step 3: Register Provider

fiber app oauth register \
  --provider-config gmail-provider.json \
  --config-name myinstance

Step 4: Verify App Providers

fiber app oauth list-providers --config-name myinstance

Part 3: Web API Testing

Register Provider via API

curl -X POST "http://localhost:7001/api/v1/credentials/oauth/register" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_name": "gmail",
    "client_id": "123456-abc.apps.googleusercontent.com",
    "client_secret": "GOCSPX-your_secret_here",
    "redirect_uri": "http://localhost:7001/api/v1/credentials/auth/callback/gmail",
    "token_data": {
      "authorize_url": "https://accounts.google.com/o/oauth2/auth",
      "token_url": "https://oauth2.googleapis.com/token",
      "scopes": ["https://www.googleapis.com/auth/gmail.readonly"]
    }
  }'

Start OAuth Flow

Open in browser:

http://localhost:7001/api/v1/credentials/auth/gmail?return_to=/dashboard

Check OAuth Connections

curl -X GET "http://localhost:7001/api/v1/credentials/oauth/connections" \
  -H "Authorization: Bearer YOUR_API_KEY"

Part 4: Agent Integration

Create Test Agent

Create oauth_test_agent.py:

from fiberwise_sdk import FiberAgent

class OAuthTestAgent(FiberAgent):
    def __init__(self):
        super().__init__()
        self.oauth = self.get_oauth_provider()

    def process(self, input_data):
        # Test OAuth credential retrieval
        gmail_creds = self.oauth.get_credentials("gmail")

        if not gmail_creds:
            return {"error": "Gmail not authenticated", "authenticated": False}

        try:
            # Test actual Gmail API call
            import googleapiclient.discovery
            service = googleapiclient.discovery.build(
                'gmail', 'v1', credentials=gmail_creds
            )

            # List recent messages
            results = service.users().messages().list(
                userId='me', maxResults=5
            ).execute()

            return {
                "authenticated": True,
                "message_count": len(results.get('messages', [])),
                "status": "success"
            }
        except Exception as e:
            return {
                "authenticated": True,
                "error": f"Gmail API error: {str(e)}",
                "status": "failed"
            }

Test the Agent

fiber activate oauth_test_agent.py --input-data '{"test": "oauth"}'

Expected success output:

{
  "authenticated": true,
  "message_count": 5,
  "status": "success"
}

Part 5: Complete Testing Checklist

Configuration Tests

OAuth Flow Tests

Agent Integration Tests

Security Tests

Part 6: Troubleshooting

Debug Logging

# Enable debug mode
export FIBERWISE_LOG_LEVEL=DEBUG
fiber start --verbose

Database Verification

-- Check stored providers
SELECT id, provider_name, provider_type, created_at FROM oauth_providers;

-- Check user tokens (encrypted)
SELECT user_id, provider_name, expires_at, created_at FROM oauth_credentials;