phil/Gondulf
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9dfa77633a9e35f441c308150ad2dbc841178ad8
Gondulf/docs/guides/real-client-testing-cheatsheet.md

399 lines
10 KiB
Markdown
Raw Blame History

# Real Client Testing Cheat Sheet
Quick guide to test Gondulf with real IndieAuth clients. Target: working auth in 15-30 minutes.
---
## 1. Quick Start Setup
### Generate Secret Key
```bash
python -c "import secrets; print(secrets.token_urlsafe(32))"
```
### Create .env File
```bash
cd /path/to/gondulf
cp .env.example .env
```
Edit `.env` with minimum required settings:
```bash
# Required - paste your generated key
GONDULF_SECRET_KEY=your-generated-secret-key-here
# Your auth server URL (use your actual domain)
GONDULF_BASE_URL=https://auth.thesatelliteoflove.com
# Database (container path)
GONDULF_DATABASE_URL=sqlite:////data/gondulf.db
# SMTP - use your provider (example: Gmail)
GONDULF_SMTP_HOST=smtp.gmail.com
GONDULF_SMTP_PORT=587
GONDULF_SMTP_USERNAME=your-email@gmail.com
GONDULF_SMTP_PASSWORD=your-app-specific-password
GONDULF_SMTP_FROM=your-email@gmail.com
GONDULF_SMTP_USE_TLS=true
# Production settings
GONDULF_HTTPS_REDIRECT=true
GONDULF_TRUST_PROXY=true
GONDULF_SECURE_COOKIES=true
GONDULF_DEBUG=false
```
### Run with Podman/Docker
```bash
# Build
podman build -t gondulf:latest -f Containerfile .
# Run (creates volume for persistence)
podman run -d \
--name gondulf \
-p 8000:8000 \
-v gondulf_data:/data \
--env-file .env \
gondulf:latest
# Or with docker-compose/podman-compose
podman-compose up -d
```
### Verify Server Running
```bash
curl https://auth.thesatelliteoflove.com/health
# Expected: {"status":"healthy","database":"connected"}
curl https://auth.thesatelliteoflove.com/.well-known/oauth-authorization-server
# Expected: JSON with authorization_endpoint, token_endpoint, etc.
```
---
## 2. Domain Setup
### DNS TXT Record
Add this TXT record to your domain DNS:
| Type | Host | Value |
|------|------|-------|
| TXT | @ (or thesatelliteoflove.com) | `gondulf-verify-domain` |
Verify with:
```bash
dig TXT thesatelliteoflove.com +short
# Expected: "gondulf-verify-domain"
```
**Note**: DNS propagation can take up to 48 hours, but usually completes within minutes.
### Homepage rel="me" Link
Add a `rel="me"` link to your homepage pointing to your email:
```html
<!DOCTYPE html>
<html>
<head>
<title>Your Homepage</title>
<!-- rel="me" link in head -->
<link rel="me" href="mailto:you@thesatelliteoflove.com">
</head>
<body>
<h1>thesatelliteoflove.com</h1>
<!-- Or as a visible link in body -->
<a rel="me" href="mailto:you@thesatelliteoflove.com">Email me</a>
</body>
</html>
```
**Important**: The email domain should match your website domain OR be an email you control (Gondulf sends a verification code to this address).
### Complete Homepage Example
```html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>thesatelliteoflove.com</title>
<link rel="me" href="mailto:phil@thesatelliteoflove.com">
<link rel="authorization_endpoint" href="https://auth.thesatelliteoflove.com/authorize">
<link rel="token_endpoint" href="https://auth.thesatelliteoflove.com/token">
</head>
<body>
<div class="h-card">
<h1 class="p-name">Phil</h1>
<p><a class="u-url" rel="me" href="https://thesatelliteoflove.com/">thesatelliteoflove.com</a></p>
<p><a rel="me" href="mailto:phil@thesatelliteoflove.com">phil@thesatelliteoflove.com</a></p>
</div>
</body>
</html>
```
---
## 3. Testing with Real Clients
**Important**: These are IndieAuth CLIENTS that will authenticate against YOUR Gondulf server. Your domain needs to point its authorization and token endpoints to Gondulf, not to IndieLogin.
**Note about IndieLogin.com**: IndieLogin.com is NOT a client - it's an IndieAuth provider/server like Gondulf. Gondulf is designed to REPLACE IndieLogin as your authentication provider. If your domain points to IndieLogin's endpoints, you're using IndieLogin for auth, not Gondulf.
### Option A: IndieWeb Wiki (Easiest Test)
The IndieWeb wiki uses IndieAuth for login.
1. Go to: https://indieweb.org/
2. Click "Log in" (top right)
3. Enter your domain: `https://thesatelliteoflove.com/`
4. Click "Log In"
**Expected flow**:
- Wiki discovers your authorization endpoint (Gondulf)
- Redirects to your Gondulf server
- Gondulf verifies DNS TXT record
- Gondulf discovers your email from rel="me"
- Sends verification code to your email
- You enter the code
- Consent screen appears
- Approve authorization
- Redirected back to IndieWeb wiki as logged in
### Option B: Quill (Micropub Posting Client)
Quill is a web-based Micropub client for creating posts.
1. Go to: https://quill.p3k.io/
2. Enter your domain: `https://thesatelliteoflove.com/`
3. Click "Sign In"
**Note**: Quill will attempt to discover your Micropub endpoint after auth. For testing auth only, you can ignore Micropub errors after successful authentication.
### Option C: Monocle (Feed Reader)
Monocle is a web-based social feed reader.
1. Go to: https://monocle.p3k.io/
2. Enter your domain: `https://thesatelliteoflove.com/`
3. Sign in
**Note**: Monocle will look for a Microsub endpoint after auth. The authentication itself will still work without one.
### Option D: Teacup (Check-in App)
Teacup is for food/drink check-ins.
1. Go to: https://teacup.p3k.io/
2. Enter your domain to sign in
### Option E: Micropublish (Simple Posting)
Micropublish is a simple web interface for creating posts.
1. Go to: https://micropublish.net/
2. Enter your domain to authenticate
### Option F: Indigenous (Mobile Apps)
Indigenous has apps for iOS and Android that support IndieAuth.
- **iOS**: Search "Indigenous" in App Store
- **Android**: Search "Indigenous" in Play Store
- Configure with your domain: `https://thesatelliteoflove.com/`
### Option G: Omnibear (Browser Extension)
Omnibear is a browser extension for Firefox and Chrome.
1. Install from browser extension store
2. Configure with your domain
3. Use to sign in and post from any webpage
### Option H: Custom Test Client (curl)
Test the authorization endpoint directly:
```bash
# Generate PKCE verifier and challenge
CODE_VERIFIER=$(python -c "import secrets; print(secrets.token_urlsafe(32))")
CODE_CHALLENGE=$(echo -n "$CODE_VERIFIER" | openssl dgst -sha256 -binary | base64 | tr '+/' '-_' | tr -d '=')
echo "Verifier: $CODE_VERIFIER"
echo "Challenge: $CODE_CHALLENGE"
# Open this URL in browser:
echo "https://auth.thesatelliteoflove.com/authorize?\
client_id=https://example.com/&\
redirect_uri=https://example.com/callback&\
response_type=code&\
state=test123&\
code_challenge=$CODE_CHALLENGE&\
code_challenge_method=S256&\
me=https://thesatelliteoflove.com/"
```
---
## 4. Verification Checklist
### DNS Verification
```bash
# Check TXT record exists
dig TXT thesatelliteoflove.com +short
# Must return: "gondulf-verify-domain"
# Alternative: query specific DNS server
dig @8.8.8.8 TXT thesatelliteoflove.com +short
```
### Email Discovery Verification
```bash
# Check your homepage serves rel="me" email link
curl -s https://thesatelliteoflove.com/ | grep -i 'rel="me"'
# Must show: href="mailto:your@email.com"
# Or check with a parser
curl -s https://thesatelliteoflove.com/ | grep -oP 'rel="me"[^>]*href="mailto:[^"]+"'
```
### Server Metadata Verification
```bash
curl -s https://auth.thesatelliteoflove.com/.well-known/oauth-authorization-server | jq .
```
Expected output:
```json
{
"issuer": "https://auth.thesatelliteoflove.com",
"authorization_endpoint": "https://auth.thesatelliteoflove.com/authorize",
"token_endpoint": "https://auth.thesatelliteoflove.com/token",
"response_types_supported": ["code"],
"grant_types_supported": ["authorization_code"],
"code_challenge_methods_supported": [],
"token_endpoint_auth_methods_supported": ["none"],
"revocation_endpoint_auth_methods_supported": ["none"],
"scopes_supported": []
}
```
### Complete Flow Test
1. DNS check passes (TXT record found)
2. Email discovered (rel="me" link found)
3. Verification email received
4. Code entered successfully
5. Consent screen displayed
6. Authorization code returned
7. Token exchanged successfully
8. Client shows logged in as `https://thesatelliteoflove.com/`
---
## 5. Troubleshooting
### Check Server Logs
```bash
# View live logs
podman logs -f gondulf
# View last 100 lines
podman logs --tail 100 gondulf
```
### Enable Debug Mode (Development Only)
In `.env`:
```bash
GONDULF_DEBUG=true
GONDULF_LOG_LEVEL=DEBUG
GONDULF_HTTPS_REDIRECT=false
```
**Warning**: Never use DEBUG=true in production.
### Common Issues
| Problem | Solution |
|---------|----------|
| "dns_verification_failed" | Add TXT record: `gondulf-verify-domain`. Wait for DNS propagation (check with `dig`). |
| "email_discovery_failed" | Add `<link rel="me" href="mailto:you@domain.com">` to your homepage. |
| "email_send_failed" | Check SMTP settings. Test with: `podman logs gondulf | grep -i smtp` |
| "Invalid me URL" | Ensure `me` parameter uses HTTPS and is a valid URL |
| "client_id must use HTTPS" | Client applications must use HTTPS URLs |
| "redirect_uri does not match" | redirect_uri domain must match client_id domain |
| Health check fails | Check database volume permissions: `podman exec gondulf ls -la /data` |
| Container won't start | Check for missing env vars: `podman logs gondulf` |
### SMTP Testing
Test email delivery independently:
```bash
# Check SMTP connection (Python)
python -c "
import smtplib
with smtplib.SMTP('smtp.gmail.com', 587) as s:
s.starttls()
s.login('your-email@gmail.com', 'app-password')
print('SMTP connection successful')
"
```
### DNS Propagation Check
```bash
# Check multiple DNS servers
for ns in 8.8.8.8 1.1.1.1 9.9.9.9; do
echo "Checking $ns:"
dig @$ns TXT thesatelliteoflove.com +short
done
```
### Database Issues
```bash
# Check database exists and is writable
podman exec gondulf ls -la /data/
# Check database schema
podman exec gondulf sqlite3 /data/gondulf.db ".tables"
```
---
## Quick Reference
| Endpoint | URL |
|----------|-----|
| Health | `GET /health` |
| Metadata | `GET /.well-known/oauth-authorization-server` |
| Authorization | `GET /authorize` |
| Token | `POST /token` |
| Start Verification | `POST /api/verify/start` |
| Verify Code | `POST /api/verify/code` |
| Required DNS Record | Value |
|---------------------|-------|
| TXT @ | `gondulf-verify-domain` |
| Required HTML | Example |
|---------------|---------|
| rel="me" email | `<link rel="me" href="mailto:you@example.com">` |
| authorization_endpoint | `<link rel="authorization_endpoint" href="https://auth.example.com/authorize">` |
| token_endpoint | `<link rel="token_endpoint" href="https://auth.example.com/token">` |
Reference in New Issue View Git Blame Copy Permalink