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 enterprise identity providers (Okta, Auth0, Keycloak), see Custom OIDC.

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: Configure Environment

Add to your .env file:

GITHUB_CLIENT_ID="your-client-id"
GITHUB_CLIENT_SECRET="your-client-secret"

Callback URL Format

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

For local development:

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

Scopes Requested

• read:user - Read user profile information
• user:email - Access user email addresses

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: Configure Environment

GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="your-client-secret"

Callback URL Format

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

Scopes Requested

• openid - OpenID Connect authentication
• email - User email address
• profile - Basic profile information

Enable OAuth in Quackback

OAuth providers are configured in the admin dashboard, not through environment variables. Credentials are stored encrypted in the database.

Admin Settings

[Dashboard]

1. Navigate to Admin → Settings → Portal Authentication (or Security for team auth)
2. Click on the provider you want to configure
3. Enter the Client ID, Client Secret, and any provider-specific fields
4. Toggle the provider on

Providers only appear on the sign-in page when they're configured and enabled.

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

• Never commit secrets to version control
• Use environment variables or secret management
• Rotate secrets periodically
• Use separate OAuth apps for development/production

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)
• Email OTP - Magic code authentication
• Authentication Overview - All auth options