Skip to content

Commit 7cc622a

Browse files
GauriGupta21GauriGupta21
authored
Update the project documentation (#120)
2 parents e94989d + bca0033 commit 7cc622a

File tree

5 files changed

+1431
-372
lines changed

5 files changed

+1431
-372
lines changed

‎docs/CHECK_OAUTH_CONSUMER.md‎

Lines changed: 193 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,214 @@
11
# Check Your OAuth Consumer Settings
22

3-
## Error: "oauth_callback must be set to 'oob'"
3+
Troubleshooting guide for the "oauth_callback must be set to 'oob'" error.
44

5-
This error means one of two things:
5+
## Understanding the Error
66

7-
### Possibility 1: Consumer Registered with "oob"
7+
**Error Message:** "oauth_callback must be set to 'oob'"
88

9-
Your OAuth consumer might have been registered with **"oob"** (out-of-band) instead of a callback URL.
9+
This error occurs when there's a mismatch between your OAuth consumer registration and the callback configuration in your application.
1010

11-
**Check your consumer:**
12-
1. Go to: https://meta.wikimedia.org/wiki/Special:OAuthConsumerRegistration
13-
2. Find your consumer with key: `ff02bad2706bef15385eec1471ee03ea`
14-
3. Click "Update" or "Manage"
15-
4. Check the **"OAuth 'callback' URL"** field:
16-
- If it says **"oob"** → That's the problem!
17-
- If it says **"http://localhost:5000/api/user/oauth/callback"** → That's correct
1811

19-
**If it's set to "oob":**
20-
- You have two options:
21-
1. **Update the consumer** (if possible) to use: `http://localhost:5000/api/user/oauth/callback`
22-
2. **OR** set `OAUTH_USE_OOB=True` in your `.env` file
12+
## Possibility 1: Consumer Registered with "oob"
2313

24-
### Possibility 2: Callback URL Mismatch
14+
Your OAuth consumer may have been registered with **"oob"** (out-of-band) authentication instead of a specific callback URL.
2515

26-
The callback URL being sent doesn't match what's registered.
16+
### Check Your Consumer Registration
2717

28-
**What to check:**
29-
1. Your consumer should be registered with: `http://localhost:5000/api/user/oauth/callback`
30-
2. The code should be sending: `http://localhost:5000/api/user/oauth/callback`
31-
3. They must match EXACTLY (including http vs https, localhost vs 127.0.0.1)
18+
1. **Navigate to OAuth Consumer Management:**
19+
- Visit: https://meta.wikimedia.org/wiki/Special:OAuthConsumerRegistration
3220

33-
**To debug:**
34-
1. Check Flask console logs when you click "Login with Wikimedia"
35-
2. Look for: `Using OAuth callback URL: ...`
36-
3. Verify it matches your registered callback URL exactly
21+
2. **Find your consumer:**
22+
- Look for the consumer with key: `ff02bad2706bef15385eec1471ee03ea`
23+
- Click **"Update"** or **"Manage"** to view details
3724

38-
## Quick Fix
25+
3. **Check the callback URL field:**
26+
27+
| Callback URL Value | Status | Issue |
28+
|-------------------------------------------------|----------|--------------------------------|
29+
| `oob` | Problem | Consumer registered for out-of-band authentication |
30+
| `http://localhost:5000/api/user/oauth/callback` | Correct | Consumer properly configured for callback |
31+
| Empty or missing | Problem | No callback URL specified |
3932

40-
If your consumer is registered with "oob", update your `.env`:
33+
### Solution Options
4134

35+
#### Option 1: Update the Consumer (If Possible)
36+
37+
Some OAuth consumers can be updated after registration:
38+
39+
1. Click **"Update"** on your consumer
40+
2. Change **"OAuth 'callback' URL"** to: `http://localhost:5000/api/user/oauth/callback`
41+
3. Save changes
42+
4. Restart your Flask server
43+
44+
**Note:** Not all consumer settings can be modified after approval. If the callback URL field is read-only, use Option 2.
45+
46+
#### Option 2: Use Out-of-Band Authentication
47+
48+
If you cannot update the consumer, configure your application to use out-of-band authentication:
49+
50+
**File: `backend/.env`**
51+
```env
52+
OAUTH_USE_OOB=True
53+
```
54+
55+
**Restart Flask:**
56+
```bash
57+
cd backend
58+
python app.py
59+
```
60+
61+
**How it works:**
62+
1. Click "Login with Wikimedia"
63+
2. You'll be redirected to Wikimedia and receive a verification code
64+
3. Manually enter the verification code in your application
65+
4. Authentication completes
66+
67+
**Limitation:** This is less user-friendly than automatic callback authentication.
68+
69+
## Possibility 2: Callback URL Mismatch
70+
71+
The callback URL your application is sending doesn't match the registered callback URL.
72+
73+
### What Must Match Exactly
74+
75+
The following must be **identical** between your OAuth consumer registration and your application:
76+
77+
| Component | Registered Value | Application Value | Must Match |
78+
|-----------|----------------------------|----------------------------|------------|
79+
| Protocol | `http://` | `http://` | Yes |
80+
| Host | `localhost` | `localhost` | Yes |
81+
| Port | `5000` | `5000` | Yes |
82+
| Path | `/api/user/oauth/callback` | `/api/user/oauth/callback` | Yes |
83+
84+
### Common Mismatches
85+
86+
**Wrong Protocol:**
87+
- Registered: `http://localhost:5000/api/user/oauth/callback`
88+
- Sent: `https://localhost:5000/api/user/oauth/callback`
89+
90+
**Wrong Host:**
91+
- Registered: `http://localhost:5000/api/user/oauth/callback`
92+
- Sent: `http://127.0.0.1:5000/api/user/oauth/callback`
93+
94+
**Wrong Port:**
95+
- Registered: `http://localhost:5000/api/user/oauth/callback`
96+
- Sent: `http://localhost:8000/api/user/oauth/callback`
97+
98+
**Wrong Path:**
99+
- Registered: `http://localhost:5000/api/user/oauth/callback`
100+
- Sent: `http://localhost:5000/oauth/callback`
101+
102+
### How to Debug
103+
104+
1. **Check Flask console logs** when you click "Login with Wikimedia"
105+
106+
2. **Look for the callback URL being used:**
107+
```
108+
Using OAuth callback URL: http://localhost:5000/api/user/oauth/callback
109+
```
110+
111+
3. **Compare with your registered callback URL:**
112+
- Go to: https://meta.wikimedia.org/wiki/Special:OAuthConsumerRegistration
113+
- Find your consumer and check the callback URL
114+
- They must match **exactly**
115+
116+
4. **Check for common issues:**
117+
- Extra trailing slash: `/api/user/oauth/callback/`
118+
- Missing path prefix: `/oauth/callback`
119+
- Wrong protocol: `https://` instead of `http://`
120+
121+
---
122+
123+
## Quick Fix: Enable Out-of-Band
124+
125+
If you need OAuth working immediately and can't update your consumer:
126+
127+
**File: `backend/.env`**
42128
```env
43129
OAUTH_USE_OOB=True
44130
```
45131

46-
Then restart Flask and try again. You'll need to manually enter a verification code.
132+
**Restart Flask:**
133+
```bash
134+
cd backend
135+
python app.py
136+
```
137+
138+
**Trade-off:**
139+
- Works immediately without consumer changes
140+
- Requires manual verification code entry (less user-friendly)
141+
142+
## Better Solution: Create New Consumer
143+
144+
For the best user experience, create a new OAuth consumer with the correct callback URL:
145+
146+
### Step 1: Register New Consumer
147+
148+
1. Visit: https://meta.wikimedia.org/wiki/Special:OAuthConsumerRegistration
149+
2. Click **"Propose an OAuth 1.0a consumer"**
150+
3. Fill out the form:
151+
- **Application name:** WikiContest Local Development
152+
- **OAuth callback URL:** `http://localhost:5000/api/user/oauth/callback`
153+
- **Owner-only:** No
154+
4. Submit and copy the credentials
155+
156+
### Step 2: Update Configuration
157+
158+
**File: `backend/.env`**
159+
```env
160+
# New consumer credentials
161+
CONSUMER_KEY=your-new-consumer-key
162+
CONSUMER_SECRET=your-new-consumer-secret
163+
164+
# Use callback (not out-of-band)
165+
OAUTH_USE_OOB=False
166+
```
167+
168+
### Step 3: Restart and Test
169+
```bash
170+
cd backend
171+
python app.py
172+
```
173+
174+
Test the OAuth flow - it should work smoothly without manual verification codes.
175+
176+
177+
## Verification Checklist
178+
179+
After applying your fix, verify:
180+
181+
- [ ] OAuth consumer found at https://meta.wikimedia.org/wiki/Special:OAuthConsumerRegistration
182+
- [ ] Callback URL is either `oob` or `http://localhost:5000/api/user/oauth/callback`
183+
- [ ] `.env` file has correct `CONSUMER_KEY` and `CONSUMER_SECRET`
184+
- [ ] `.env` file has `OAUTH_USE_OOB` set correctly:
185+
- `True` if consumer uses "oob"
186+
- `False` if consumer uses callback URL
187+
- [ ] Flask server restarted after configuration changes
188+
- [ ] OAuth login redirects properly
189+
- [ ] Authentication completes successfully
190+
191+
192+
## Summary
193+
194+
**If callback URL is "oob":**
195+
- Set `OAUTH_USE_OOB=True` in `.env` (quick fix)
196+
- OR create new consumer with proper callback URL (better solution)
197+
198+
**If callback URL is set but mismatched:**
199+
- Verify exact match between registered and sent URLs
200+
- Check protocol, host, port, and path
201+
- Update consumer or application configuration to match
202+
203+
**Recommended approach:**
204+
- Create a new OAuth consumer specifically for local development
205+
- Use callback URL: `http://localhost:5000/api/user/oauth/callback`
206+
- Set `OAUTH_USE_OOB=False` in `.env`
207+
- Keep a separate consumer for production (Toolforge)
47208

48-
## Better Solution
49209

50-
Create a NEW consumer with the correct callback URL:
51-
1. Go to: https://meta.wikimedia.org/wiki/Special:OAuthConsumerRegistration
52-
2. Register NEW consumer with callback: `http://localhost:5000/api/user/oauth/callback`
53-
3. Update `.env` with new credentials
54-
4. Keep `OAUTH_USE_OOB=False`
210+
## Related Documentation
55211

212+
- **Create Local OAuth Consumer - Step by Step** - Full guide to creating a new consumer
213+
- **OAuth Callback URL for Local Development** - Detailed callback URL reference
214+
- **OAuth 1.0a Local Development Setup Guide** - Complete OAuth setup instructions

0 commit comments

Comments
 (0)