;
}
```
## Callback URL Configuration
**Development:**
```
http://localhost:7654/api/auth/{provider}/callback
```
**Production:**
```
https://api.yourapp.com/api/auth/{provider}/callback
```
Update redirect URIs in provider dashboard when deploying.
## Cookie Settings for OAuth
Configure cookie behavior for OAuth flow:
```typescript
{
auth: {
cookie: {
secure: process.env.NODE_ENV === "production", // HTTPS only in prod
httpOnly: true,
sameSite: "lax", // Required for OAuth redirects
pathSuccess: "/dashboard", // Redirect after login
pathLoggedOut: "/login", // Redirect after logout
},
},
}
```
## Common Pitfalls
### Callback URL Mismatch
**Problem:** `redirect_uri_mismatch` error from provider
**Fix:** Ensure callback URL exactly matches provider dashboard:
```
# Provider dashboard (Google/GitHub)
http://localhost:7654/api/auth/google/callback
# Must match Bknd host configuration
host: "http://localhost:7654"
```
### Missing Environment Variables
**Problem:** OAuth login fails silently
**Fix:** Verify all required env vars are set:
```bash
# Required for Google OAuth
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
# Required for GitHub OAuth
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
# Always required
JWT_SECRET=...
```
### CORS Issues (SPA)
**Problem:** CORS error when calling OAuth endpoints
**Fix:** Configure CORS on backend:
```typescript
{
server: {
cors: {
origin: ["http://localhost:3000"], // Your frontend URL
credentials: true,
},
},
}
```
### Strategy Conflict
**Problem:** "User signed up with different strategy"
**Cause:** User has existing account with different auth method
**Solution:** Users can only have ONE strategy. Guide them to use their original login method or implement account linking (requires custom code).
### OAuth Cookie Not Set
**Problem:** Cookie not received after OAuth callback
**Fix:** Ensure secure cookie settings:
```typescript
{
auth: {
cookie: {
secure: false, // Set false for localhost (no HTTPS)
sameSite: "lax", // Required for OAuth redirects
},
},
}
```
### Invalid Scopes
**Problem:** Provider rejects scope request
**Fix:** Use only scopes from `scopes_supported`:
```typescript
// Google OIDC defaults
scopes_supported: ["openid", "email", "profile"]
// GitHub OAuth2 defaults
scopes_supported: ["read:user", "user:email"]
```
## Verification
Test OAuth setup:
**1. Check available strategies:**
```bash
curl http://localhost:7654/api/auth/strategies
```
Response should include your OAuth providers:
```json
{
"strategies": ["password", "google", "github"],
"basepath": "/api/auth"
}
```
**2. Test OAuth URL generation:**
```bash
curl http://localhost:7654/api/auth/google/login
```
Response:
```json
{
"url": "https://accounts.google.com/o/oauth2/v2/auth?...",
"challenge": "...",
"action": "login"
}
```
**3. Complete full OAuth flow:**
- Visit the OAuth URL in browser
- Complete provider login
- Verify redirect to `pathSuccess`
- Check `api/auth/me` returns user
## DOs and DON'Ts
**DO:**
- Store client secrets in environment variables
- Use HTTPS in production
- Set `sameSite: "lax"` for cookie (required for OAuth redirects)
- Match callback URLs exactly in provider dashboard
- Test OAuth flow in incognito (avoid cached sessions)
- Set appropriate JWT expiration
**DON'T:**
- Hardcode client secrets in code
- Use `secure: true` cookie on localhost (no HTTPS)
- Mix up client_id and client_secret
- Forget to update callback URLs for production
- Expect users to have multiple strategies (one per user)
- Skip the challenge verification in token flow
## Related Skills
- **bknd-setup-auth** - Initialize authentication system
- **bknd-login-flow** - Login/logout functionality
- **bknd-registration** - User registration setup
- **bknd-session-handling** - Manage user sessions
- **bknd-create-role** - Define user roles for OAuth users