OAuth Authentication

FastCMS supports OAuth authentication with 29 providers, allowing users to sign in with their existing accounts.

Supported Providers

All 29 providers are organized into three categories. Most require only a client_id and client_secret; the few exceptions are noted in the Extra fields column.

Social & Tech Platforms (14)

Development & Productivity (11)

Enterprise & Self-Hosted (4)

Tip: the canonical list lives in app/db/models/oauth_provider.py (PROVIDER_METADATA) — it includes auth URLs, token URLs, and default scopes for each provider. New providers only need to be added to that file plus a handler in app/services/oauth_service.py.

Configuration

Method 1: Admin UI (Recommended)

1. Navigate to Admin > Settings > OAuth Providers
2. Click "Add Provider"
3. Select the provider type
4. Enter Client ID and Client Secret
5. Toggle "Enabled" and save

Method 2: Environment Variables

GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

Method 3: API

POST /api/v1/oauth/providers
Authorization: Bearer ADMIN_TOKEN

{
  "provider_type": "google",
  "name": "Google",
  "client_id": "your-client-id.apps.googleusercontent.com",
  "client_secret": "your-client-secret",
  "enabled": true
}

Setting Up Providers

Google OAuth

1. Go to Google Cloud Console
2. Create a project → APIs & Services → Credentials
3. Create OAuth 2.0 Client ID (Web application)
4. Add redirect URI: http://localhost:8000/api/v1/oauth/google/callback
5. Add credentials via Admin UI

GitHub OAuth

1. Go to GitHub Developer Settings
2. Click New OAuth App
3. Set callback URL: http://localhost:8000/api/v1/oauth/github/callback
4. Add credentials via Admin UI

OpenID Connect (Generic)

{
  "provider_type": "oidc",
  "name": "My OIDC Provider",
  "client_id": "your-client-id",
  "client_secret": "your-client-secret",
  "extra_config": {
    "discovery_url": "https://your-provider.com/.well-known/openid-configuration"
  }
}

OAuth Flow

1. Initiate OAuth Login

Redirect users to:

GET /api/v1/oauth/{provider}/login

2. Callback

After authorization, FastCMS automatically:

• Exchanges the code for an access token
• Fetches the user's profile
• Creates or updates the user account
• Returns JWT tokens

Response:

{
  "access_token": "eyJhbGc...",
  "refresh_token": "eyJhbGc...",
  "token_type": "bearer",
  "user": {
    "id": "user-uuid",
    "email": "user@gmail.com",
    "name": "John Doe",
    "verified": true,
    "oauth_provider": "google"
  }
}

Frontend Integration

<a href="http://localhost:8000/api/v1/oauth/google/login">
  Sign in with Google
</a>
<a href="http://localhost:8000/api/v1/oauth/github/login">
  Sign in with GitHub
</a>

Dynamic provider buttons:

const providers = await fetch('/api/v1/oauth/providers/enabled').then(r => r.json());

providers.forEach(provider => {
  const button = document.createElement('a');
  button.href = `/api/v1/oauth/${provider.type}/login`;
  button.textContent = `Sign in with ${provider.name}`;
  loginContainer.appendChild(button);
});

OAuth with Auth Collections

GET /api/v1/oauth/{provider}/login?collection=customers

OAuth Behavior Settings

Security Notes

1. HTTPS in Production — always use HTTPS URLs for OAuth redirects
2. State Parameter — FastCMS includes CSRF protection via state parameter
3. Redirect URI Validation — ensure redirect URIs match exactly in provider settings

Troubleshooting