Set up OAuth providers

One-click sign-in. Let users authenticate with social accounts instead of managing another set of credentials. Works for both portal users (customers) and team members (your employees).

Overview

OAuth lets users sign in with accounts they already have. No new passwords, no verification emails. Just a quick popup to authorize access and they're in.

Supported Providers

All providers work for both portal users and team members. For team-wide single sign-on with verified domains and enforcement, see Single sign-on. To offer a single custom OIDC button on the portal sign-in form, enable Custom OIDC on the Portal tab of the Authentication page (requires the Custom OIDC feature on your plan).

How It Works

1. User clicks "Continue with [Provider]"
2. A popup window opens to the provider's login page
3. User authenticates and grants permission
4. Provider redirects back to Quackback with authorization code
5. Quackback exchanges the code for user information
6. User session is created

GitHub Setup

Step 1: Create OAuth Application

[GitHub]

1. Go to GitHub Developer Settings
2. Click OAuth Apps > New OAuth App
3. Fill in the application details:

4. Click Register application
5. Note the Client ID
6. Click Generate a new client secret and save it securely

Step 2: Add credentials in Quackback

1. Go to Admin → Settings → Security → Authentication in Quackback.
2. Switch to the Portal or Team tab.
3. Find GitHub in the Social sign-in grid and click Configure.
4. Paste the Client ID and Client Secret. Save.
5. Toggle GitHub on for the surface(s) you want.

Credentials are stored encrypted in the database, not in environment variables.

Callback URL format

https://YOUR_DOMAIN/api/auth/callback/github

For local development:

http://localhost:3000/api/auth/callback/github

Google Setup

Step 1: Create OAuth Credentials

[Google Cloud Console]

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Navigate to APIs & Services > Credentials
4. Click Create Credentials > OAuth client ID
5. If prompted, configure the OAuth consent screen first:
   • User Type: External (or Internal for Workspace)
   • App name: Quackback
   • User support email: Your email
   • Authorized domains: yourcompany.com

Step 2: Configure OAuth Client

[Google Cloud Console]

1. Application type: Web application
2. Name: Quackback
3. Authorized JavaScript origins:

   https://feedback.yourcompany.com
   

4. Authorized redirect URIs:

   https://feedback.yourcompany.com/api/auth/callback/google
   

5. Click Create
6. Note the Client ID and Client Secret

Step 3: Add credentials in Quackback

1. Go to Admin → Settings → Security → Authentication in Quackback.
2. Switch to the Portal or Team tab.
3. Find Google in the Social sign-in grid and click Configure.
4. Paste the Client ID and Client Secret. Save.
5. Toggle Google on for the surface(s) you want.

Callback URL format

https://YOUR_DOMAIN/api/auth/callback/google

Enable OAuth in Quackback

Every provider is configured once and can be enabled per surface (Portal, Team). Credentials are stored encrypted in the platform credentials table.

1. Go to Admin → Settings → Security → Authentication.
2. Switch to the Portal or Team tab.
3. Click Configure on the provider tile, paste Client ID and Client Secret, save.
4. Toggle the provider on for that surface. The same credentials power both surfaces; configure once, enable independently.

Providers only appear on the sign-in page when credentials are saved and the toggle is on.

Other Providers

All providers follow the same pattern:

1. Create an OAuth application in the provider's developer console
2. Set the callback URL to https://YOUR_DOMAIN/api/auth/callback/PROVIDER_ID
3. Enter the Client ID and Client Secret in Quackback's admin settings

Common Issues

"OAuth callback URL mismatch"

The callback URL in your OAuth app configuration must match exactly:

Check these common issues:

• Protocol mismatch (http vs https)
• Trailing slash differences
• Port number missing or incorrect
• Domain/subdomain mismatch

Example correct callback URLs:

# Production
https://feedback.yourcompany.com/api/auth/callback/github

# Local development
http://localhost:3000/api/auth/callback/github

"Invalid client_id or client_secret"

1. Verify the credentials are copied correctly (no extra spaces)
2. Ensure the OAuth app is not deleted or disabled
3. For Google, check if the OAuth consent screen is in testing mode

"Popup blocked"

Quackback uses popup windows for OAuth. If blocked:

1. Click the browser's popup blocked notification
2. Allow popups for your Quackback domain
3. Try the sign-in again

"Access denied" or "Application not authorized"

GitHub:

• Verify the OAuth app is not suspended
• Check organization access policies

Google:

• If consent screen is in testing mode, add test users
• Submit app for verification for production use
• Check if domain restrictions apply

"Unable to get email from provider"

Some providers don't return email by default:

GitHub:

• User must have a public email or grant email permission
• Quackback fetches from /user/emails as fallback

Google:

• Email scope is always requested
• User must have a Google account with email

CORS Errors

If you see CORS errors in the browser console:

1. Verify BASE_URL matches your actual domain
2. Check BASE_URL is correctly set
3. Ensure your reverse proxy passes the correct headers

Security Best Practices

Protect client secrets

• Quackback stores OAuth credentials encrypted in the platform credentials table; you don't need to manage them in environment variables.
• Rotate client secrets periodically and update them in Configure for each provider.
• Use separate OAuth apps for development and production so leaking one set doesn't expose the other.

Verify Callback URLs

• Use HTTPS in production
• Don't use wildcard callback URLs
• Restrict to your exact domain

Review OAuth Permissions

Each provider requests minimal scopes:

• Basic profile information
• Email address (for account identification)

No write access or sensitive permissions are requested.

Monitor OAuth Activity

• Review sign-in logs regularly
• Set up alerts for unusual patterns
• Disable unused OAuth providers

Test OAuth locally

[Browser]

Local Development Setup

1. Use localhost:3000 in your callback URL
2. Most providers allow http://localhost for development
3. For Google, add http://localhost:3000 to authorized origins

Test checklist

• OAuth app created with correct callback URL
• Credentials entered in admin settings
• Browser allows popups from your domain
• Test user exists (for testing-mode apps)

Next steps

• Custom OIDC - Enterprise identity providers (Okta, Auth0, Keycloak)
• Magic link - Passwordless email sign-in
• Authentication Overview - All auth options