Flowless Docs

Appearance

On this page

Social Authentication Setup ​

Configure OAuth 2.0 social authentication providers for your Flowless instance to enable login with Google, Facebook, GitHub, and more.

Overview ​

Flowless supports social authentication (OAuth 2.0) with popular providers:

  • ✅ Google
  • ✅ Facebook
  • ✅ GitHub
  • ✅ Twitter
  • ✅ LinkedIn
  • ✅ Custom OAuth 2.0 providers

Benefits of Social Auth ​

  • Faster Registration: Users can sign up in one click
  • Better Security: No password to remember or manage
  • Higher Conversion: Reduces friction in signup process
  • Verified Emails: Social providers verify email addresses
  • Profile Data: Get user's name, picture, and email automatically

Flowless Environment Configuration ​

Required variables ​

env
API_BASE_URL=https://your-api.com       # Used to build OAuth callback URLs
FRONTEND_URL=https://your-frontend.com  # Used for post-login redirects
SOCIAL_LOGIN=true                       # Global social login feature switch

callback_mode — Secure Token Transport ​

Controls how the session token is delivered after a web OAuth callback. Configure via SOCIAL_AUTH_MCU or the SOCIAL_AUTH JSON variable.

ModeDescriptionsessionId in URL?Recommended
cookie (default)Full session delivered via HTTP-only cookie. Frontend calls GET /auth/session/current.❌ No (full session)✅ Yes
params (legacy)?session_id=xxx appended to redirect URL.✅ Always⚠️ Legacy only

⚠️ Important — 2FA exception: Even when callback_mode=cookie is configured, social login with two-factor authentication always includes the partial session_id in the redirect URL:

/login?social_login=success&requires_2fa=true&session_id=ses_partial_xyz&provider=google

This is required because Safari's Intelligent Tracking Prevention (ITP) and other privacy-focused browsers block cookies set during cross-origin OAuth redirect chains (Google → API → Frontend). Relying on the cookie alone for the 2FA step would cause the OTP form to never appear in these browsers.

This is safe: the partial session expires in 5 minutes and still requires a valid OTP code to become a full session. The frontend removes session_id from the browser URL history immediately after consuming it.

env
# MCU format (recommended)
SOCIAL_AUTH_MCU=social://enabled@config/v1?callback_mode=cookie&providers=google&...

# JSON format
SOCIAL_AUTH='{"enabled":true,"callback_mode":"cookie","providers":{...}}'

Note: callback_mode=cookie is the default. You only need to set it explicitly if you want legacy params behavior.

General Setup Process ​

For each provider, you'll need to:

  1. Create an app in the provider's developer console
  2. Get Client ID and Client Secret
  3. Configure redirect URI to ${API_BASE_URL}/auth/social/{provider}/callback
  4. Add credentials to Flowless via SOCIAL_AUTH_MCU or SOCIAL_AUTH
  5. Enable the provider

Google OAuth Setup ​

Step 1: Create Google OAuth App ​

  1. Go to Google Cloud Console
  2. Create a new project or select existing
  3. Navigate to APIs & Services → Credentials
  4. Click Create Credentials → OAuth 2.0 Client ID
  5. Select Web application
  1. Go to OAuth consent screen
  2. Select External user type
  3. Fill in app information:
    • App name: Your app name
    • User support email: Your email
    • Developer contact: Your email
  4. Add scopes:
    • userinfo.email
    • userinfo.profile
  5. Save and continue

Step 3: Get Credentials ​

  1. Go back to Credentials
  2. Create OAuth 2.0 Client ID
  3. Add authorized redirect URIs:
    https://your-instance.pubflow.com/auth/social/google/callback
  4. Copy Client ID and Client Secret

Step 4: Add to Flowless ​

  1. Go to Pubflow Dashboard → Your Instance → Settings → Social Auth
  2. Enable Google
  3. Enter:
    • Client ID: Your Google Client ID
    • Client Secret: Your Google Client Secret
  4. Save

