# Authentication Setup

Flyer Crawler supports OAuth authentication via Google and GitHub. This guide walks through configuring both providers.

---

## Google OAuth

### Step 1: Create OAuth Credentials

1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project (or select an existing one)
3. Navigate to **APIs & Services > Credentials**
4. Click **Create Credentials > OAuth client ID**
5. Select **Web application** as the application type

### Step 2: Configure Authorized Redirect URIs

Add the callback URL where Google will redirect users after authentication:

| Environment | Redirect URI                                       |
| ----------- | -------------------------------------------------- |
| Development | `http://localhost:3001/api/auth/google/callback`   |
| Production  | `https://your-domain.com/api/auth/google/callback` |

### Step 3: Save Credentials

After clicking **Create**, you'll receive:

- **Client ID**
- **Client Secret**

Store these securely as environment variables:

- `GOOGLE_CLIENT_ID`
- `GOOGLE_CLIENT_SECRET`

---

## GitHub OAuth

### Step 1: Create OAuth App

1. Go to your [GitHub Developer Settings](https://github.com/settings/developers)
2. Navigate to **OAuth Apps**
3. Click **New OAuth App**

### Step 2: Fill in Application Details

| Field                      | Value                                                |
| -------------------------- | ---------------------------------------------------- |
| Application name           | Flyer Crawler (or your preferred name)               |
| Homepage URL               | `http://localhost:5173` (dev) or your production URL |
| Authorization callback URL | `http://localhost:3001/api/auth/github/callback`     |

### Step 3: Save GitHub Credentials

After clicking **Register application**, you'll receive:

- **Client ID**
- **Client Secret**

Store these securely as environment variables:

- `GITHUB_CLIENT_ID`
- `GITHUB_CLIENT_SECRET`

---

## Environment Variables Summary

| Variable               | Description                              |
| ---------------------- | ---------------------------------------- |
| `GOOGLE_CLIENT_ID`     | Google OAuth client ID                   |
| `GOOGLE_CLIENT_SECRET` | Google OAuth client secret               |
| `GITHUB_CLIENT_ID`     | GitHub OAuth client ID                   |
| `GITHUB_CLIENT_SECRET` | GitHub OAuth client secret               |
| `JWT_SECRET`           | Secret for signing authentication tokens |

---

## Production Considerations

When deploying to production:

1. **Update redirect URIs** in both Google Cloud Console and GitHub OAuth settings to use your production domain
2. **Use HTTPS** for all callback URLs in production
3. **Store secrets securely** using your CI/CD platform's secrets management (e.g., Gitea repository secrets)

---

## Troubleshooting

### "redirect_uri_mismatch" Error

The callback URL in your OAuth provider settings doesn't match what the application is sending. Verify:

- The URL is exactly correct (no trailing slashes, correct port)
- You're using the right environment (dev vs production URLs)

### "invalid_client" Error

The Client ID or Client Secret is incorrect. Double-check your environment variables.

---

## Related Documentation

- [Installation Guide](INSTALL.md) - Local development setup
- [Deployment Guide](DEPLOYMENT.md) - Production deployment
