427 lines
15 KiB
Markdown
427 lines
15 KiB
Markdown
# Rodauth-OAuth Decision Guide
|
|
|
|
## TL;DR - Make Your Choice Here
|
|
|
|
### Option A: Keep Your Rails Implementation
|
|
**Best if:** Authorization Code + PKCE is all you need, forever
|
|
- Keep your current 450 lines of OIDC controller code
|
|
- Maintain incrementally as needs change
|
|
- Stay 100% in Rails ecosystem
|
|
- Time investment: Ongoing (2-3 months to feature parity)
|
|
- Learning curve: None (already know Rails)
|
|
|
|
### Option B: Switch to Rodauth-OAuth
|
|
**Best if:** You need enterprise features, standards compliance, low maintenance
|
|
- Replace 450 lines with plugin config
|
|
- Get 34 optional features on demand
|
|
- OpenID Certified, production-hardened
|
|
- Time investment: 4-8 weeks (one-time)
|
|
- Learning curve: Medium (learn Roda/Rodauth)
|
|
|
|
### Option C: Hybrid (Recommended if Option B appeals you)
|
|
**Best if:** You want rodauth-oauth benefits without framework change
|
|
- Run Rodauth-OAuth as separate microservice
|
|
- Keep your Rails app unchanged
|
|
- Services talk via HTTP APIs
|
|
- Time investment: 2-3 weeks (independent services)
|
|
- Learning curve: Low (Roda is isolated)
|
|
|
|
---
|
|
|
|
## Decision Matrix
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Do you need features beyond Authorization Code + PKCE? │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ YES ─→ Go to Question 2 │
|
|
│ NO ─→ KEEP YOUR IMPLEMENTATION │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Can your team learn Roda (different from Rails)? │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ YES ─→ SWITCH TO RODAUTH-OAUTH │
|
|
│ NO ─→ Go to Question 3 │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Can you run separate services (microservices)? │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ YES ─→ USE HYBRID APPROACH │
|
|
│ NO ─→ KEEP YOUR IMPLEMENTATION │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Feature Roadmap Comparison
|
|
|
|
### Scenario 1: You Need Refresh Tokens (Common)
|
|
|
|
**Option A (Keep Custom):**
|
|
- Implement refresh token endpoints
|
|
- Add refresh_token columns to DB
|
|
- Token rotation logic
|
|
- Estimate: 1-2 weeks of work
|
|
- Ongoing: Maintain refresh token security
|
|
|
|
**Option B (Rodauth-OAuth):**
|
|
- Already built and tested
|
|
- Just enable: `:oauth_authorization_code_grant` (includes refresh)
|
|
- Token rotation: Configurable options
|
|
- Estimate: Already included
|
|
- Ongoing: Community maintains
|
|
|
|
**Option C (Hybrid):**
|
|
- Rodauth-OAuth handles it
|
|
- Your app unchanged
|
|
- Same as Option B for this feature
|
|
|
|
### Scenario 2: You Need Token Revocation
|
|
|
|
**Option A (Keep Custom):**
|
|
- Build `/oauth/revoke` endpoint
|
|
- Implement token blacklist or DB update
|
|
- Handle race conditions
|
|
- Estimate: 1-2 weeks
|
|
- Ongoing: Monitor revocation leaks
|
|
|
|
**Option B (Rodauth-OAuth):**
|
|
- Enable `:oauth_token_revocation` feature
|
|
- RFC 7009 compliant out of the box
|
|
- Estimate: Already included
|
|
- Ongoing: Community handles RFC updates
|
|
|
|
**Option C (Hybrid):**
|
|
- Same as Option B
|
|
|
|
### Scenario 3: You Need Client Credentials Grant
|
|
|
|
**Option A (Keep Custom):**
|
|
- New endpoint logic
|
|
- Client authentication (different from user auth)
|
|
- Token generation for apps without users
|
|
- Estimate: 2-3 weeks
|
|
- Ongoing: Test with external clients
|
|
|
|
**Option B (Rodauth-OAuth):**
|
|
- Enable `:oauth_client_credentials_grant` feature
|
|
- All edge cases handled
|
|
- Estimate: Already included
|
|
- Ongoing: Community maintains
|
|
|
|
**Option C (Hybrid):**
|
|
- Same as Option B
|
|
|
|
---
|
|
|
|
## Architecture Diagrams
|
|
|
|
### Current Setup (Your Implementation)
|
|
```
|
|
┌─────────────────────────────┐
|
|
│ Your Rails Application │
|
|
├─────────────────────────────┤
|
|
│ app/controllers/ │
|
|
│ oidc_controller.rb │ ← 450 lines of OAuth logic
|
|
│ │
|
|
│ app/models/ │
|
|
│ OidcAuthorizationCode │
|
|
│ OidcAccessToken │
|
|
│ OidcUserConsent │
|
|
│ │
|
|
│ app/services/ │
|
|
│ OidcJwtService │
|
|
├─────────────────────────────┤
|
|
│ Rails ActiveRecord │
|
|
├─────────────────────────────┤
|
|
│ PostgreSQL Database │
|
|
│ - oidc_authorization_codes
|
|
│ - oidc_access_tokens
|
|
│ - oidc_user_consents
|
|
│ - applications
|
|
└─────────────────────────────┘
|
|
```
|
|
|
|
### Option B: Full Migration
|
|
```
|
|
┌──────────────────────────────┐
|
|
│ Roda + Rodauth-OAuth App │
|
|
├──────────────────────────────┤
|
|
│ lib/rodauth_app.rb │ ← Config (not code!)
|
|
│ enable :oidc, │
|
|
│ enable :oauth_pkce, │
|
|
│ enable :oauth_token_... │
|
|
│ │
|
|
│ [Routes auto-mounted] │
|
|
│ /.well-known/config │
|
|
│ /oauth/authorize │
|
|
│ /oauth/token │
|
|
│ /oauth/userinfo │
|
|
│ /oauth/revoke │
|
|
│ /oauth/introspect │
|
|
├──────────────────────────────┤
|
|
│ Sequel ORM │
|
|
├──────────────────────────────┤
|
|
│ PostgreSQL Database │
|
|
│ - accounts (rodauth)
|
|
│ - oauth_applications
|
|
│ - oauth_grants (unified!)
|
|
│ - optional feature tables
|
|
└──────────────────────────────┘
|
|
```
|
|
|
|
### Option C: Microservices Architecture (Hybrid)
|
|
```
|
|
┌──────────────────────────┐ ┌──────────────────────────┐
|
|
│ Your Rails App │ │ Rodauth-OAuth Service │
|
|
├──────────────────────────┤ ├──────────────────────────┤
|
|
│ Normal Rails Controllers │ │ lib/rodauth_app.rb │
|
|
│ & Business Logic │ │ [OAuth Features] │
|
|
│ │ │ │
|
|
│ HTTP Calls to →──────────┼─────→ /.well-known/config │
|
|
│ OAuth Service OAuth │ │ /oauth/authorize │
|
|
│ HTTP API │ │ /oauth/token │
|
|
│ │ │ /oauth/userinfo │
|
|
│ Verify Tokens via →──────┼─────→ /oauth/introspect │
|
|
│ /oauth/introspect │ │ │
|
|
├──────────────────────────┤ ├──────────────────────────┤
|
|
│ Rails ActiveRecord │ │ Sequel ORM │
|
|
├──────────────────────────┤ ├──────────────────────────┤
|
|
│ PostgreSQL │ │ PostgreSQL │
|
|
│ [business tables] │ │ [oauth tables] │
|
|
└──────────────────────────┘ └──────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Effort Estimates
|
|
|
|
### Option A: Keep & Enhance Custom Implementation
|
|
```
|
|
Refresh Tokens: 1-2 weeks
|
|
Token Revocation: 1-2 weeks
|
|
Token Introspection: 1-2 weeks
|
|
Client Credentials: 2-3 weeks
|
|
Device Code: 3-4 weeks
|
|
JWT Access Tokens: 1-2 weeks
|
|
Session Management: 2-3 weeks
|
|
Front-Channel Logout: 1-2 weeks
|
|
Back-Channel Logout: 2-3 weeks
|
|
─────────────────────────────────
|
|
TOTAL FOR PARITY: 15-25 weeks
|
|
(4-6 months of work)
|
|
|
|
ONGOING MAINTENANCE: ~8-10 hours/month
|
|
(security updates, RFC changes, bug fixes)
|
|
```
|
|
|
|
### Option B: Migrate to Rodauth-OAuth
|
|
```
|
|
Learn Roda/Rodauth: 1-2 weeks
|
|
Migrate Database Schema: 1-2 weeks
|
|
Replace OIDC Code: 1-2 weeks
|
|
Test & Validation: 2-3 weeks
|
|
─────────────────────────────────
|
|
ONE-TIME EFFORT: 5-9 weeks
|
|
(1-2 months)
|
|
|
|
ONGOING MAINTENANCE: ~1-2 hours/month
|
|
(dependency updates, config tweaks)
|
|
```
|
|
|
|
### Option C: Hybrid Approach
|
|
```
|
|
Set up Rodauth service: 1-2 weeks
|
|
Configure integration: 1-2 weeks
|
|
Test both services: 1 week
|
|
─────────────────────────────────
|
|
ONE-TIME EFFORT: 3-5 weeks
|
|
(less than Option B)
|
|
|
|
ONGOING MAINTENANCE: ~2-3 hours/month
|
|
(maintain two services, but Roda handles OAuth)
|
|
```
|
|
|
|
---
|
|
|
|
## Real-World Questions to Ask Your Team
|
|
|
|
### Question 1: Feature Needs
|
|
- "Do we need refresh tokens?"
|
|
- "Will clients ask for token revocation?"
|
|
- "Do we support service-to-service auth (client credentials)?"
|
|
- "Will we ever need device code flow (IoT)?"
|
|
|
|
If YES to any: **Option B or C makes sense**
|
|
|
|
### Question 2: Maintenance Philosophy
|
|
- "Do we want to own the OAuth code?"
|
|
- "Can we afford to maintain OAuth compliance?"
|
|
- "Do we have experts in OAuth/OIDC?"
|
|
|
|
If NO to all: **Option B or C is better**
|
|
|
|
### Question 3: Framework Flexibility
|
|
- "Is Rails non-negotiable for this company?"
|
|
- "Can our team learn a new framework?"
|
|
- "Can we run microservices?"
|
|
|
|
If Rails is required: **Option C (hybrid)**
|
|
|
|
### Question 4: Time Constraints
|
|
- "Do we have 4-8 weeks for a migration?"
|
|
- "Can we maintain OAuth for years?"
|
|
- "What if specs change?"
|
|
|
|
If time-constrained: **Option B is fastest path to full features**
|
|
|
|
---
|
|
|
|
## Security Comparison
|
|
|
|
### Your Implementation
|
|
- ✓ PKCE support
|
|
- ✓ JWT signing
|
|
- ✓ HTTPS recommended
|
|
- ✗ Token hashing (stores tokens in plaintext)
|
|
- ✗ Token rotation
|
|
- ✗ DPoP (token binding)
|
|
- ✗ Automatic spec compliance
|
|
- Risk: Token theft if DB compromised
|
|
|
|
### Rodauth-OAuth
|
|
- ✓ PKCE support
|
|
- ✓ JWT signing
|
|
- ✓ Token hashing (bcrypt by default)
|
|
- ✓ Token rotation policies
|
|
- ✓ DPoP support (RFC 9449)
|
|
- ✓ TLS mutual authentication
|
|
- ✓ Automatic spec updates
|
|
- ✓ Certified compliance
|
|
- Risk: Minimal (industry-standard)
|
|
|
|
---
|
|
|
|
## Cost-Benefit Summary
|
|
|
|
### Keep Your Implementation
|
|
```
|
|
Costs:
|
|
- 15-25 weeks to feature parity
|
|
- Ongoing security monitoring
|
|
- Spec compliance tracking
|
|
- Bug fixes & edge cases
|
|
|
|
Benefits:
|
|
- No framework learning
|
|
- Full code understanding
|
|
- Rails-native patterns
|
|
- Minimal dependencies
|
|
```
|
|
|
|
### Switch to Rodauth-OAuth
|
|
```
|
|
Costs:
|
|
- 5-9 weeks migration effort
|
|
- Learn Roda/Rodauth
|
|
- Database schema changes
|
|
- Test all flows
|
|
|
|
Benefits:
|
|
- Get 34 features immediately
|
|
- Certified compliance
|
|
- Community-maintained
|
|
- Security best practices
|
|
- Ongoing support
|
|
```
|
|
|
|
### Hybrid Approach
|
|
```
|
|
Costs:
|
|
- 3-5 weeks setup
|
|
- Learn Roda basics
|
|
- Operate two services
|
|
- Service communication
|
|
|
|
Benefits:
|
|
- All Rodauth-OAuth features
|
|
- Rails app unchanged
|
|
- Independent scaling
|
|
- Clear separation of concerns
|
|
```
|
|
|
|
---
|
|
|
|
## Decision Scorecard
|
|
|
|
| Factor | Option A | Option B | Option C |
|
|
|--------|----------|----------|----------|
|
|
| Initial Time | Low | Medium | Medium-Low |
|
|
| Ongoing Effort | High | Low | Medium |
|
|
| Feature Completeness | Low | High | High |
|
|
| Framework Learning | None | Medium | Low |
|
|
| Standards Compliance | Manual | Auto | Auto |
|
|
| Deployment Complexity | Simple | Simple | Complex |
|
|
| Team Preference | ??? | ??? | ??? |
|
|
|
|
---
|
|
|
|
## Next Actions
|
|
|
|
### For Option A (Keep Custom):
|
|
1. Plan feature roadmap (refresh tokens first)
|
|
2. Allocate team capacity for implementation
|
|
3. Document OAuth decisions
|
|
4. Set up security monitoring
|
|
|
|
### For Option B (Full Migration):
|
|
1. Assign someone to learn Roda/Rodauth
|
|
2. Run rodauth-oauth examples
|
|
3. Plan database migration
|
|
4. Schedule migration window
|
|
5. Prepare rollback plan
|
|
|
|
### For Option C (Hybrid):
|
|
1. Evaluate microservices capability
|
|
2. Run Rodauth-OAuth example
|
|
3. Plan service boundaries
|
|
4. Set up service communication
|
|
5. Plan infrastructure for two services
|
|
|
|
---
|
|
|
|
## Still Can't Decide?
|
|
|
|
Ask these questions:
|
|
1. **Will you add features beyond Auth Code + PKCE in next 12 months?**
|
|
- YES → Option B or C
|
|
- NO → Option A
|
|
|
|
2. **Do you have maintenance bandwidth?**
|
|
- YES → Option A
|
|
- NO → Option B or C
|
|
|
|
3. **Can you run multiple services?**
|
|
- YES → Option C (best of both)
|
|
- NO → Option B (if framework is OK) or Option A (stay Rails)
|
|
|
|
---
|
|
|
|
## Document Files
|
|
|
|
You now have three documents:
|
|
1. **rodauth-oauth-analysis.md** - Deep technical analysis (12 sections)
|
|
2. **rodauth-oauth-quick-reference.md** - Quick lookup guide
|
|
3. **RODAUTH_DECISION_GUIDE.md** - This decision framework
|
|
|
|
Read in this order:
|
|
1. This guide (make a decision)
|
|
2. Quick reference (understand architecture)
|
|
3. Analysis (deep dive on your choice)
|
|
|
|
---
|
|
|
|
**Made Your Decision?** Create an issue/commit to document your choice and next steps!
|