Facebook OAuth Setup ​

Step 1: Create Facebook App ​

  1. Go to Facebook Developers
  2. Click My Apps → Create App
  3. Select Consumer app type
  4. Fill in app details

Step 2: Configure Facebook Login ​

  1. Add Facebook Login product
  2. Go to Settings → Basic
  3. Add App Domains: your-instance.pubflow.com
  4. Copy App ID and App Secret

Step 3: Configure OAuth Redirect ​

  1. Go to Facebook Login → Settings
  2. Add Valid OAuth Redirect URIs:
    https://your-instance.pubflow.com/auth/social/facebook/callback
  3. Save changes

Step 4: Add to Flowless ​

  1. Go to Pubflow Dashboard → Social Auth
  2. Enable Facebook
  3. Enter:
    • App ID: Your Facebook App ID
    • App Secret: Your Facebook App Secret
  4. Save

GitHub OAuth Setup ​

Step 1: Create GitHub OAuth App ​

  1. Go to GitHub Settings
  2. Click OAuth Apps → New OAuth App
  3. Fill in:
    • Application name: Your app name
    • Homepage URL: https://yourdomain.com
    • Authorization callback URL:
      https://your-instance.pubflow.com/auth/social/github/callback
  4. Click Register application

Step 2: Get Credentials ​

  1. Copy Client ID
  2. Generate Client Secret
  3. Copy Client Secret

Step 3: Add to Flowless ​

  1. Go to Pubflow Dashboard → Social Auth
  2. Enable GitHub
  3. Enter:
    • Client ID: Your GitHub Client ID
    • Client Secret: Your GitHub Client Secret
  4. Save

Twitter OAuth Setup ​

Step 1: Create Twitter App ​

  1. Go to Twitter Developer Portal
  2. Create a new project and app
  3. Go to App Settings → User authentication settings
  4. Enable OAuth 2.0

Step 2: Configure OAuth ​

  1. Set Type of App: Web App
  2. Add Callback URI:
    https://your-instance.pubflow.com/auth/social/twitter/callback
  3. Add Website URL: https://yourdomain.com
  4. Copy Client ID and Client Secret

Step 3: Add to Flowless ​

  1. Go to Pubflow Dashboard → Social Auth
  2. Enable Twitter
  3. Enter:
    • Client ID: Your Twitter Client ID
    • Client Secret: Your Twitter Client Secret
  4. Save

LinkedIn OAuth Setup ​

Step 1: Create LinkedIn App ​

  1. Go to LinkedIn Developers
  2. Click Create app
  3. Fill in app details
  4. Verify your app

Step 2: Configure OAuth ​

  1. Go to Auth tab
  2. Add Redirect URLs:
    https://your-instance.pubflow.com/auth/social/linkedin/callback
  3. Request Sign In with LinkedIn product
  4. Copy Client ID and Client Secret

Step 3: Add to Flowless ​

  1. Go to Pubflow Dashboard → Social Auth
  2. Enable LinkedIn
  3. Enter:
    • Client ID: Your LinkedIn Client ID
    • Client Secret: Your LinkedIn Client Secret
  4. Save

Custom OAuth Provider ​

Step 1: Configure Custom Provider ​

  1. Go to Pubflow Dashboard → Social Auth → Custom Provider
  2. Click Add Custom Provider
  3. Fill in:
    • Provider Name: e.g., "MyProvider"
    • Authorization URL: https://provider.com/oauth/authorize
    • Token URL: https://provider.com/oauth/token
    • User Info URL: https://provider.com/oauth/userinfo
    • Client ID: Your client ID
    • Client Secret: Your client secret
    • Scopes: email profile

Step 2: Configure Redirect URI ​

Add this redirect URI to your OAuth provider:

https://your-instance.pubflow.com/auth/social/custom/callback

Testing Social Auth ​

Test Login Flow ​

  1. Go to your app's login page
  2. Click "Login with Google" (or other provider)
  3. Authorize the app
  4. Verify you're logged in
  5. Check user data is correct

