Pixelflare

Appearance

OAuth Provider Setup ​

This page will walk you through how to get the required keys and config for setting up OAuth providers, which can then be used either with Cloudflare ZeroTrust, Auth.js, or your own custom authentication system on Pixelflare.

When using Auth.js, the callback URL will be:

https://your-domain.com/auth/callback/{provider}

When using Cloudflare ZeroTrust, the callback URL will be:

https://[team-id].cloudflareaccess.com/cdn-cgi/access/callback

GitHub ​

1. Create GitHub OAuth App ​

  1. Go to GitHub Developer Settings
  2. Click "Register a new application"
  3. Fill in the application details:
    • Application name: Your application name (e.g., "Pixelflare CDN")
    • Homepage URL: Your application's homepage (e.g., https://example.com)
    • Application description: Optional description
    • Authorization callback URL: https://your-domain.com/auth/callback/github
  4. Click "Register application"

2. Get Client ID and Secret ​

  1. After creating the app, you'll see your Client ID on the app details page
  2. Click "Generate a new client secret"
  3. Copy the secret immediately (you won't be able to see it again)

3. Configure Environment Variables ​

Add to your .env file:

bash
GITHUB_OAUTH_CLIENT_ID='Iv1.abc123def456...'
GITHUB_OAUTH_CLIENT_SECRET='your_github_secret_here'

Google OAuth Setup ​

1. Create Google Cloud Project ​

  1. Go to Google Cloud Console
  2. Create a new project or select an existing one
  3. Enable the Google Identity API (or Google+ API)

2. Configure OAuth Consent Screen ​

  1. Go to APIs & Services → OAuth consent screen
  2. Choose user type (external for public, or internal for Google Workspace)
  3. Fill in the required fields
  4. Add scopes: openid, email, profile
  5. Save and continue

3. Create OAuth 2.0 Credentials ​

  1. Go to APIs & Services → Credentials
  2. Click "Create Credentials" → "OAuth client ID"
  3. Choose "Web application" as the application type
  4. Fill in the details:
    • Name: Your credential name (e.g., "Pixelflare Production")
    • Authorized JavaScript origins: Add your domain (e.g., https://example.com)
    • Authorized redirect URIs: Add https://your-domain.com/auth/callback/google
  5. Click "Create"

4. Get Client ID and Secret ​

  1. After creation, a dialog will show your Client ID and Client Secret
  2. Copy both values
  3. You can also view these later from the Credentials page

5. Configure Environment Variables ​

Add to your .env file:

bash
GOOGLE_OAUTH_CLIENT_ID='123456789-abcdefg.apps.googleusercontent.com'
GOOGLE_OAUTH_CLIENT_SECRET='GOCSPX-abc123def456...'

Microsoft ​

1. Register Application in Azure ​

  1. Go to Azure Portal - App Registrations
  2. Click New registration"
  3. Fill in the application details:
    • Name: Your application name (e.g., "Pixelflare CDN")
    • Supported account types: Choose one:
      • Single tenant: Only your organization
      • Multitenant: Any Azure AD directory
      • Multitenant + personal: Any Azure AD + personal Microsoft accounts (recommended)
    • Redirect URI:
      • Platform: Web
      • URI: https://your-domain.com/auth/callback/microsoft
  4. Click "Register"

2. Get Application (Client) ID ​

  1. After registration, you'll see the Overview page
  2. Copy the Application (client) ID (this is your Client ID)
  3. Note: The Directory (tenant) ID is not needed (Auth.js uses the common endpoint)

3. Create Client Secret ​

  1. In your app's page, go to Certificates & secrets
  2. Click "New client secret"
  3. Add a description (e.g., "Production secret")
  4. Choose an expiration period (6 months, 12 months, 24 months, or custom)
  5. Click "Add"
  6. Copy the Value immediately (you won't be able to see it again)

Important

Don't copy the "Secret ID" - you need the "Value" column. You'll need to rotate this secret before it expires.

4. Configure API Permissions (Optional) ​

The default permissions should be sufficient, but you can verify:

  1. Go to API permissions
  2. Ensure these Microsoft Graph permissions are present:
    • openid
    • email
    • profile
  3. These are typically added automatically

5. Configure Environment Variables ​

Add to your .env file:

bash
MICROSOFT_OAUTH_CLIENT_ID='12345678-1234-1234-1234-123456789012'
MICROSOFT_OAUTH_CLIENT_SECRET='your_microsoft_secret_here'

Troubleshooting ​

Common Issues ​

"No OAuth providers configured" error
  • Ensure at least one provider has both Client ID and Client Secret configured
  • Check that environment variables are properly loaded
  • Verify the variable names match exactly (case-sensitive)
Redirect URI mismatch
  • Verify the callback URL in your OAuth provider matches exactly: https://your-domain.com/auth/callback/{provider}
  • Ensure there are no trailing slashes
  • Check that your domain is correct (including subdomain)
  • Make sure you're using HTTPS in production
Google: "Access blocked: Authorization Error"
  • Ensure your OAuth consent screen is configured
  • Check that the required scopes are added (openid, email, profile)
  • Verify the app is not in "Testing" mode with restricted users (or add test users)
  • If in testing mode, only approved test users can sign in
Microsoft: "AADSTS50011: The redirect URI does not match"
  • Go to Authentication in your Azure app registration
  • Verify the redirect URI is exactly: https://your-domain.com/auth/callback/microsoft
  • Ensure the platform type is set to Web
  • Check for any typos or extra characters
Provider button doesn't appear on login page
  • Check that both Client ID and Client Secret are configured
  • Verify environment variables are loaded correctly (restart dev server)
  • Check browser console for any JavaScript errors
  • Ensure AUTH_MODE=authjs is set

Security Best Practices ​

Never commit secrets to version control

  • Use .env for local development
  • Use Terraform variables for production
  • Keep .env in your .gitignore
  • Never share secrets in screenshots or documentation

Rotate secrets regularly

  • Set calendar reminders for secret expiration (especially Microsoft)
  • Update secrets in both your OAuth provider console and deployment config
  • Use password managers to track secret expiration dates

Use appropriate scopes

  • Only request the minimum scopes needed (openid, email, profile)
  • Avoid requesting unnecessary permissions
  • Review scopes annually as requirements change

Monitor OAuth usage

  • Check your OAuth provider dashboards for unusual activity
  • Review failed authentication attempts
  • Set up alerts for suspicious patterns

Multiple Providers ​

You can configure multiple OAuth providers simultaneously. Users will see buttons for all configured providers on the login page.

The system will:

  • Show buttons only for providers with valid credentials
  • Allow users to choose their preferred authentication method
  • Link user accounts by email address across providers

Account Linking

If a user signs in with GitHub using alice@example.com, then later signs in with Google using the same email, the system will recognize them as the same user and link the accounts automatically.