OAuth Authenticators

Overview

OAuth authenticators in FiberWise provide a secure, standardized way to connect your applications with third-party services like Gmail, Slack, GitHub, and many others. The authenticator system separates configuration management from user connections, enabling developers to set up OAuth integrations once and allow multiple users to connect their accounts.

Architecture

The OAuth authenticator system uses a two-level architecture:

1. Developer Level: Authenticators

Developers create and manage OAuth authenticators containing:

• OAuth application credentials (client_id, client_secret)
• Service-specific configuration (scopes, endpoints)
• Custom naming and identification

2. User Level: Connections

End users create connections to authenticators containing:

• User-specific OAuth tokens (access_token, refresh_token)
• Token metadata and expiration
• Service-specific user information

CLI Management

The FiberWise CLI provides comprehensive commands for managing OAuth authenticators:

Import Authenticator (Primary Workflow)

# Import OAuth authenticator config file
fiber app oauth import "path/to/oauth-config.json"

# The command will:
# 1. Upload the config to the platform
# 2. Register it for the current environment
# 3. Update app_manifest.yaml automatically
# 4. Track registration in .fiber/{instance}/oauth_tracking.json

Alternative: Manual File Placement

# For advanced scenarios, place files directly:
# .fiber/oauth/{instance}/oauth-config.json
# This approach requires manual manifest updates

Configuration File Format

Authenticator configuration files use JSON format:

{
  "name": "Gmail Integration",
  "authenticator_type": "gmail",
  "client_id": "your-client-id.googleusercontent.com",
  "client_secret": "your-client-secret",
  "scopes": ["https://www.googleapis.com/auth/gmail.readonly"],
  "custom_name": "production-gmail",
  "display_name": "Production Gmail Access"
}

Environment Management

OAuth authenticators support environment-specific configurations stored in the .fiber/oauth/ directory:

Directory Structure

your-app/
├── .fiber/
│   ├── oauth/
│   │   ├── development/
│   │   │   ├── gmail-auth.json
│   │   │   └── slack-auth.json
│   │   ├── production/
│   │   │   ├── gmail-auth.json
│   │   │   └── slack-auth.json
│   │   └── staging/
│   │       ├── gmail-auth.json
│   │       └── slack-auth.json
│   └── local/
│       └── oauth_tracking.json

Automatic Processing

During app installation, FiberWise automatically:

1. Discovers OAuth configuration files in .fiber/oauth/{instance}/
2. Registers authenticators with the target instance
3. Tracks created authenticator IDs in .fiber/{instance}/oauth_tracking.json
4. Provides feedback on successful registration

Tracking and Metadata

FiberWise maintains comprehensive tracking of OAuth authenticators:

Tracking File Format

{
  "created_authenticators": [
    {
      "authenticator_id": "auth_456",
      "config_file": "gmail-auth.json",
      "service_type": "gmail",
      "custom_name": "production-gmail",
      "created_at": "2025-08-16T10:30:00Z",
      "instance_name": "production"
    }
  ],
  "last_sync": "2025-08-16T10:30:00Z",
  "instance_name": "production"
}

Benefits of Tracking

• Audit Trail: Complete history of created authenticators
• Environment Sync: Track which authenticators exist in each environment
• Deployment Management: Identify configuration drift between environments
• Cleanup Support: Enable safe removal of unused authenticators

Best Practices

🔒 Security

• Never commit secrets: Add .fiber/oauth/ to your .gitignore
• Environment separation: Use different OAuth applications for development and production
• Minimal scopes: Request only the permissions your application actually needs
• Regular rotation: Rotate OAuth secrets periodically

📋 Configuration Management

• Consistent naming: Use descriptive, environment-specific names
• Documentation: Document which OAuth applications correspond to which authenticators
• Version control: Use template files in version control, keep secrets separate
• Instance alignment: Ensure OAuth configurations match your instance strategy

🚀 Deployment

• Automated deployment: Include OAuth setup in your CI/CD pipeline
• Environment parity: Maintain consistent OAuth setup across environments
• Monitoring: Track OAuth authenticator usage and health
• Rollback planning: Plan for OAuth configuration rollbacks

Supported Services

FiberWise supports OAuth integration with major services:

Troubleshooting

Common Issues

Next Steps