Test via API ​

bash
# Initiate OAuth flow
curl https://your-instance.pubflow.com/auth/social/google

# This will redirect to Google's OAuth page
# After authorization, user is redirected back with session_id

Frontend Implementation ​

React Example ​

typescript
function SocialLogin() {
  const handleGoogleLogin = () => {
    window.location.href = `${FLOWLESS_URL}/auth/social/google`;
  };

  const handleFacebookLogin = () => {
    window.location.href = `${FLOWLESS_URL}/auth/social/facebook`;
  };

  const handleGitHubLogin = () => {
    window.location.href = `${FLOWLESS_URL}/auth/social/github`;
  };

  return (
    <div>
      <button onClick={handleGoogleLogin}>
        Login with Google
      </button>
      <button onClick={handleFacebookLogin}>
        Login with Facebook
      </button>
      <button onClick={handleGitHubLogin}>
        Login with GitHub
      </button>
    </div>
  );
}

Handling Callback ​

Cookie mode (default, recommended) — full session (no 2FA)

After OAuth completes with no 2FA required, Flowless redirects without exposing the session token in the URL:

https://yourdomain.com/login?social_login=success&provider=google

Your frontend calls GET /auth/session/current (with credentials: 'include') to resolve the session:

typescript
useEffect(() => {
  const params = new URLSearchParams(window.location.search);
  if (params.get('social_login') !== 'success') return;
  if (params.get('session_id')) return; // 2FA case — handled separately

  fetch(`${FLOWLESS_URL}/auth/session/current`, { credentials: 'include' })
    .then(r => r.json())
    .then(data => {
      if (data.success && data.user) {
        localStorage.setItem('pubflow_session_id', data.sessionId);
        window.location.href = '/dashboard';
      }
    });
}, []);

Cookie mode (default, recommended) — 2FA pending

When the authenticated user has 2FA enabled, the redirect always includes session_id in the URL, even with callback_mode=cookie. This is required to bypass Safari ITP cookie blocking:

https://yourdomain.com/login?social_login=success&requires_2fa=true&session_id=ses_partial_xyz&provider=google

Your frontend reads session_id from the URL, shows the OTP form, and should clean the param from browser history after consuming it:

typescript
// Clean session_id from URL history after consuming it
const clean = new URL(window.location.href);
clean.searchParams.delete('session_id');
window.history.replaceState(null, '', clean.toString());

Params mode (legacy only)

Only use this if your frontend cannot call /auth/session/current. Set callback_mode=params in your config. The full session token will appear in the redirect URL:

https://yourdomain.com/login?social_login=success&provider=google&session_id=ses_xyz123

⚠️ Security note: Params mode exposes the full session token in browser history, server logs, and Referer headers. Prefer cookie mode for all new deployments.

Account Linking ​

Users can link multiple social accounts to one Flowless account:

bash
POST /auth/social/link
Headers: X-Session-ID: ses_xyz123
Body: {
  "provider": "google",
  "access_token": "google_access_token"
}
bash
DELETE /auth/social/unlink/google
Headers: X-Session-ID: ses_xyz123

Security Considerations ​

State Parameter ​

Flowless automatically includes a state parameter to prevent CSRF attacks.

Scope Limitations ​

Only request necessary scopes:

  • ✅ email, profile - Essential
  • ❌ contacts, calendar - Unnecessary

Token Storage ​

  • Social access tokens are stored securely
  • Refresh tokens are encrypted
  • Tokens are never exposed to frontend

Troubleshooting ​

"Redirect URI mismatch" ​

  • Verify redirect URI in provider console matches exactly:
    https://your-instance.pubflow.com/auth/social/{provider}/callback

"Invalid client ID" ​

  • Double-check Client ID and Client Secret
  • Ensure no extra spaces
  • Regenerate credentials if needed

"App not verified" ​

  • Some providers require app verification for production
  • Submit app for review in provider console

Next Steps ​