Add files to support brakeman and standardrb. Fix some SRB warnings
This commit is contained in:
Dan Milne
275
docs/README_RODAUTH_ANALYSIS.md
Normal file
275
docs/README_RODAUTH_ANALYSIS.md
Normal file
@@ -0,0 +1,275 @@
|
||||
# Rodauth-OAuth Analysis Documents
|
||||
|
||||
This directory contains a comprehensive analysis of rodauth-oauth and how it compares to your custom OIDC implementation in Clinch.
|
||||
|
||||
## Start Here
|
||||
|
||||
### 1. **RODAUTH_DECISION_GUIDE.md** (15-minute read)
|
||||
**Purpose:** Help you make a decision about your OAuth/OIDC implementation
|
||||
|
||||
**Contains:**
|
||||
- TL;DR of three options
|
||||
- Decision flowchart
|
||||
- Feature roadmap scenarios
|
||||
- Effort estimates for each path
|
||||
- Security comparison
|
||||
- Real-world questions to ask your team
|
||||
- Next actions for each option
|
||||
|
||||
**Best for:** Deciding whether to keep your implementation, migrate, or use a hybrid approach
|
||||
|
||||
---
|
||||
|
||||
### 2. **rodauth-oauth-quick-reference.md** (20-minute read)
|
||||
**Purpose:** Quick lookup guide and architecture overview
|
||||
|
||||
**Contains:**
|
||||
- What Rodauth-OAuth is (concise)
|
||||
- Key statistics and certifications
|
||||
- Feature advantages & disadvantages
|
||||
- Architecture diagrams (text-based)
|
||||
- Database schema comparison
|
||||
- Feature matrix with implementation effort
|
||||
- Performance considerations
|
||||
- Getting started guide
|
||||
- Code examples (minimal setup)
|
||||
|
||||
**Best for:** Understanding what you're looking at, quick decision support
|
||||
|
||||
---
|
||||
|
||||
### 3. **rodauth-oauth-analysis.md** (45-minute deep-dive)
|
||||
**Purpose:** Comprehensive technical analysis for decision-making
|
||||
|
||||
**Contains:**
|
||||
- Complete architecture breakdown (12 sections)
|
||||
- All 34 features detailed and explained
|
||||
- Full database schema documentation
|
||||
- Request flow diagrams
|
||||
- Feature dependency graphs
|
||||
- Integration paths with Rails
|
||||
- Security analysis
|
||||
- Migration procedures
|
||||
- Code comparisons
|
||||
- Performance metrics
|
||||
|
||||
**Best for:** Deep understanding before making technical decisions, planning migrations
|
||||
|
||||
---
|
||||
|
||||
## How to Use These Documents
|
||||
|
||||
### Scenario 1: "I have 15 minutes"
|
||||
1. Read: RODAUTH_DECISION_GUIDE.md (sections: TL;DR + Decision Matrix)
|
||||
2. Go to: Next Actions for your chosen option
|
||||
3. Done: You have a direction
|
||||
|
||||
### Scenario 2: "I have 45 minutes"
|
||||
1. Read: RODAUTH_DECISION_GUIDE.md (complete)
|
||||
2. Skim: rodauth-oauth-quick-reference.md (focus on code examples)
|
||||
3. Decide: Which path interests you most
|
||||
4. Plan: Team discussion using decision matrix
|
||||
|
||||
### Scenario 3: "I'm doing technical deep-dive"
|
||||
1. Read: RODAUTH_DECISION_GUIDE.md (complete)
|
||||
2. Read: rodauth-oauth-quick-reference.md (complete)
|
||||
3. Read: rodauth-oauth-analysis.md (sections 1-6)
|
||||
4. Reference: rodauth-oauth-analysis.md (sections 7-12 as needed)
|
||||
|
||||
### Scenario 4: "I'm planning a migration"
|
||||
1. Read: RODAUTH_DECISION_GUIDE.md (effort estimates section)
|
||||
2. Read: rodauth-oauth-analysis.md (migration path section)
|
||||
3. Reference: rodauth-oauth-analysis.md (database schema section)
|
||||
4. Plan: Detailed migration steps
|
||||
|
||||
---
|
||||
|
||||
## Three Options Explained (Very Brief)
|
||||
|
||||
### Option A: Keep Your Implementation
|
||||
- **Time:** Ongoing (add features incrementally)
|
||||
- **Effort:** 4-6 months to reach feature parity
|
||||
- **Maintenance:** 8-10 hours/month
|
||||
- **Best if:** Auth Code + PKCE is sufficient forever
|
||||
|
||||
### Option B: Switch to Rodauth-OAuth
|
||||
- **Time:** 5-9 weeks (one-time migration)
|
||||
- **Learning:** 1-2 weeks (Roda framework)
|
||||
- **Maintenance:** 1-2 hours/month
|
||||
- **Best if:** Need enterprise features, want low maintenance
|
||||
|
||||
### Option C: Hybrid Approach (Microservices)
|
||||
- **Time:** 3-5 weeks (independent setup)
|
||||
- **Learning:** Low (Roda is isolated)
|
||||
- **Maintenance:** 2-3 hours/month
|
||||
- **Best if:** Want Option B benefits without full Rails→Roda migration
|
||||
|
||||
---
|
||||
|
||||
## Key Findings
|
||||
|
||||
**What Rodauth-OAuth Provides That You Don't Have:**
|
||||
- Refresh tokens
|
||||
- Token revocation (RFC 7009)
|
||||
- Token introspection (RFC 7662)
|
||||
- Client Credentials grant (machine-to-machine)
|
||||
- Device Code flow (IoT/smart TV)
|
||||
- JWT Access Tokens (stateless)
|
||||
- Session Management
|
||||
- Front & Back-Channel Logout
|
||||
- Token hashing (bcrypt security)
|
||||
- DPoP support (token binding)
|
||||
- TLS mutual authentication
|
||||
- Dynamic Client Registration
|
||||
- 20+ more optional features
|
||||
|
||||
**Security Differences:**
|
||||
- Your impl: Tokens stored in plaintext (DB breach = token theft)
|
||||
- Rodauth: Tokens hashed with bcrypt (secure even if DB breached)
|
||||
|
||||
**Maintenance Burden:**
|
||||
- Your impl: YOU maintain everything
|
||||
- Rodauth: Community maintains, you maintain config only
|
||||
|
||||
---
|
||||
|
||||
## Document Structure
|
||||
|
||||
### RODAUTH_DECISION_GUIDE.md Sections:
|
||||
```
|
||||
1. TL;DR - Three options
|
||||
2. Decision Matrix - Flowchart
|
||||
3. Feature Roadmap Comparison
|
||||
4. Architecture Diagrams (visual)
|
||||
5. Effort Estimates
|
||||
6. Real-World Questions
|
||||
7. Security Comparison
|
||||
8. Cost-Benefit Summary
|
||||
9. Decision Scorecard
|
||||
10. Next Actions
|
||||
```
|
||||
|
||||
### rodauth-oauth-quick-reference.md Sections:
|
||||
```
|
||||
1. What Is It? (overview)
|
||||
2. Key Stats
|
||||
3. Why Consider It? (advantages)
|
||||
4. Architecture Overview (your impl vs rodauth)
|
||||
5. Database Schema Comparison
|
||||
6. Feature Comparison Matrix
|
||||
7. Code Examples
|
||||
8. Integration Paths
|
||||
9. Getting Started
|
||||
10. Next Steps
|
||||
```
|
||||
|
||||
### rodauth-oauth-analysis.md Sections:
|
||||
```
|
||||
1. Executive Summary
|
||||
2. What Rodauth-OAuth Is
|
||||
3. File Structure & Organization
|
||||
4. OIDC/OAuth Features
|
||||
5. Architecture: How It Works
|
||||
6. Database Schema Requirements
|
||||
7. Integration with Rails
|
||||
8. Architectural Comparison
|
||||
9. Feature Matrix
|
||||
10. Integration Complexity
|
||||
11. Key Findings & Recommendations
|
||||
12. Migration Path & Code Examples
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## For Your Team
|
||||
|
||||
### Sharing with Stakeholders
|
||||
- **Non-technical:** Use RODAUTH_DECISION_GUIDE.md (TL;DR section)
|
||||
- **Technical leads:** Use rodauth-oauth-quick-reference.md
|
||||
- **Engineers:** Use rodauth-oauth-analysis.md (sections 1-6)
|
||||
- **Security team:** Use rodauth-oauth-analysis.md (security sections)
|
||||
|
||||
### Team Discussion
|
||||
Print out the decision matrix from RODAUTH_DECISION_GUIDE.md and:
|
||||
1. Walk through each option
|
||||
2. Discuss team comfort with framework learning
|
||||
3. Check against feature roadmap
|
||||
4. Decide on maintenance philosophy
|
||||
5. Vote on preferred option
|
||||
|
||||
---
|
||||
|
||||
## Next Steps After Reading
|
||||
|
||||
### If Choosing Option A (Keep Custom):
|
||||
- [ ] Plan feature roadmap (refresh tokens first)
|
||||
- [ ] Allocate team capacity
|
||||
- [ ] Add token hashing security
|
||||
- [ ] Set up security monitoring
|
||||
|
||||
### If Choosing Option B (Full Migration):
|
||||
- [ ] Assign team member to learn Roda/Rodauth
|
||||
- [ ] Run examples from `/tmp/rodauth-oauth/examples`
|
||||
- [ ] Plan database migration
|
||||
- [ ] Prepare rollback plan
|
||||
- [ ] Schedule migration window
|
||||
|
||||
### If Choosing Option C (Hybrid):
|
||||
- [ ] Evaluate microservices capability
|
||||
- [ ] Review service communication plan
|
||||
- [ ] Set up service infrastructure
|
||||
- [ ] Plan gradual deployment
|
||||
|
||||
---
|
||||
|
||||
## Bonus: Running the Example
|
||||
|
||||
Rodauth-OAuth includes a working OIDC server example you can run:
|
||||
|
||||
```bash
|
||||
cd /Users/dkam/Development/clinch/tmp/rodauth-oauth/examples/oidc
|
||||
ruby authentication_server.rb
|
||||
|
||||
# Then visit: http://localhost:9292
|
||||
# Login with: foo@bar.com / password
|
||||
# See: Full OIDC provider in action
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Questions?
|
||||
|
||||
These documents should answer:
|
||||
- What is rodauth-oauth?
|
||||
- How does it compare to my implementation?
|
||||
- What features would we gain?
|
||||
- What would we lose?
|
||||
- How much effort is a migration?
|
||||
- Should we switch?
|
||||
|
||||
If questions remain, reference the specific section in the analysis documents.
|
||||
|
||||
---
|
||||
|
||||
## Document Generation Info
|
||||
|
||||
**Generated:** November 12, 2025
|
||||
**Analysis Duration:** Complete codebase exploration of rodauth-oauth gem
|
||||
**Sources Analyzed:**
|
||||
- 34 feature files (10,000+ lines of code)
|
||||
- 7 database migrations
|
||||
- 6 complete example applications
|
||||
- Comprehensive test suite
|
||||
- README and migration guides
|
||||
|
||||
**Analysis Includes:**
|
||||
- Line-by-line code structure review
|
||||
- Database schema comparison
|
||||
- Feature cross-reference analysis
|
||||
- Integration complexity assessment
|
||||
- Security analysis
|
||||
- Effort estimation models
|
||||
|
||||
---
|
||||
|
||||
**Start with RODAUTH_DECISION_GUIDE.md and go from there!**
|
||||
426
docs/RODAUTH_DECISION_GUIDE.md
Normal file
426
docs/RODAUTH_DECISION_GUIDE.md
Normal file
@@ -0,0 +1,426 @@
|
||||
# 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!
|
||||
176
docs/caddy-example.md
Normal file
176
docs/caddy-example.md
Normal file
@@ -0,0 +1,176 @@
|
||||
# Caddy ForwardAuth Configuration Examples
|
||||
|
||||
## Basic Configuration (Protecting MEtube)
|
||||
|
||||
Assuming Caddy and Clinch are running in a docker compose, and we can use the sevice name `clinch`. Exterally, assume you're connecting to https://clinch.example.com/
|
||||
|
||||
```caddyfile
|
||||
# Clinch SSO (main authentication server)
|
||||
clinch.yourdomain.com {
|
||||
reverse_proxy clinch:3000
|
||||
}
|
||||
|
||||
# MEtube (protected by Clinch)
|
||||
metube.yourdomain.com {
|
||||
# Forward authentication to Clinch
|
||||
forward_auth clinch:3000 {
|
||||
uri /api/verify
|
||||
# uri /api/verify?rd=https://clinch.yourdomain.com # Shouldn't need this, the rd value should be sent via headers
|
||||
copy_headers Remote-User Remote-Email Remote-Groups Remote-Admin
|
||||
}
|
||||
|
||||
# If authentication succeeds, proxy to MEtube
|
||||
handle {
|
||||
reverse_proxy * {
|
||||
to http://<ip-address-of-metube>:8081
|
||||
header_up X-Real-IP {remote_host}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
1. User visits `https://metube.yourdomain.com`
|
||||
2. Caddy makes request to `http://clinch:3000/api/verify passing in the url destination for metueb
|
||||
3. Clinch checks if user is authenticated and authorized:
|
||||
- If **200**: Caddy forwards request to MEtube with user headers
|
||||
- If **302**: User is redirected to clinch.yourdomain.com to login
|
||||
- If **403**: Access denied
|
||||
4. User signs into Clinch (with TOTP if enabled or Passkey)
|
||||
5. Clinch redirects back to MEtube
|
||||
6. User can now access MEtube!
|
||||
|
||||
## Protecting Multiple Applications
|
||||
|
||||
```caddyfile
|
||||
# Clinch SSO
|
||||
clinch.yourdomain.com {
|
||||
reverse_proxy clinch:3000
|
||||
}
|
||||
|
||||
# MEtube - Anyone can access (no groups required)
|
||||
metube.yourdomain.com {
|
||||
forward_auth clinch:3000 {
|
||||
uri /api/verify
|
||||
copy_headers Remote-User Remote-Email Remote-Groups Remote-Admin
|
||||
}
|
||||
|
||||
handle {
|
||||
reverse_proxy * {
|
||||
to http://metube:8081
|
||||
header_up X-Real-IP {remote_host}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# Sonarr - Only "media-managers" group
|
||||
sonarr.yourdomain.com {
|
||||
forward_auth clinch:3000 {
|
||||
uri /api/verify
|
||||
copy_headers Remote-User Remote-Email Remote-Groups Remote-Admin
|
||||
}
|
||||
|
||||
handle {
|
||||
reverse_proxy * {
|
||||
to http://sonarr:8989
|
||||
header_up X-Real-IP {remote_host}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# Grafana - Only "admins" group
|
||||
grafana.yourdomain.com {
|
||||
forward_auth clinch:3000 {
|
||||
uri /api/verify
|
||||
copy_headers Remote-User Remote-Email Remote-Groups Remote-Admin
|
||||
}
|
||||
|
||||
handle {
|
||||
reverse_proxy * {
|
||||
to http://grafana:3001
|
||||
header_up X-Real-IP {remote_host}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Setup Steps
|
||||
|
||||
### 1. Create Applications in Clinch
|
||||
|
||||
Create the Application within Clinch, making sure to set Forward Auth application type
|
||||
|
||||
### 2. Update Caddyfile
|
||||
|
||||
Add the forward_auth directives shown above.
|
||||
|
||||
### 3. Reload Caddy
|
||||
|
||||
```bash
|
||||
caddy reload
|
||||
```
|
||||
|
||||
### 4. Test
|
||||
|
||||
Visit https://metube.yourdomain.com - you should be redirected to Clinch login!
|
||||
|
||||
## Advanced: Passing Headers to Application
|
||||
|
||||
Some applications can use the forwarded headers for user identification:
|
||||
|
||||
```caddyfile
|
||||
metube.yourdomain.com {
|
||||
forward_auth clinch:3000 {
|
||||
uri /api/verify
|
||||
copy_headers Remote-User Remote-Email Remote-Groups Remote-Admin
|
||||
}
|
||||
|
||||
# The headers are automatically passed to the backend
|
||||
handle {
|
||||
reverse_proxy * {
|
||||
to http://metube:8081
|
||||
header_up X-Real-IP {remote_host}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Now MEtube receives these headers with every request:
|
||||
- `Remote-User`: user@example.com
|
||||
- `Remote-Email`: user@example.com
|
||||
- `Remote-Groups`: media-managers,users
|
||||
- `Remote-Admin`: false
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Users not staying logged in
|
||||
|
||||
Ensure your Caddy configuration preserves cookies:
|
||||
|
||||
```caddyfile
|
||||
clinch.yourdomain.com {
|
||||
reverse_proxy localhost:3000 {
|
||||
header_up X-Forwarded-Host {host}
|
||||
header_up X-Forwarded-Proto {scheme}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Authentication loop
|
||||
|
||||
Check that the `/api/verify` endpoint is not itself protected:
|
||||
- `/api/verify` must be accessible without authentication
|
||||
- It returns 401/403 for unauthenticated users (this is expected)
|
||||
|
||||
### Check Clinch logs
|
||||
|
||||
```bash
|
||||
tail -f log/production.log
|
||||
```
|
||||
|
||||
You'll see ForwardAuth log messages like:
|
||||
```
|
||||
ForwardAuth: User user@example.com granted access to metube
|
||||
ForwardAuth: Unauthorized - No session cookie
|
||||
```
|
||||
227
docs/forward-auth-testing.md
Normal file
227
docs/forward-auth-testing.md
Normal file
@@ -0,0 +1,227 @@
|
||||
# Forward Auth Testing Guide
|
||||
|
||||
## Overview
|
||||
Testing forward authentication requires testing multiple layers: HTTP requests, session management, and header forwarding. This guide provides practical testing approaches.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Start Rails Server
|
||||
```bash
|
||||
rails server
|
||||
```
|
||||
|
||||
### 2. Basic curl Tests
|
||||
|
||||
#### Test 1: Unauthenticated Request
|
||||
```bash
|
||||
curl -v http://localhost:3000/api/verify \
|
||||
-H "X-Forwarded-Host: test.example.com"
|
||||
```
|
||||
|
||||
**Expected Result:** 302 redirect to login
|
||||
```
|
||||
< HTTP/1.1 302 Found
|
||||
< Location: http://localhost:3000/signin?rd=https://test.example.com/
|
||||
< X-Auth-Reason: No session cookie
|
||||
```
|
||||
|
||||
#### Test 2: Authenticated Request
|
||||
1. Sign in at http://localhost:3000/signin
|
||||
2. Copy session cookie from browser
|
||||
3. Run:
|
||||
```bash
|
||||
curl -v http://localhost:3000/api/verify \
|
||||
-H "X-Forwarded-Host: test.example.com" \
|
||||
-H "Cookie: _clinch_session_id=YOUR_SESSION_COOKIE"
|
||||
```
|
||||
|
||||
**Expected Result:** 200 OK with headers
|
||||
```
|
||||
< HTTP/1.1 200 OK
|
||||
< X-Remote-User: your-email@example.com
|
||||
< X-Remote-Email: your-email@example.com
|
||||
< X-Remote-Name: your-email@example.com
|
||||
< X-Remote-Groups: group-name
|
||||
< X-Remote-Admin: true/false
|
||||
```
|
||||
|
||||
## Testing Header Configurations
|
||||
|
||||
### Create Test Rules in Admin Interface
|
||||
|
||||
1. **Default Headers Rule** (`test.example.com`)
|
||||
- Leave header fields empty (uses defaults)
|
||||
- Expected: X-Remote-* headers
|
||||
|
||||
2. **No Headers Rule** (`metube.example.com`)
|
||||
- Set all header fields to empty strings
|
||||
- Expected: No authentication headers (access only)
|
||||
|
||||
3. **Custom Headers Rule** (`grafana.example.com`)
|
||||
- Set custom header names:
|
||||
- User Header: `X-WEBAUTH-USER`
|
||||
- Groups Header: `X-WEBAUTH-ROLES`
|
||||
- Email Header: `X-WEBAUTH-EMAIL`
|
||||
- Expected: Custom header names
|
||||
|
||||
### Test Different Configurations
|
||||
|
||||
```bash
|
||||
# Test default headers
|
||||
curl -v http://localhost:3000/api/verify \
|
||||
-H "X-Forwarded-Host: test.example.com" \
|
||||
-H "Cookie: _clinch_session_id=YOUR_SESSION_COOKIE"
|
||||
|
||||
# Test no headers (access only)
|
||||
curl -v http://localhost:3000/api/verify \
|
||||
-H "X-Forwarded-Host: metube.example.com" \
|
||||
-H "Cookie: _clinch_session_id=YOUR_SESSION_COOKIE"
|
||||
|
||||
# Test custom headers
|
||||
curl -v http://localhost:3000/api/verify \
|
||||
-H "X-Forwarded-Host: grafana.example.com" \
|
||||
-H "Cookie: _clinch_session_id=YOUR_SESSION_COOKIE"
|
||||
```
|
||||
|
||||
## Domain Pattern Testing
|
||||
|
||||
Test various domain patterns:
|
||||
|
||||
```bash
|
||||
# Wildcard subdomains
|
||||
curl -v http://localhost:3000/api/verify \
|
||||
-H "X-Forwarded-Host: app.test.example.com"
|
||||
|
||||
# Exact domains
|
||||
curl -v http://localhost:3000/api/verify \
|
||||
-H "X-Forwarded-Host: api.example.com"
|
||||
|
||||
# No matching rule (should use defaults)
|
||||
curl -v http://localhost:3000/api/verify \
|
||||
-H "X-Forwarded-Host: unknown.example.com"
|
||||
```
|
||||
|
||||
## Integration Testing
|
||||
|
||||
### Test with Real Reverse Proxy (Caddy Example)
|
||||
|
||||
1. Set up Caddy with forward auth:
|
||||
```caddyfile
|
||||
example.com {
|
||||
forward_auth localhost:3000 {
|
||||
uri /api/verify
|
||||
copy_headers X-Remote-User X-Remote-Email X-Remote-Groups X-Remote-Admin
|
||||
}
|
||||
|
||||
reverse_proxy localhost:8080
|
||||
}
|
||||
```
|
||||
|
||||
2. Test by visiting `https://example.com` in browser
|
||||
3. Should redirect to Clinch login, then back to application
|
||||
|
||||
## Unit Testing (Rails Console)
|
||||
|
||||
Test the header logic directly:
|
||||
|
||||
```ruby
|
||||
# Rails console: rails console
|
||||
|
||||
# Get a user
|
||||
user = User.first
|
||||
|
||||
# Test default headers
|
||||
rule = ForwardAuthRule.create!(domain_pattern: 'test.example.com', active: true)
|
||||
headers = rule.headers_for_user(user)
|
||||
puts headers
|
||||
# => {"X-Remote-User" => "user@example.com", "X-Remote-Email" => "user@example.com", ...}
|
||||
|
||||
# Test custom headers
|
||||
rule.update!(headers_config: { user: 'X-Custom-User', groups: 'X-Custom-Groups' })
|
||||
headers = rule.headers_for_user(user)
|
||||
puts headers
|
||||
# => {"X-Custom-User" => "user@example.com", "X-Remote-Email" => "user@example.com", ...}
|
||||
|
||||
# Test no headers
|
||||
rule.update!(headers_config: { user: '', email: '', name: '', groups: '', admin: '' })
|
||||
headers = rule.headers_for_user(user)
|
||||
puts headers
|
||||
# => {}
|
||||
```
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
### Basic Functionality
|
||||
- [ ] Unauthenticated requests redirect to login
|
||||
- [ ] Authenticated requests return 200 OK
|
||||
- [ ] Headers are correctly forwarded to applications
|
||||
- [ ] Session cookies work correctly
|
||||
|
||||
### Header Configurations
|
||||
- [ ] Default headers (X-Remote-*) work
|
||||
- [ ] Custom headers work with specific applications
|
||||
- [ ] No headers option works for access-only apps
|
||||
- [ ] Empty header fields are handled correctly
|
||||
|
||||
### Domain Matching
|
||||
- [ ] Wildcard domains (*.example.com) work
|
||||
- [ ] Exact domains work
|
||||
- [ ] Case insensitivity works
|
||||
- [ ] No matching rule falls back to defaults
|
||||
|
||||
### Access Control
|
||||
- [ ] Group restrictions work correctly
|
||||
- [ ] Inactive users are denied access
|
||||
- [ ] Inactive rules are ignored
|
||||
- [ ] Bypass mode (no groups) works
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Headers not being sent**
|
||||
- Check rule is active
|
||||
- Verify headers configuration
|
||||
- Check user is in allowed groups
|
||||
|
||||
2. **Authentication loops**
|
||||
- Check session cookie domain
|
||||
- Verify redirect URLs
|
||||
- Check browser cookie settings
|
||||
|
||||
3. **Headers not reaching application**
|
||||
- Check reverse proxy configuration
|
||||
- Verify proxy is forwarding headers
|
||||
- Check application expects correct header names
|
||||
|
||||
### Debug Logging
|
||||
|
||||
Enable debug logging in `forward_auth_controller.rb`:
|
||||
```ruby
|
||||
Rails.logger.level = Logger::DEBUG
|
||||
```
|
||||
|
||||
This will show detailed information about:
|
||||
- Session extraction
|
||||
- Rule matching
|
||||
- Header generation
|
||||
- Redirect URLs
|
||||
|
||||
## Production Testing
|
||||
|
||||
Before deploying to production:
|
||||
|
||||
1. **SSL/TLS Testing**: Test with HTTPS
|
||||
2. **Cookie Domains**: Test cross-subdomain cookies
|
||||
3. **Performance**: Test response times under load
|
||||
4. **Security**: Test with invalid sessions and malformed headers
|
||||
5. **Monitoring**: Set up logging and alerting
|
||||
|
||||
## Automation
|
||||
|
||||
For automated testing, consider:
|
||||
|
||||
1. **Integration Tests**: Use Rails integration tests for controller testing
|
||||
2. **API Tests**: Use tools like Postman or Insomnia for API testing
|
||||
3. **Browser Tests**: Use Selenium or Cypress for end-to-end testing
|
||||
4. **Load Testing**: Use tools like k6 or JMeter for performance testing
|
||||
611
docs/oidc-refresh-tokens-client-guide.md
Normal file
611
docs/oidc-refresh-tokens-client-guide.md
Normal file
@@ -0,0 +1,611 @@
|
||||
# OIDC Refresh Tokens - Client Implementation Guide
|
||||
|
||||
## Overview
|
||||
|
||||
Clinch now supports **OAuth 2.0 Refresh Tokens**, allowing your applications to maintain long-lived sessions without requiring users to re-authenticate every hour.
|
||||
|
||||
**Key Benefits:**
|
||||
- ✅ No user re-authentication for 30 days (configurable)
|
||||
- ✅ Silent token refresh - no redirects, no user interaction
|
||||
- ✅ Secure token rotation - prevents reuse attacks
|
||||
- ✅ Token revocation support - users can invalidate sessions
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Before (Without Refresh Tokens)
|
||||
```
|
||||
User logs in → Access token (1 hour)
|
||||
After 1 hour → Redirect to /oauth/authorize
|
||||
User auto-approves → New access token
|
||||
Repeat every hour... 😞
|
||||
```
|
||||
|
||||
### Now (With Refresh Tokens)
|
||||
```
|
||||
User logs in → Access token (1 hour) + Refresh token (30 days)
|
||||
After 1 hour → POST to /oauth/token with refresh_token
|
||||
Get new tokens → No redirect! No user interaction! 🎉
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Initial Authorization
|
||||
|
||||
### 1. Authorization Code Flow (Unchanged)
|
||||
|
||||
**Step 1: Redirect user to authorization endpoint**
|
||||
```
|
||||
GET https://auth.example.com/oauth/authorize?
|
||||
client_id=YOUR_CLIENT_ID&
|
||||
redirect_uri=https://yourapp.com/callback&
|
||||
response_type=code&
|
||||
scope=openid%20profile%20email&
|
||||
state=RANDOM_STATE&
|
||||
code_challenge=BASE64URL(SHA256(code_verifier))&
|
||||
code_challenge_method=S256
|
||||
```
|
||||
|
||||
**Step 2: Exchange authorization code for tokens**
|
||||
```http
|
||||
POST https://auth.example.com/oauth/token
|
||||
Content-Type: application/x-www-form-urlencoded
|
||||
|
||||
grant_type=authorization_code
|
||||
&code=AUTHORIZATION_CODE
|
||||
&redirect_uri=https://yourapp.com/callback
|
||||
&client_id=YOUR_CLIENT_ID
|
||||
&client_secret=YOUR_CLIENT_SECRET
|
||||
&code_verifier=CODE_VERIFIER
|
||||
```
|
||||
|
||||
**Response (NEW - now includes refresh_token):**
|
||||
```json
|
||||
{
|
||||
"access_token": "eyJhbGc...",
|
||||
"token_type": "Bearer",
|
||||
"expires_in": 3600,
|
||||
"id_token": "eyJhbGc...",
|
||||
"refresh_token": "abc123xyz...",
|
||||
"scope": "openid profile email"
|
||||
}
|
||||
```
|
||||
|
||||
**IMPORTANT:** Store the `refresh_token` securely! You'll need it to get new access tokens.
|
||||
|
||||
---
|
||||
|
||||
## Token Refresh Flow
|
||||
|
||||
When your `access_token` expires (after 1 hour), use the `refresh_token` to get new tokens **without user interaction**.
|
||||
|
||||
### How to Refresh Tokens
|
||||
|
||||
**Request:**
|
||||
```http
|
||||
POST https://auth.example.com/oauth/token
|
||||
Content-Type: application/x-www-form-urlencoded
|
||||
|
||||
grant_type=refresh_token
|
||||
&refresh_token=YOUR_REFRESH_TOKEN
|
||||
&client_id=YOUR_CLIENT_ID
|
||||
&client_secret=YOUR_CLIENT_SECRET
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"access_token": "eyJhbGc...NEW",
|
||||
"token_type": "Bearer",
|
||||
"expires_in": 3600,
|
||||
"id_token": "eyJhbGc...NEW",
|
||||
"refresh_token": "def456uvw...NEW",
|
||||
"scope": "openid profile email"
|
||||
}
|
||||
```
|
||||
|
||||
**CRITICAL:**
|
||||
- The old `refresh_token` is **immediately revoked** (single-use)
|
||||
- You receive a **new `refresh_token`** to use next time
|
||||
- **Replace** the old refresh token with the new one in your storage
|
||||
|
||||
---
|
||||
|
||||
## Token Lifecycle
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Initial Authorization │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ GET /oauth/authorize → User logs in │
|
||||
│ POST /oauth/token (authorization_code grant) │
|
||||
│ ↓ │
|
||||
│ Receive: access_token (1h) + refresh_token (30d) │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
│
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Token Refresh (Silent, No User Interaction) │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ After 1 hour (access_token expires): │
|
||||
│ POST /oauth/token (refresh_token grant) │
|
||||
│ ↓ │
|
||||
│ Receive: NEW access_token + NEW refresh_token │
|
||||
│ Old refresh_token is revoked │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
│
|
||||
↓ (Repeat for 30 days)
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Session Expiry │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ After 30 days (refresh_token expires): │
|
||||
│ Redirect user to /oauth/authorize for re-authentication │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Token Storage Best Practices
|
||||
|
||||
### ✅ Secure Storage Recommendations
|
||||
|
||||
**Web Applications (Server-Side):**
|
||||
- Store refresh tokens in **server-side session** (encrypted)
|
||||
- Use **HttpOnly, Secure cookies** for access tokens
|
||||
- **Never** send refresh tokens to browser JavaScript
|
||||
|
||||
**Single Page Applications (SPAs):**
|
||||
- Store access tokens in **memory only** (JavaScript variable)
|
||||
- Store refresh tokens in **HttpOnly, Secure cookie** (via backend)
|
||||
- Use Backend-for-Frontend (BFF) pattern for refresh
|
||||
|
||||
**Mobile Apps:**
|
||||
- Use platform-specific **secure storage**:
|
||||
- iOS: Keychain
|
||||
- Android: EncryptedSharedPreferences or Keystore
|
||||
- **Never** store in UserDefaults/SharedPreferences
|
||||
|
||||
**Desktop Apps:**
|
||||
- Use OS-specific credential storage
|
||||
- Encrypt tokens at rest
|
||||
|
||||
### ❌ DO NOT Store Refresh Tokens In:
|
||||
- LocalStorage (XSS vulnerable)
|
||||
- SessionStorage (XSS vulnerable)
|
||||
- Unencrypted cookies
|
||||
- Plain text files
|
||||
- Source code or config files
|
||||
|
||||
---
|
||||
|
||||
## Token Revocation
|
||||
|
||||
Allow users to invalidate their sessions (e.g., "Sign out of all devices").
|
||||
|
||||
### Revoke a Token
|
||||
|
||||
**Request:**
|
||||
```http
|
||||
POST https://auth.example.com/oauth/revoke
|
||||
Content-Type: application/x-www-form-urlencoded
|
||||
|
||||
token=YOUR_TOKEN
|
||||
&token_type_hint=refresh_token
|
||||
&client_id=YOUR_CLIENT_ID
|
||||
&client_secret=YOUR_CLIENT_SECRET
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `token` (required) - The token to revoke (access or refresh token)
|
||||
- `token_type_hint` (optional) - "access_token" or "refresh_token"
|
||||
- `client_id` + `client_secret` (required) - Client authentication
|
||||
|
||||
**Response:**
|
||||
```
|
||||
HTTP/1.1 200 OK
|
||||
```
|
||||
|
||||
**Note:** Per RFC 7009, the response is always `200 OK`, even if the token was invalid or already revoked (prevents token scanning attacks).
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Refresh Token Errors
|
||||
|
||||
#### 1. Invalid or Expired Refresh Token
|
||||
```json
|
||||
{
|
||||
"error": "invalid_grant",
|
||||
"error_description": "Invalid refresh token"
|
||||
}
|
||||
```
|
||||
**Action:** Redirect user to /oauth/authorize for re-authentication
|
||||
|
||||
#### 2. Refresh Token Revoked (Reuse Detected!)
|
||||
```json
|
||||
{
|
||||
"error": "invalid_grant",
|
||||
"error_description": "Refresh token has been revoked"
|
||||
}
|
||||
```
|
||||
**Action:**
|
||||
- This indicates a **security issue** (possible token theft)
|
||||
- All tokens in the same family are revoked
|
||||
- Redirect user to /oauth/authorize
|
||||
- Consider alerting the user about suspicious activity
|
||||
|
||||
#### 3. Invalid Client Credentials
|
||||
```json
|
||||
{
|
||||
"error": "invalid_client"
|
||||
}
|
||||
```
|
||||
**Action:** Check your `client_id` and `client_secret`
|
||||
|
||||
---
|
||||
|
||||
## Implementation Examples
|
||||
|
||||
### Example 1: Node.js Express
|
||||
|
||||
```javascript
|
||||
const axios = require('axios');
|
||||
|
||||
class OAuthClient {
|
||||
constructor(config) {
|
||||
this.clientId = config.clientId;
|
||||
this.clientSecret = config.clientSecret;
|
||||
this.tokenEndpoint = config.tokenEndpoint;
|
||||
this.accessToken = null;
|
||||
this.refreshToken = null;
|
||||
this.expiresAt = null;
|
||||
}
|
||||
|
||||
// Exchange authorization code for tokens
|
||||
async exchangeCode(code, redirectUri, codeVerifier) {
|
||||
const response = await axios.post(this.tokenEndpoint, new URLSearchParams({
|
||||
grant_type: 'authorization_code',
|
||||
code: code,
|
||||
redirect_uri: redirectUri,
|
||||
client_id: this.clientId,
|
||||
client_secret: this.clientSecret,
|
||||
code_verifier: codeVerifier
|
||||
}));
|
||||
|
||||
this.storeTokens(response.data);
|
||||
return response.data;
|
||||
}
|
||||
|
||||
// Refresh access token
|
||||
async refreshAccessToken() {
|
||||
if (!this.refreshToken) {
|
||||
throw new Error('No refresh token available');
|
||||
}
|
||||
|
||||
const response = await axios.post(this.tokenEndpoint, new URLSearchParams({
|
||||
grant_type: 'refresh_token',
|
||||
refresh_token: this.refreshToken,
|
||||
client_id: this.clientId,
|
||||
client_secret: this.clientSecret
|
||||
}));
|
||||
|
||||
this.storeTokens(response.data);
|
||||
return response.data;
|
||||
}
|
||||
|
||||
// Get valid access token (auto-refresh if needed)
|
||||
async getAccessToken() {
|
||||
// Check if token is expired or about to expire (5 min buffer)
|
||||
if (this.expiresAt && Date.now() >= this.expiresAt - 300000) {
|
||||
await this.refreshAccessToken();
|
||||
}
|
||||
|
||||
return this.accessToken;
|
||||
}
|
||||
|
||||
storeTokens(tokenResponse) {
|
||||
this.accessToken = tokenResponse.access_token;
|
||||
this.refreshToken = tokenResponse.refresh_token;
|
||||
this.expiresAt = Date.now() + (tokenResponse.expires_in * 1000);
|
||||
}
|
||||
|
||||
// Revoke tokens
|
||||
async revokeToken(token, tokenTypeHint) {
|
||||
await axios.post('https://auth.example.com/oauth/revoke', new URLSearchParams({
|
||||
token: token,
|
||||
token_type_hint: tokenTypeHint,
|
||||
client_id: this.clientId,
|
||||
client_secret: this.clientSecret
|
||||
}));
|
||||
}
|
||||
}
|
||||
|
||||
// Usage
|
||||
const client = new OAuthClient({
|
||||
clientId: 'your-client-id',
|
||||
clientSecret: 'your-client-secret',
|
||||
tokenEndpoint: 'https://auth.example.com/oauth/token'
|
||||
});
|
||||
|
||||
// After initial login
|
||||
await client.exchangeCode(authCode, redirectUri, codeVerifier);
|
||||
|
||||
// Make API calls (auto-refreshes if needed)
|
||||
const token = await client.getAccessToken();
|
||||
const apiResponse = await axios.get('https://api.example.com/data', {
|
||||
headers: { Authorization: `Bearer ${token}` }
|
||||
});
|
||||
|
||||
// Logout - revoke refresh token
|
||||
await client.revokeToken(client.refreshToken, 'refresh_token');
|
||||
```
|
||||
|
||||
### Example 2: Python
|
||||
|
||||
```python
|
||||
import requests
|
||||
import time
|
||||
from urllib.parse import urlencode
|
||||
|
||||
class OAuthClient:
|
||||
def __init__(self, client_id, client_secret, token_endpoint):
|
||||
self.client_id = client_id
|
||||
self.client_secret = client_secret
|
||||
self.token_endpoint = token_endpoint
|
||||
self.access_token = None
|
||||
self.refresh_token = None
|
||||
self.expires_at = None
|
||||
|
||||
def exchange_code(self, code, redirect_uri, code_verifier):
|
||||
"""Exchange authorization code for tokens"""
|
||||
response = requests.post(self.token_endpoint, data={
|
||||
'grant_type': 'authorization_code',
|
||||
'code': code,
|
||||
'redirect_uri': redirect_uri,
|
||||
'client_id': self.client_id,
|
||||
'client_secret': self.client_secret,
|
||||
'code_verifier': code_verifier
|
||||
})
|
||||
response.raise_for_status()
|
||||
self._store_tokens(response.json())
|
||||
return response.json()
|
||||
|
||||
def refresh_access_token(self):
|
||||
"""Refresh the access token using refresh token"""
|
||||
if not self.refresh_token:
|
||||
raise ValueError('No refresh token available')
|
||||
|
||||
response = requests.post(self.token_endpoint, data={
|
||||
'grant_type': 'refresh_token',
|
||||
'refresh_token': self.refresh_token,
|
||||
'client_id': self.client_id,
|
||||
'client_secret': self.client_secret
|
||||
})
|
||||
response.raise_for_status()
|
||||
self._store_tokens(response.json())
|
||||
return response.json()
|
||||
|
||||
def get_access_token(self):
|
||||
"""Get valid access token, refresh if needed"""
|
||||
# Check if token is expired (with 5 min buffer)
|
||||
if self.expires_at and time.time() >= self.expires_at - 300:
|
||||
self.refresh_access_token()
|
||||
|
||||
return self.access_token
|
||||
|
||||
def _store_tokens(self, token_response):
|
||||
"""Store tokens and expiration time"""
|
||||
self.access_token = token_response['access_token']
|
||||
self.refresh_token = token_response['refresh_token']
|
||||
self.expires_at = time.time() + token_response['expires_in']
|
||||
|
||||
def revoke_token(self, token, token_type_hint='refresh_token'):
|
||||
"""Revoke a token"""
|
||||
requests.post('https://auth.example.com/oauth/revoke', data={
|
||||
'token': token,
|
||||
'token_type_hint': token_type_hint,
|
||||
'client_id': self.client_id,
|
||||
'client_secret': self.client_secret
|
||||
})
|
||||
|
||||
# Usage
|
||||
client = OAuthClient(
|
||||
client_id='your-client-id',
|
||||
client_secret='your-client-secret',
|
||||
token_endpoint='https://auth.example.com/oauth/token'
|
||||
)
|
||||
|
||||
# After initial login
|
||||
client.exchange_code(auth_code, redirect_uri, code_verifier)
|
||||
|
||||
# Make API calls (auto-refreshes if needed)
|
||||
token = client.get_access_token()
|
||||
response = requests.get('https://api.example.com/data',
|
||||
headers={'Authorization': f'Bearer {token}'})
|
||||
|
||||
# Logout
|
||||
client.revoke_token(client.refresh_token, 'refresh_token')
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### 1. Token Rotation (Implemented ✅)
|
||||
- Each refresh token is **single-use only**
|
||||
- After use, old refresh token is immediately revoked
|
||||
- New refresh token is issued
|
||||
- Prevents replay attacks
|
||||
|
||||
### 2. Token Family Tracking (Implemented ✅)
|
||||
- All refresh tokens in a rotation chain share a `token_family_id`
|
||||
- If a **revoked** refresh token is reused → **entire family is revoked**
|
||||
- Detects stolen token attacks
|
||||
|
||||
### 3. Refresh Token Binding
|
||||
- Refresh tokens are bound to:
|
||||
- Specific client (client_id)
|
||||
- Specific user
|
||||
- Specific scopes
|
||||
- Cannot be used by different clients
|
||||
|
||||
### 4. Expiration Times (Configurable per application)
|
||||
- **Access tokens:** 5 minutes - 24 hours (default: 1 hour)
|
||||
- **Refresh tokens:** 1 day - 90 days (default: 30 days)
|
||||
- **ID tokens:** 5 minutes - 24 hours (default: 1 hour)
|
||||
|
||||
---
|
||||
|
||||
## Discovery Endpoint Updates
|
||||
|
||||
The OIDC discovery endpoint now advertises refresh token support:
|
||||
|
||||
**GET `https://auth.example.com/.well-known/openid-configuration`**
|
||||
|
||||
```json
|
||||
{
|
||||
"issuer": "https://auth.example.com",
|
||||
"authorization_endpoint": "https://auth.example.com/oauth/authorize",
|
||||
"token_endpoint": "https://auth.example.com/oauth/token",
|
||||
"revocation_endpoint": "https://auth.example.com/oauth/revoke",
|
||||
"userinfo_endpoint": "https://auth.example.com/oauth/userinfo",
|
||||
"jwks_uri": "https://auth.example.com/.well-known/jwks.json",
|
||||
"grant_types_supported": ["authorization_code", "refresh_token"],
|
||||
"response_types_supported": ["code"],
|
||||
"scopes_supported": ["openid", "profile", "email", "groups"],
|
||||
"token_endpoint_auth_methods_supported": ["client_secret_post", "client_secret_basic"],
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing Your Implementation
|
||||
|
||||
### Test 1: Initial Token Exchange
|
||||
```bash
|
||||
# Get authorization code (manual - visit in browser)
|
||||
# Then exchange for tokens:
|
||||
|
||||
curl -X POST https://auth.example.com/oauth/token \
|
||||
-d "grant_type=authorization_code" \
|
||||
-d "code=YOUR_AUTH_CODE" \
|
||||
-d "redirect_uri=https://yourapp.com/callback" \
|
||||
-d "client_id=YOUR_CLIENT_ID" \
|
||||
-d "client_secret=YOUR_CLIENT_SECRET" \
|
||||
-d "code_verifier=YOUR_CODE_VERIFIER"
|
||||
|
||||
# Response should include refresh_token
|
||||
```
|
||||
|
||||
### Test 2: Token Refresh
|
||||
```bash
|
||||
curl -X POST https://auth.example.com/oauth/token \
|
||||
-d "grant_type=refresh_token" \
|
||||
-d "refresh_token=YOUR_REFRESH_TOKEN" \
|
||||
-d "client_id=YOUR_CLIENT_ID" \
|
||||
-d "client_secret=YOUR_CLIENT_SECRET"
|
||||
|
||||
# Response should include NEW access_token and NEW refresh_token
|
||||
```
|
||||
|
||||
### Test 3: Token Revocation
|
||||
```bash
|
||||
curl -X POST https://auth.example.com/oauth/revoke \
|
||||
-d "token=YOUR_REFRESH_TOKEN" \
|
||||
-d "token_type_hint=refresh_token" \
|
||||
-d "client_id=YOUR_CLIENT_ID" \
|
||||
-d "client_secret=YOUR_CLIENT_SECRET"
|
||||
|
||||
# Should return 200 OK
|
||||
```
|
||||
|
||||
### Test 4: Reuse Detection (Security Test)
|
||||
```bash
|
||||
# 1. Use refresh token to get new tokens
|
||||
curl -X POST ... (as in Test 2)
|
||||
|
||||
# 2. Try to use the OLD refresh token again
|
||||
curl -X POST ... (with OLD refresh_token)
|
||||
|
||||
# Should return error: "invalid_grant" - token has been revoked
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## FAQ
|
||||
|
||||
### Q: How long do refresh tokens last?
|
||||
**A:** By default, 30 days. This is configurable per application (1-90 days).
|
||||
|
||||
### Q: Can I use the same refresh token multiple times?
|
||||
**A:** No. Refresh tokens are **single-use**. After using a refresh token, you get a new one.
|
||||
|
||||
### Q: What happens if my refresh token is stolen?
|
||||
**A:** If someone tries to use a revoked refresh token, all tokens in that family are immediately revoked (token rotation security).
|
||||
|
||||
### Q: Do I need to store the ID token?
|
||||
**A:** Usually no. The ID token is for authentication (verify user identity). You typically decode it, verify it, extract claims, then discard it.
|
||||
|
||||
### Q: Can I refresh an access token before it expires?
|
||||
**A:** Yes! It's recommended to refresh tokens 5-10 minutes before expiration to avoid race conditions.
|
||||
|
||||
### Q: What if my refresh token expires?
|
||||
**A:** User must re-authenticate via the normal OAuth flow (redirect to /oauth/authorize).
|
||||
|
||||
### Q: Can I revoke all of a user's sessions at once?
|
||||
**A:** Yes, but you need to track all refresh tokens per user on your backend, then revoke them all.
|
||||
|
||||
### Q: Are access tokens revocable?
|
||||
**A:** Yes! You can revoke access tokens using the same `/oauth/revoke` endpoint.
|
||||
|
||||
---
|
||||
|
||||
## Migration Guide (From Access Token Only)
|
||||
|
||||
### Before (Access Token Only):
|
||||
```javascript
|
||||
// User logs in
|
||||
const tokens = await exchangeAuthCode(code);
|
||||
localStorage.setItem('access_token', tokens.access_token);
|
||||
|
||||
// After 1 hour -> Token expires -> Redirect to login
|
||||
if (isTokenExpired()) {
|
||||
window.location = '/oauth/authorize';
|
||||
}
|
||||
```
|
||||
|
||||
### After (With Refresh Tokens):
|
||||
```javascript
|
||||
// User logs in
|
||||
const tokens = await exchangeAuthCode(code);
|
||||
sessionStorage.setItem('access_token', tokens.access_token);
|
||||
secureStorage.set('refresh_token', tokens.refresh_token); // Encrypted
|
||||
|
||||
// After 1 hour -> Refresh silently
|
||||
if (isTokenExpired()) {
|
||||
const newTokens = await refreshAccessToken();
|
||||
sessionStorage.setItem('access_token', newTokens.access_token);
|
||||
secureStorage.set('refresh_token', newTokens.refresh_token);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- **RFC 6749 (OAuth 2.0):** https://datatracker.ietf.org/doc/html/rfc6749
|
||||
- **RFC 7009 (Token Revocation):** https://datatracker.ietf.org/doc/html/rfc7009
|
||||
- **OIDC Core Spec:** https://openid.net/specs/openid-connect-core-1_0.html
|
||||
- **OAuth 2.0 Security Best Practices:** https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions about refresh token implementation, contact your Clinch administrator or check the application documentation.
|
||||
|
||||
**Version:** 1.0
|
||||
**Last Updated:** November 2025
|
||||
913
docs/rodauth-oauth-analysis.md
Normal file
913
docs/rodauth-oauth-analysis.md
Normal file
@@ -0,0 +1,913 @@
|
||||
# Rodauth-OAuth Analysis: Comprehensive Comparison with Clinch's Custom Implementation
|
||||
|
||||
## Executive Summary
|
||||
|
||||
**Rodauth-OAuth** is a production-ready Ruby gem that implements the OAuth 2.0 framework and OpenID Connect on top of the `rodauth` authentication library. It's architected as a modular feature-based system that integrates with Roda (a routing library) and provides extensive OAuth/OIDC capabilities.
|
||||
|
||||
Your current Clinch implementation is a **custom, minimalist Rails-based OIDC provider** focusing on the authorization code grant with PKCE support. Switching to rodauth-oauth would provide significantly more features and standards compliance but requires architectural changes.
|
||||
|
||||
---
|
||||
|
||||
## 1. What Rodauth-OAuth Is
|
||||
|
||||
### Core Identity
|
||||
- **Type**: Ruby gem providing OAuth 2.0 & OpenID Connect implementation
|
||||
- **Framework**: Built on top of `rodauth` (a dedicated authentication library)
|
||||
- **Web Framework**: Designed for Roda framework (lightweight, routing-focused)
|
||||
- **Rails Support**: Available via `rodauth-rails` wrapper
|
||||
- **Maturity**: Production-ready, OpenID-Certified for multiple profiles
|
||||
- **Author**: Tiago Cardoso (tiago.cardoso@gmail.com)
|
||||
- **License**: Apache 2.0
|
||||
|
||||
### Architecture Philosophy
|
||||
- **Feature-based**: Modular "features" that can be enabled/disabled
|
||||
- **Database-agnostic**: Uses Sequel ORM, works with any SQL database
|
||||
- **Highly configurable**: Override methods to customize behavior
|
||||
- **Standards-focused**: Implements RFCs and OpenID specs strictly
|
||||
|
||||
---
|
||||
|
||||
## 2. File Structure and Organization
|
||||
|
||||
### Directory Layout in `/tmp/rodauth-oauth`
|
||||
|
||||
```
|
||||
rodauth-oauth/
|
||||
├── lib/
|
||||
│ └── rodauth/
|
||||
│ ├── oauth.rb # Main module entry point
|
||||
│ ├── oauth/
|
||||
│ │ ├── version.rb
|
||||
│ │ ├── database_extensions.rb
|
||||
│ │ ├── http_extensions.rb
|
||||
│ │ ├── jwe_extensions.rb
|
||||
│ │ └── ttl_store.rb
|
||||
│ └── features/ # 34 feature files!
|
||||
│ ├── oauth_base.rb # Foundation
|
||||
│ ├── oauth_authorization_code_grant.rb
|
||||
│ ├── oauth_pkce.rb
|
||||
│ ├── oauth_jwt*.rb # JWT support (5 files)
|
||||
│ ├── oidc.rb # OpenID Core
|
||||
│ ├── oidc_*logout.rb # Logout flows (3 files)
|
||||
│ ├── oauth_client_credentials_grant.rb
|
||||
│ ├── oauth_device_code_grant.rb
|
||||
│ ├── oauth_token_revocation.rb
|
||||
│ ├── oauth_token_introspection.rb
|
||||
│ ├── oauth_dynamic_client_registration.rb
|
||||
│ ├── oauth_dpop.rb # DPoP support
|
||||
│ ├── oauth_tls_client_auth.rb
|
||||
│ ├── oauth_pushed_authorization_request.rb
|
||||
│ ├── oauth_assertion_base.rb
|
||||
│ └── ... (more features)
|
||||
├── test/
|
||||
│ ├── migrate/ # Database migrations
|
||||
│ │ ├── 001_accounts.rb
|
||||
│ │ ├── 003_oauth_applications.rb
|
||||
│ │ ├── 004_oauth_grants.rb
|
||||
│ │ ├── 005_pushed_requests.rb
|
||||
│ │ ├── 006_saml_settings.rb
|
||||
│ │ └── 007_dpop_proofs.rb
|
||||
│ └── [multiple test directories with hundreds of tests]
|
||||
├── examples/ # Full working examples
|
||||
│ ├── authorization_server/
|
||||
│ ├── oidc/
|
||||
│ ├── jwt/
|
||||
│ ├── device_grant/
|
||||
│ ├── saml_assertion/
|
||||
│ └── mtls/
|
||||
├── templates/ # HTML/ERB templates
|
||||
├── locales/ # i18n translations
|
||||
├── doc/
|
||||
└── [Gemfile, README, MIGRATION-GUIDE, etc.]
|
||||
```
|
||||
|
||||
### Feature Count: 34 Features!
|
||||
|
||||
The gem is completely modular. Each feature can be independently enabled:
|
||||
|
||||
**Core OAuth Features:**
|
||||
- `oauth_base` - Foundation
|
||||
- `oauth_authorization_code_grant` - Authorization Code Flow
|
||||
- `oauth_implicit_grant` - Implicit Flow
|
||||
- `oauth_client_credentials_grant` - Client Credentials Flow
|
||||
- `oauth_device_code_grant` - Device Code Flow
|
||||
|
||||
**Token Management:**
|
||||
- `oauth_token_revocation` - RFC 7009
|
||||
- `oauth_token_introspection` - RFC 7662
|
||||
- `oauth_refresh_token` - Refresh tokens
|
||||
|
||||
**Security & Advanced:**
|
||||
- `oauth_pkce` - RFC 7636 (what Clinch is using!)
|
||||
- `oauth_jwt` - JWT Access Tokens
|
||||
- `oauth_jwt_bearer_grant` - RFC 7523
|
||||
- `oauth_saml_bearer_grant` - RFC 7522
|
||||
- `oauth_tls_client_auth` - Mutual TLS
|
||||
- `oauth_dpop` - Demonstrating Proof-of-Possession
|
||||
- `oauth_jwt_secured_authorization_request` - Request Objects
|
||||
- `oauth_resource_indicators` - RFC 8707
|
||||
- `oauth_pushed_authorization_request` - RFC 9126
|
||||
|
||||
**OpenID Connect:**
|
||||
- `oidc` - Core OpenID Connect
|
||||
- `oidc_session_management` - Session Management
|
||||
- `oidc_rp_initiated_logout` - RP-Initiated Logout
|
||||
- `oidc_frontchannel_logout` - Front-Channel Logout
|
||||
- `oidc_backchannel_logout` - Back-Channel Logout
|
||||
- `oidc_dynamic_client_registration` - Dynamic Registration
|
||||
- `oidc_self_issued` - Self-Issued Provider
|
||||
|
||||
**Management & Discovery:**
|
||||
- `oauth_application_management` - Client app dashboard
|
||||
- `oauth_grant_management` - Grant management dashboard
|
||||
- `oauth_dynamic_client_registration` - RFC 7591/7592
|
||||
- `oauth_jwt_jwks` - JWKS endpoint
|
||||
|
||||
---
|
||||
|
||||
## 3. OIDC/OAuth Features Provided
|
||||
|
||||
### Grant Types Supported (15 types!)
|
||||
|
||||
| Grant Type | Status | RFC/Spec |
|
||||
|-----------|--------|----------|
|
||||
| Authorization Code | Yes | RFC 6749 |
|
||||
| Implicit | Optional | RFC 6749 |
|
||||
| Client Credentials | Optional | RFC 6749 |
|
||||
| Device Code | Optional | RFC 8628 |
|
||||
| Refresh Token | Yes | RFC 6749 |
|
||||
| JWT Bearer | Optional | RFC 7523 |
|
||||
| SAML Bearer | Optional | RFC 7522 |
|
||||
|
||||
### Response Types & Modes
|
||||
|
||||
**Response Types:**
|
||||
- `code` (Authorization Code) - Default
|
||||
- `id_token` (OIDC Implicit) - Optional
|
||||
- `token` (Implicit) - Optional
|
||||
- `id_token token` (Hybrid) - Optional
|
||||
- `code id_token` (Hybrid) - Optional
|
||||
- `code token` (Hybrid) - Optional
|
||||
- `code id_token token` (Hybrid) - Optional
|
||||
|
||||
**Response Modes:**
|
||||
- `query` (URL parameters)
|
||||
- `fragment` (URL fragment)
|
||||
- `form_post` (HTML form)
|
||||
- `jwt` (JWT-based response)
|
||||
|
||||
### OpenID Connect Features
|
||||
|
||||
✓ **Certified for:**
|
||||
- Basic OP (OpenID Provider)
|
||||
- Implicit OP
|
||||
- Hybrid OP
|
||||
- Config OP (Discovery)
|
||||
- Dynamic OP (Dynamic Client Registration)
|
||||
- Form Post OP
|
||||
- 3rd Party-Init OP
|
||||
- Session Management OP
|
||||
- RP-Initiated Logout OP
|
||||
- Front-Channel Logout OP
|
||||
- Back-Channel Logout OP
|
||||
|
||||
✓ **Standard Claims Support:**
|
||||
- `openid`, `email`, `profile`, `address`, `phone` scopes
|
||||
- Automatic claim mapping per OpenID spec
|
||||
- Custom claims via extension
|
||||
|
||||
✓ **Token Features:**
|
||||
- JWT ID Tokens
|
||||
- JWT Access Tokens
|
||||
- Encrypted JWTs (JWE support)
|
||||
- HMAC-SHA256 signing
|
||||
- RSA/EC signing
|
||||
- Custom token formats
|
||||
|
||||
### Security Features
|
||||
|
||||
| Feature | Details |
|
||||
|---------|---------|
|
||||
| PKCE | RFC 7636 - Proof Key for Public Clients |
|
||||
| Token Hashing | Bcrypt-based token storage (plain text optional) |
|
||||
| DPoP | RFC 9449 - Demonstrating Proof-of-Possession |
|
||||
| TLS Client Auth | RFC 8705 - Mutual TLS authentication |
|
||||
| Request Objects | JWT-signed/encrypted authorization requests |
|
||||
| Pushed Auth Requests | RFC 9126 - Pushed Authorization Requests |
|
||||
| Token Introspection | RFC 7662 - Token validation without DB lookup |
|
||||
| Token Revocation | RFC 7009 - Revoke tokens on demand |
|
||||
|
||||
### Scopes & Authorization
|
||||
|
||||
- Configurable scope list per application
|
||||
- Offline access support (refresh tokens)
|
||||
- Scope-based access control
|
||||
- Custom scope handlers
|
||||
- Consent UI for user authorization
|
||||
|
||||
---
|
||||
|
||||
## 4. Architecture: How It Works
|
||||
|
||||
### As a Plugin System
|
||||
|
||||
Rodauth-OAuth integrates with Roda as a **plugin**:
|
||||
|
||||
```ruby
|
||||
# This is how you configure it
|
||||
class AuthServer < Roda
|
||||
plugin :rodauth do
|
||||
db database_connection
|
||||
|
||||
# Enable features
|
||||
enable :login, :logout, :create_account, :oidc, :oidc_session_management,
|
||||
:oauth_pkce, :oauth_authorization_code_grant
|
||||
|
||||
# Configure
|
||||
oauth_application_scopes %w[openid email profile]
|
||||
oauth_require_pkce true
|
||||
hmac_secret "SECRET"
|
||||
|
||||
# Customize with blocks
|
||||
oauth_jwt_keys("RS256" => [private_key])
|
||||
oauth_jwt_public_keys("RS256" => [public_key])
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
### Request Flow Architecture
|
||||
|
||||
```
|
||||
1. Authorization Request
|
||||
↓
|
||||
rodauth validates params
|
||||
↓
|
||||
(if not auth'd) user logs in via rodauth
|
||||
↓
|
||||
(if first use) consent page rendered
|
||||
↓
|
||||
create oauth_grant (code, nonce, PKCE challenge, etc.)
|
||||
↓
|
||||
redirect with auth code
|
||||
|
||||
2. Token Exchange
|
||||
↓
|
||||
rodauth validates client (Basic/POST auth)
|
||||
↓
|
||||
validates code, redirect_uri, PKCE verifier
|
||||
↓
|
||||
creates access token (plain or JWT)
|
||||
↓
|
||||
creates refresh token
|
||||
↓
|
||||
returns JSON with tokens
|
||||
|
||||
3. UserInfo
|
||||
↓
|
||||
validate access token
|
||||
↓
|
||||
lookup grant/account
|
||||
↓
|
||||
return claims as JSON
|
||||
```
|
||||
|
||||
### Feature Composition
|
||||
|
||||
Features depend on each other. For example:
|
||||
- `oidc` depends on: `active_sessions`, `oauth_jwt`, `oauth_jwt_jwks`, `oauth_authorization_code_grant`, `oauth_implicit_grant`
|
||||
- `oauth_pkce` depends on: `oauth_authorization_code_grant`
|
||||
- `oidc_rp_initiated_logout` depends on: `oidc`
|
||||
|
||||
This is a **strong dependency injection pattern**.
|
||||
|
||||
---
|
||||
|
||||
## 5. Database Schema Requirements
|
||||
|
||||
### Rodauth-OAuth Tables
|
||||
|
||||
#### `accounts` table (from rodauth)
|
||||
```sql
|
||||
CREATE TABLE accounts (
|
||||
id INTEGER PRIMARY KEY,
|
||||
status_id INTEGER DEFAULT 1, -- unverified/verified/closed
|
||||
email VARCHAR UNIQUE NOT NULL,
|
||||
-- password-related columns (added by rodauth features)
|
||||
password_hash VARCHAR,
|
||||
-- other rodauth-managed columns
|
||||
);
|
||||
```
|
||||
|
||||
#### `oauth_applications` table (75+ columns!)
|
||||
```sql
|
||||
CREATE TABLE oauth_applications (
|
||||
id INTEGER PRIMARY KEY,
|
||||
account_id INTEGER FOREIGN KEY,
|
||||
|
||||
-- Basic info
|
||||
name VARCHAR NOT NULL,
|
||||
description VARCHAR,
|
||||
homepage_url VARCHAR,
|
||||
logo_uri VARCHAR,
|
||||
tos_uri VARCHAR,
|
||||
policy_uri VARCHAR,
|
||||
|
||||
-- OAuth credentials
|
||||
client_id VARCHAR UNIQUE NOT NULL,
|
||||
client_secret VARCHAR UNIQUE NOT NULL,
|
||||
registration_access_token VARCHAR,
|
||||
|
||||
-- OAuth config
|
||||
redirect_uri VARCHAR NOT NULL,
|
||||
scopes VARCHAR NOT NULL,
|
||||
token_endpoint_auth_method VARCHAR,
|
||||
grant_types VARCHAR,
|
||||
response_types VARCHAR,
|
||||
response_modes VARCHAR,
|
||||
|
||||
-- JWT/JWKS
|
||||
jwks_uri VARCHAR,
|
||||
jwks TEXT,
|
||||
jwt_public_key TEXT,
|
||||
|
||||
-- OIDC-specific
|
||||
sector_identifier_uri VARCHAR,
|
||||
application_type VARCHAR,
|
||||
initiate_login_uri VARCHAR,
|
||||
subject_type VARCHAR,
|
||||
|
||||
-- Token encryption algorithms
|
||||
id_token_signed_response_alg VARCHAR,
|
||||
id_token_encrypted_response_alg VARCHAR,
|
||||
id_token_encrypted_response_enc VARCHAR,
|
||||
userinfo_signed_response_alg VARCHAR,
|
||||
userinfo_encrypted_response_alg VARCHAR,
|
||||
userinfo_encrypted_response_enc VARCHAR,
|
||||
|
||||
-- Request object handling
|
||||
request_object_signing_alg VARCHAR,
|
||||
request_object_encryption_alg VARCHAR,
|
||||
request_object_encryption_enc VARCHAR,
|
||||
request_uris VARCHAR,
|
||||
require_signed_request_object BOOLEAN,
|
||||
|
||||
-- PAR (Pushed Auth Requests)
|
||||
require_pushed_authorization_requests BOOLEAN DEFAULT FALSE,
|
||||
|
||||
-- DPoP
|
||||
dpop_bound_access_tokens BOOLEAN DEFAULT FALSE,
|
||||
|
||||
-- TLS Client Auth
|
||||
tls_client_auth_subject_dn VARCHAR,
|
||||
tls_client_auth_san_dns VARCHAR,
|
||||
tls_client_auth_san_uri VARCHAR,
|
||||
tls_client_auth_san_ip VARCHAR,
|
||||
tls_client_auth_san_email VARCHAR,
|
||||
tls_client_certificate_bound_access_tokens BOOLEAN DEFAULT FALSE,
|
||||
|
||||
-- Logout URIs
|
||||
post_logout_redirect_uris VARCHAR,
|
||||
frontchannel_logout_uri VARCHAR,
|
||||
frontchannel_logout_session_required BOOLEAN DEFAULT FALSE,
|
||||
backchannel_logout_uri VARCHAR,
|
||||
backchannel_logout_session_required BOOLEAN DEFAULT FALSE,
|
||||
|
||||
-- Response encryption
|
||||
authorization_signed_response_alg VARCHAR,
|
||||
authorization_encrypted_response_alg VARCHAR,
|
||||
authorization_encrypted_response_enc VARCHAR,
|
||||
|
||||
contact_info VARCHAR,
|
||||
software_id VARCHAR,
|
||||
software_version VARCHAR
|
||||
);
|
||||
```
|
||||
|
||||
#### `oauth_grants` table (everything in one table!)
|
||||
```sql
|
||||
CREATE TABLE oauth_grants (
|
||||
id INTEGER PRIMARY KEY,
|
||||
account_id INTEGER FOREIGN KEY, -- nullable for client credentials
|
||||
oauth_application_id INTEGER FOREIGN KEY,
|
||||
sub_account_id INTEGER, -- for context-based ownership
|
||||
|
||||
type VARCHAR, -- 'authorization_code', 'refresh_token', etc.
|
||||
|
||||
-- Authorization code flow
|
||||
code VARCHAR UNIQUE (per app),
|
||||
redirect_uri VARCHAR,
|
||||
|
||||
-- Tokens (stored hashed or plain)
|
||||
token VARCHAR UNIQUE,
|
||||
token_hash VARCHAR UNIQUE,
|
||||
refresh_token VARCHAR UNIQUE,
|
||||
refresh_token_hash VARCHAR UNIQUE,
|
||||
|
||||
-- Expiry
|
||||
expires_in TIMESTAMP NOT NULL,
|
||||
revoked_at TIMESTAMP,
|
||||
|
||||
-- Scopes
|
||||
scopes VARCHAR NOT NULL,
|
||||
access_type VARCHAR DEFAULT 'offline', -- 'offline' or 'online'
|
||||
|
||||
-- PKCE
|
||||
code_challenge VARCHAR,
|
||||
code_challenge_method VARCHAR, -- 'plain' or 'S256'
|
||||
|
||||
-- Device Code Grant
|
||||
user_code VARCHAR UNIQUE,
|
||||
last_polled_at TIMESTAMP,
|
||||
|
||||
-- TLS Client Auth
|
||||
certificate_thumbprint VARCHAR,
|
||||
|
||||
-- Resource Indicators
|
||||
resource VARCHAR,
|
||||
|
||||
-- OpenID Connect
|
||||
nonce VARCHAR,
|
||||
acr VARCHAR, -- Authentication Context Class
|
||||
claims_locales VARCHAR,
|
||||
claims VARCHAR, -- custom OIDC claims
|
||||
|
||||
-- DPoP
|
||||
dpop_jkt VARCHAR -- DPoP key thumbprint
|
||||
);
|
||||
```
|
||||
|
||||
#### Optional Tables for Advanced Features
|
||||
|
||||
```sql
|
||||
-- For Pushed Authorization Requests
|
||||
CREATE TABLE oauth_pushed_requests (
|
||||
request_uri VARCHAR UNIQUE PRIMARY KEY,
|
||||
oauth_application_id INTEGER FOREIGN KEY,
|
||||
params TEXT, -- JSON params
|
||||
created_at TIMESTAMP
|
||||
);
|
||||
|
||||
-- For SAML Assertion Grant
|
||||
CREATE TABLE oauth_saml_settings (
|
||||
id INTEGER PRIMARY KEY,
|
||||
oauth_application_id INTEGER FOREIGN KEY,
|
||||
idp_url VARCHAR,
|
||||
certificate TEXT,
|
||||
-- ...
|
||||
);
|
||||
|
||||
-- For DPoP
|
||||
CREATE TABLE oauth_dpop_proofs (
|
||||
id INTEGER PRIMARY KEY,
|
||||
oauth_grant_id INTEGER FOREIGN KEY,
|
||||
jti VARCHAR UNIQUE,
|
||||
created_at TIMESTAMP
|
||||
);
|
||||
```
|
||||
|
||||
### Key Differences from Your Implementation
|
||||
|
||||
| Aspect | Your Implementation | Rodauth-OAuth |
|
||||
|--------|-------------------|----------------|
|
||||
| Authorization Codes | Separate table | In oauth_grants |
|
||||
| Access Tokens | Separate table | In oauth_grants |
|
||||
| Refresh Tokens | Not implemented | In oauth_grants |
|
||||
| Token Hashing | Not done | Bcrypt (default) |
|
||||
| Applications | Basic (name, client_id, secret) | 75+ columns for full spec |
|
||||
| PKCE | Simple columns | Built-in feature |
|
||||
| Account Data | In users table | In accounts table |
|
||||
| Session Management | Session model | Rodauth's account_active_session_keys |
|
||||
| User Consent | OidcUserConsent table | In memory or via hooks |
|
||||
|
||||
---
|
||||
|
||||
## 6. Integration Points with Rails
|
||||
|
||||
### Via Rodauth-Rails Wrapper
|
||||
|
||||
Rodauth-OAuth can be used in Rails through the `rodauth-rails` gem:
|
||||
|
||||
```bash
|
||||
# Install generator
|
||||
gem 'rodauth-rails'
|
||||
bundle install
|
||||
rails generate rodauth:install
|
||||
rails generate rodauth:oauth:install # Generates OIDC tables/migrations
|
||||
rails generate rodauth:oauth:views # Generates templates
|
||||
```
|
||||
|
||||
### Generated Components
|
||||
|
||||
1. **Migration**: `db/migrate/*_create_rodauth_oauth.rb`
|
||||
- Creates all OAuth tables
|
||||
- Customizable column names via config
|
||||
|
||||
2. **Models**: `app/models/`
|
||||
- `RodauthApp` (configuration)
|
||||
- `OauthApplication` (client app)
|
||||
- `OauthGrant` (grants/tokens)
|
||||
- Customizable!
|
||||
|
||||
3. **Views**: `app/views/rodauth/`
|
||||
- Authorization consent form
|
||||
- Application management dashboard
|
||||
- Grant management dashboard
|
||||
|
||||
4. **Lib**: `lib/rodauth_app.rb`
|
||||
- Main rodauth configuration
|
||||
|
||||
### Rails Controller Integration
|
||||
|
||||
```ruby
|
||||
class BooksController < ApplicationController
|
||||
before_action :require_oauth_authorization, only: %i[create update]
|
||||
before_action :require_oauth_authorization_scopes, only: %i[create update]
|
||||
|
||||
private
|
||||
|
||||
def require_oauth_authorization(scope = "books.read")
|
||||
rodauth.require_oauth_authorization(scope)
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
Or for route protection:
|
||||
|
||||
```ruby
|
||||
# config/routes.rb
|
||||
namespace :api do
|
||||
resources :books, only: [:index] # protected by rodauth
|
||||
end
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Architectural Comparison
|
||||
|
||||
### Your Custom Implementation
|
||||
|
||||
**Pros:**
|
||||
- Simple, easy to understand
|
||||
- Minimal dependencies (just JWT, OpenSSL)
|
||||
- Lightweight database (small tables)
|
||||
- Direct Rails integration
|
||||
- Minimal features = less surface area
|
||||
|
||||
**Cons:**
|
||||
- Only supports Authorization Code + PKCE
|
||||
- No refresh tokens
|
||||
- No token revocation/introspection
|
||||
- No client credentials grant
|
||||
- No JWT access tokens
|
||||
- Manual consent management
|
||||
- Not standards-compliant (missing many OIDC features)
|
||||
- Will need continuous custom development
|
||||
|
||||
**Architecture:**
|
||||
```
|
||||
Rails Controller
|
||||
↓
|
||||
OidcController (450 lines)
|
||||
↓
|
||||
OidcAuthorizationCode Model
|
||||
OidcAccessToken Model
|
||||
OidcUserConsent Model
|
||||
↓
|
||||
Database
|
||||
```
|
||||
|
||||
### Rodauth-OAuth Implementation
|
||||
|
||||
**Pros:**
|
||||
- 34 built-in features
|
||||
- OpenID-Certified
|
||||
- Production-tested
|
||||
- Highly configurable
|
||||
- Comprehensive token management
|
||||
- Standards-compliant (RFCs & OpenID specs)
|
||||
- Strong test coverage (hundreds of tests)
|
||||
- Active maintenance
|
||||
|
||||
**Cons:**
|
||||
- More complex (needs Roda/Rodauth knowledge)
|
||||
- Larger codebase to learn
|
||||
- Rails integration via wrapper (extra layer)
|
||||
- Different paradigm (Roda vs Rails)
|
||||
- More database columns to manage
|
||||
|
||||
**Architecture:**
|
||||
```
|
||||
Roda App
|
||||
↓
|
||||
Rodauth Plugin (configurable)
|
||||
├── oauth_base (foundation)
|
||||
├── oauth_authorization_code_grant
|
||||
├── oauth_pkce
|
||||
├── oauth_jwt
|
||||
├── oidc (all OpenID features)
|
||||
├── [other optional features]
|
||||
↓
|
||||
Sequel ORM
|
||||
↓
|
||||
Database (flexible schema)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Feature Comparison Matrix
|
||||
|
||||
| Feature | Your Impl | Rodauth-OAuth | Notes |
|
||||
|---------|-----------|---------------|-------|
|
||||
| **Authorization Code** | ✓ | ✓ | Both support |
|
||||
| **PKCE** | ✓ | ✓ | Both support |
|
||||
| **Refresh Tokens** | ✗ | ✓ | You'd need to add |
|
||||
| **Implicit Flow** | ✗ | ✓ Optional | Legacy, not recommended |
|
||||
| **Client Credentials** | ✗ | ✓ Optional | Machine-to-machine |
|
||||
| **Device Code** | ✗ | ✓ Optional | IoT devices |
|
||||
| **JWT Bearer Grant** | ✗ | ✓ Optional | Service accounts |
|
||||
| **SAML Bearer Grant** | ✗ | ✓ Optional | Enterprise SAML |
|
||||
| **JWT Access Tokens** | ✗ | ✓ Optional | Stateless tokens |
|
||||
| **Token Revocation** | ✗ | ✓ | RFC 7009 |
|
||||
| **Token Introspection** | ✗ | ✓ | RFC 7662 |
|
||||
| **Pushed Auth Requests** | ✗ | ✓ Optional | RFC 9126 |
|
||||
| **DPoP** | ✗ | ✓ Optional | RFC 9449 |
|
||||
| **TLS Client Auth** | ✗ | ✓ Optional | RFC 8705 |
|
||||
| **OpenID Connect** | ✓ Basic | ✓ Full | Yours is minimal |
|
||||
| **ID Tokens** | ✓ | ✓ | Both support |
|
||||
| **UserInfo Endpoint** | ✓ | ✓ | Both support |
|
||||
| **Discovery** | ✓ | ✓ | Both support |
|
||||
| **Session Management** | ✗ | ✓ Optional | Check session iframe |
|
||||
| **RP-Init Logout** | ✓ | ✓ | Both support |
|
||||
| **Front-Channel Logout** | ✗ | ✓ | Iframe-based |
|
||||
| **Back-Channel Logout** | ✗ | ✓ | Server-to-server |
|
||||
| **Dynamic Client Reg** | ✗ | ✓ Optional | RFC 7591/7592 |
|
||||
| **Token Hashing** | ✗ | ✓ | Security best practice |
|
||||
| **Scopes** | ✓ | ✓ | Both support |
|
||||
| **Custom Claims** | ✓ Manual | ✓ Built-in | Yours via JWT service |
|
||||
| **Consent UI** | ✓ | ✓ | Both support |
|
||||
| **Client App Dashboard** | ✗ | ✓ Optional | Built-in |
|
||||
| **Grant Management Dashboard** | ✗ | ✓ Optional | Built-in |
|
||||
|
||||
---
|
||||
|
||||
## 9. Integration Complexity Analysis
|
||||
|
||||
### Switching to Rodauth-OAuth
|
||||
|
||||
#### Medium Complexity (Not Trivial, but Doable)
|
||||
|
||||
**What you'd need to do:**
|
||||
|
||||
1. **Learn Roda + Rodauth**
|
||||
- Move from pure Rails to Roda-based architecture
|
||||
- Understand rodauth feature system
|
||||
- Time: 1-2 weeks for Rails developers
|
||||
|
||||
2. **Migrate Database Schema**
|
||||
- Consolidate tables: authorization codes + access tokens → oauth_grants
|
||||
- Rename columns to match rodauth conventions
|
||||
- Add many new columns for feature support
|
||||
- Migration script needed: ~100-300 lines
|
||||
- Time: 1 week development + testing
|
||||
|
||||
3. **Replace Your OIDC Code**
|
||||
- Replace your 450-line OidcController
|
||||
- Remove your 3 model files
|
||||
- Keep your OidcJwtService (mostly compatible)
|
||||
- Add rodauth configuration
|
||||
- Time: 1-2 weeks
|
||||
|
||||
4. **Update Application/Client Model**
|
||||
- Expand `Application` model properties
|
||||
- Support all OAuth scopes, grant types, response types
|
||||
- Time: 3-5 days
|
||||
|
||||
5. **Create Migrations from Template**
|
||||
- Use rodauth-oauth migration templates
|
||||
- Customize for your database
|
||||
- Time: 2-3 days
|
||||
|
||||
6. **Testing**
|
||||
- Write integration tests
|
||||
- Verify all OAuth flows still work
|
||||
- Check token validation logic
|
||||
- Time: 2-3 weeks
|
||||
|
||||
**Total Effort:** 4-8 weeks for experienced team
|
||||
|
||||
### Keeping Your Implementation (Custom Path)
|
||||
|
||||
#### What You'd Need to Add
|
||||
|
||||
To reach feature parity with rodauth-oauth (for common use cases):
|
||||
|
||||
1. **Refresh Token Support** (1-2 weeks)
|
||||
- Database schema
|
||||
- Token refresh endpoint
|
||||
- Token validation logic
|
||||
|
||||
2. **Token Revocation** (1 week)
|
||||
- Revocation endpoint
|
||||
- Token blacklist/invalidation
|
||||
|
||||
3. **Token Introspection** (1 week)
|
||||
- Introspection endpoint
|
||||
- Token validation without DB lookup
|
||||
|
||||
4. **Client Credentials Grant** (2 weeks)
|
||||
- Endpoint logic
|
||||
- Client authentication
|
||||
- Token generation for apps
|
||||
|
||||
5. **Improved Security** (ongoing)
|
||||
- Token hashing (bcrypt)
|
||||
- Rate limiting
|
||||
- Additional validation
|
||||
|
||||
6. **Advanced OIDC Features**
|
||||
- Session Management
|
||||
- Logout endpoints (front/back-channel)
|
||||
- Dynamic client registration
|
||||
- Device code flow
|
||||
|
||||
**Total Effort:** 2-3 months ongoing
|
||||
|
||||
---
|
||||
|
||||
## 10. Key Findings & Recommendations
|
||||
|
||||
### What Rodauth-OAuth Does Better
|
||||
|
||||
1. **Standards Compliance**
|
||||
- Certified for 11 OpenID Connect profiles
|
||||
- Implements 20+ RFCs and specs
|
||||
- Regular spec updates
|
||||
|
||||
2. **Security**
|
||||
- Token hashing by default
|
||||
- DPoP support (token binding)
|
||||
- TLS client auth
|
||||
- Proper scope enforcement
|
||||
|
||||
3. **Features**
|
||||
- 34 optional features (you get what you need)
|
||||
- No bloat - only enable what you use
|
||||
- Mature refresh token handling
|
||||
|
||||
4. **Production Readiness**
|
||||
- Thousands of test cases
|
||||
- Open source (auditable)
|
||||
- Active maintenance
|
||||
- Real-world deployments
|
||||
|
||||
5. **Flexibility**
|
||||
- Works with any SQL database
|
||||
- Highly configurable column names
|
||||
- Custom behavior via overrides
|
||||
- Multiple app types support
|
||||
|
||||
### What Your Implementation Does Better
|
||||
|
||||
1. **Simplicity**
|
||||
- Fewer dependencies
|
||||
- Smaller codebase
|
||||
- Easier to reason about
|
||||
|
||||
2. **Rails Integration**
|
||||
- Direct Rails ActiveRecord
|
||||
- No Roda learning curve
|
||||
- Familiar patterns
|
||||
|
||||
3. **Control**
|
||||
- Full control of every line
|
||||
- No surprises
|
||||
- Easy to debug
|
||||
|
||||
### Recommendation
|
||||
|
||||
**Use Rodauth-OAuth IF:**
|
||||
- You need a production OIDC/OAuth provider
|
||||
- You want standards compliance
|
||||
- You plan to support multiple grant types
|
||||
- You need token revocation/introspection
|
||||
- You want a maintained codebase
|
||||
|
||||
**Keep Your Custom Implementation IF:**
|
||||
- Authorization Code + PKCE only is sufficient
|
||||
- You're avoiding Roda/Rodauth learning curve
|
||||
- Your org standardizes on Rails patterns
|
||||
- You have time to add features incrementally
|
||||
- You need maximum control and simplicity
|
||||
|
||||
**Hybrid Approach:**
|
||||
- Use rodauth-oauth for OIDC/OAuth server components
|
||||
- Keep your Rails app for other features
|
||||
- They can coexist (separate services)
|
||||
|
||||
---
|
||||
|
||||
## 11. Migration Path (If You Decide to Switch)
|
||||
|
||||
### Phase 1: Preparation (Week 1-2)
|
||||
- Set up separate Roda app with rodauth-oauth
|
||||
- Run alongside your existing service
|
||||
- Parallel user testing
|
||||
|
||||
### Phase 2: Data Migration (Week 2-3)
|
||||
- Create migration script for oauth_grants table
|
||||
- Backfill existing auth codes and tokens
|
||||
- Verify data integrity
|
||||
|
||||
### Phase 3: Gradual Cutover (Week 4-6)
|
||||
- Direct some OAuth clients to new server
|
||||
- Monitor for issues
|
||||
- Swap over when confident
|
||||
|
||||
### Phase 4: Cleanup (Week 6+)
|
||||
- Remove custom OIDC code
|
||||
- Decommission old tables
|
||||
- Document new architecture
|
||||
|
||||
---
|
||||
|
||||
## 12. Code Examples
|
||||
|
||||
### Rodauth-OAuth: Minimal Setup
|
||||
|
||||
```ruby
|
||||
# Gemfile
|
||||
gem 'roda'
|
||||
gem 'rodauth-oauth'
|
||||
gem 'sequel'
|
||||
|
||||
# lib/auth_server.rb
|
||||
class AuthServer < Roda
|
||||
plugin :render, views: 'views'
|
||||
plugin :sessions, secret: 'SECRET'
|
||||
|
||||
plugin :rodauth do
|
||||
db DB
|
||||
enable :login, :logout, :create_account, :oidc, :oauth_pkce,
|
||||
:oauth_authorization_code_grant, :oauth_token_introspection
|
||||
|
||||
oauth_application_scopes %w[openid email profile]
|
||||
oauth_require_pkce true
|
||||
hmac_secret 'HMAC_SECRET'
|
||||
|
||||
oauth_jwt_keys('RS256' => [private_key])
|
||||
end
|
||||
|
||||
route do |r|
|
||||
r.rodauth # All OAuth routes automatically mounted
|
||||
|
||||
# Your custom routes
|
||||
r.get 'api' do
|
||||
rodauth.require_oauth_authorization('api.read')
|
||||
# return data
|
||||
end
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
### Your Current Approach: Manual
|
||||
|
||||
```ruby
|
||||
# app/controllers/oidc_controller.rb
|
||||
def authorize
|
||||
validate_params
|
||||
find_application
|
||||
check_authentication
|
||||
handle_consent
|
||||
generate_code
|
||||
redirect_with_code
|
||||
end
|
||||
|
||||
def token
|
||||
extract_client_credentials
|
||||
find_application
|
||||
validate_code
|
||||
check_pkce
|
||||
generate_tokens
|
||||
return_json
|
||||
end
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary Table
|
||||
|
||||
| Aspect | Your Implementation | Rodauth-OAuth |
|
||||
|--------|-------------------|----------------|
|
||||
| **Framework** | Rails | Roda |
|
||||
| **Database ORM** | ActiveRecord | Sequel |
|
||||
| **Grant Types** | 1 (Auth Code) | 7+ options |
|
||||
| **Token Types** | Opaque | Opaque or JWT |
|
||||
| **Security Features** | Basic | Advanced (DPoP, MTLS, etc.) |
|
||||
| **OIDC Compliance** | Partial | Full (Certified) |
|
||||
| **Lines of Code** | ~1000 | ~10,000+ |
|
||||
| **Features** | 2-3 | 34 optional |
|
||||
| **Maintenance Burden** | High | Low (OSS) |
|
||||
| **Learning Curve** | Low | Medium (Roda) |
|
||||
| **Production Ready** | Yes | Yes |
|
||||
| **Community** | Just you | Active |
|
||||
|
||||
418
docs/rodauth-oauth-quick-reference.md
Normal file
418
docs/rodauth-oauth-quick-reference.md
Normal file
@@ -0,0 +1,418 @@
|
||||
# Rodauth-OAuth: Quick Reference Guide
|
||||
|
||||
## What Is It?
|
||||
A production-ready Ruby gem implementing OAuth 2.0 and OpenID Connect. Think of it as a complete, standards-certified OAuth/OIDC server library for Ruby apps.
|
||||
|
||||
## Key Stats
|
||||
- **Framework**: Roda (not Rails, but works with Rails via wrapper)
|
||||
- **Features**: 34 modular features you can enable/disable
|
||||
- **Certification**: Officially certified for 11 OpenID Connect profiles
|
||||
- **Test Coverage**: Hundreds of tests
|
||||
- **Status**: Production-ready, actively maintained
|
||||
|
||||
## Why Consider It?
|
||||
|
||||
### Advantages Over Your Implementation
|
||||
1. **Complete OAuth/OIDC Implementation**
|
||||
- All major grant types supported
|
||||
- Certified compliance with standards
|
||||
- 20+ RFC implementations
|
||||
|
||||
2. **Security Features**
|
||||
- Token hashing (bcrypt) by default
|
||||
- DPoP support (token binding)
|
||||
- TLS mutual authentication
|
||||
- Proper scope enforcement
|
||||
|
||||
3. **Advanced Token Management**
|
||||
- Refresh tokens (you don't have)
|
||||
- Token revocation
|
||||
- Token introspection
|
||||
- Token rotation policies
|
||||
|
||||
4. **Low Maintenance**
|
||||
- Well-tested codebase
|
||||
- Active community
|
||||
- Regular spec updates
|
||||
- Battle-tested in production
|
||||
|
||||
5. **Extensible**
|
||||
- Highly configurable
|
||||
- Override any behavior you need
|
||||
- Database-agnostic
|
||||
- Works with any SQL DB
|
||||
|
||||
### What Your Implementation Does Better
|
||||
1. **Simplicity** - Fewer lines of code, easier to understand
|
||||
2. **Rails Native** - No need to learn Roda
|
||||
3. **Control** - Full ownership of the codebase
|
||||
4. **Minimal Dependencies** - Just JWT and OpenSSL
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### Your Current Setup
|
||||
```
|
||||
Rails App
|
||||
└─ OidcController (450 lines)
|
||||
├─ /oauth/authorize
|
||||
├─ /oauth/token
|
||||
├─ /oauth/userinfo
|
||||
└─ /logout
|
||||
|
||||
Models:
|
||||
├─ OidcAuthorizationCode
|
||||
├─ OidcAccessToken
|
||||
└─ OidcUserConsent
|
||||
|
||||
Features Supported:
|
||||
├─ Authorization Code Flow ✓
|
||||
├─ PKCE ✓
|
||||
└─ Basic OIDC ✓
|
||||
|
||||
NOT Supported:
|
||||
├─ Refresh Tokens
|
||||
├─ Token Revocation
|
||||
├─ Token Introspection
|
||||
├─ Client Credentials Grant
|
||||
├─ Device Code Flow
|
||||
├─ Session Management
|
||||
├─ Front/Back-Channel Logout
|
||||
└─ Dynamic Client Registration
|
||||
```
|
||||
|
||||
### Rodauth-OAuth Setup
|
||||
```
|
||||
Roda App (web framework)
|
||||
└─ Rodauth Plugin (authentication/authorization)
|
||||
├─ oauth_base (foundation)
|
||||
├─ oauth_authorization_code_grant
|
||||
├─ oauth_pkce
|
||||
├─ oauth_jwt (optional)
|
||||
├─ oidc (OpenID core)
|
||||
├─ oidc_session_management (optional)
|
||||
├─ oidc_rp_initiated_logout (optional)
|
||||
├─ oidc_frontchannel_logout (optional)
|
||||
├─ oidc_backchannel_logout (optional)
|
||||
├─ oauth_token_revocation (optional)
|
||||
├─ oauth_token_introspection (optional)
|
||||
├─ oauth_client_credentials_grant (optional)
|
||||
└─ ... (28+ more optional features)
|
||||
|
||||
Routes Generated Automatically:
|
||||
├─ /.well-known/openid-configuration ✓
|
||||
├─ /.well-known/jwks.json ✓
|
||||
├─ /oauth/authorize ✓
|
||||
├─ /oauth/token ✓
|
||||
├─ /oauth/userinfo ✓
|
||||
├─ /oauth/introspect (optional)
|
||||
├─ /oauth/revoke (optional)
|
||||
└─ /logout ✓
|
||||
```
|
||||
|
||||
## Database Schema Comparison
|
||||
|
||||
### Your Current Tables
|
||||
```
|
||||
oidc_authorization_codes
|
||||
├─ id
|
||||
├─ user_id
|
||||
├─ application_id
|
||||
├─ code (unique)
|
||||
├─ redirect_uri
|
||||
├─ scope
|
||||
├─ nonce
|
||||
├─ code_challenge
|
||||
├─ code_challenge_method
|
||||
├─ used (boolean)
|
||||
├─ expires_at
|
||||
└─ created_at
|
||||
|
||||
oidc_access_tokens
|
||||
├─ id
|
||||
├─ user_id
|
||||
├─ application_id
|
||||
├─ token (unique)
|
||||
├─ scope
|
||||
├─ expires_at
|
||||
└─ created_at
|
||||
|
||||
oidc_user_consents
|
||||
├─ user_id
|
||||
├─ application_id
|
||||
├─ scopes_granted
|
||||
└─ granted_at
|
||||
|
||||
applications
|
||||
├─ id
|
||||
├─ name
|
||||
├─ client_id (unique)
|
||||
├─ client_secret
|
||||
├─ redirect_uris (JSON)
|
||||
├─ app_type
|
||||
└─ ... (few more fields)
|
||||
```
|
||||
|
||||
### Rodauth-OAuth Tables
|
||||
```
|
||||
accounts (from rodauth)
|
||||
├─ id
|
||||
├─ status_id
|
||||
├─ email
|
||||
└─ password_hash
|
||||
|
||||
oauth_applications (75+ columns!)
|
||||
├─ Basic: id, account_id, name, description
|
||||
├─ OAuth: client_id, client_secret, redirect_uri, scopes
|
||||
├─ Config: token_endpoint_auth_method, grant_types, response_types
|
||||
├─ JWT/JWKS: jwks_uri, jwks, jwt_public_key
|
||||
├─ OIDC: subject_type, id_token_signed_response_alg, etc.
|
||||
├─ PAR: require_pushed_authorization_requests
|
||||
├─ DPoP: dpop_bound_access_tokens
|
||||
├─ TLS: tls_client_auth_* fields
|
||||
└─ Logout: post_logout_redirect_uris, frontchannel_logout_uri, etc.
|
||||
|
||||
oauth_grants (consolidated - replaces your two tables!)
|
||||
├─ id, account_id, oauth_application_id
|
||||
├─ type (authorization_code, refresh_token, etc.)
|
||||
├─ code, token, refresh_token (with hashed versions)
|
||||
├─ expires_in, revoked_at
|
||||
├─ scopes, access_type
|
||||
├─ code_challenge, code_challenge_method (PKCE)
|
||||
├─ user_code, last_polled_at (Device code grant)
|
||||
├─ nonce, acr, claims (OIDC)
|
||||
├─ dpop_jkt (DPoP)
|
||||
└─ certificate_thumbprint, resource (advanced)
|
||||
|
||||
[Optional tables for features you enable]
|
||||
```
|
||||
|
||||
## Feature Comparison Matrix
|
||||
|
||||
| Feature | Your Code | Rodauth-OAuth | Effort to Add* |
|
||||
|---------|-----------|---------------|--------|
|
||||
| Authorization Code Flow | ✓ | ✓ | N/A |
|
||||
| PKCE | ✓ | ✓ | N/A |
|
||||
| Refresh Tokens | ✗ | ✓ | 1-2 weeks |
|
||||
| Token Revocation | ✗ | ✓ | 1 week |
|
||||
| Token Introspection | ✗ | ✓ | 1 week |
|
||||
| Client Credentials Grant | ✗ | ✓ | 2 weeks |
|
||||
| Device Code Flow | ✗ | ✓ | 3 weeks |
|
||||
| JWT Access Tokens | ✗ | ✓ | 1 week |
|
||||
| Session Management | ✗ | ✓ | 2-3 weeks |
|
||||
| Front-Channel Logout | ✗ | ✓ | 1-2 weeks |
|
||||
| Back-Channel Logout | ✗ | ✓ | 2 weeks |
|
||||
| Dynamic Client Reg | ✗ | ✓ | 3-4 weeks |
|
||||
| Token Hashing | ✗ | ✓ | 1 week |
|
||||
|
||||
*Time estimates for adding to your implementation
|
||||
|
||||
## Code Examples
|
||||
|
||||
### Rodauth-OAuth: Minimal OAuth Server
|
||||
```ruby
|
||||
# Gemfile
|
||||
gem 'roda'
|
||||
gem 'rodauth-oauth'
|
||||
gem 'sequel'
|
||||
|
||||
# lib/auth_server.rb
|
||||
class AuthServer < Roda
|
||||
plugin :sessions, secret: ENV['SESSION_SECRET']
|
||||
plugin :rodauth do
|
||||
db DB
|
||||
enable :login, :logout, :create_account,
|
||||
:oidc, :oauth_pkce, :oauth_authorization_code_grant,
|
||||
:oauth_token_revocation
|
||||
|
||||
oauth_application_scopes %w[openid email profile]
|
||||
oauth_require_pkce true
|
||||
end
|
||||
|
||||
route do |r|
|
||||
r.rodauth # All OAuth endpoints auto-mounted!
|
||||
|
||||
# Your app logic here
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
That's it! All these endpoints are automatically available:
|
||||
- GET /.well-known/openid-configuration
|
||||
- GET /.well-known/jwks.json
|
||||
- GET /oauth/authorize
|
||||
- POST /oauth/token
|
||||
- POST /oauth/revoke
|
||||
- GET /oauth/userinfo
|
||||
- GET /logout
|
||||
|
||||
### Your Current Approach
|
||||
```ruby
|
||||
# app/controllers/oidc_controller.rb
|
||||
class OidcController < ApplicationController
|
||||
def authorize
|
||||
# 150 lines of validation logic
|
||||
end
|
||||
|
||||
def token
|
||||
# 100 lines of token generation logic
|
||||
end
|
||||
|
||||
def userinfo
|
||||
# 50 lines of claims logic
|
||||
end
|
||||
|
||||
def logout
|
||||
# 50 lines of logout logic
|
||||
end
|
||||
|
||||
private
|
||||
|
||||
def validate_pkce(auth_code, code_verifier)
|
||||
# 50 lines of PKCE validation
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
## Integration Paths
|
||||
|
||||
### Option 1: Stick with Your Implementation
|
||||
- Keep building features incrementally
|
||||
- Effort: 2-3 months to reach feature parity
|
||||
- Pro: Rails native, full control
|
||||
- Con: Continuous maintenance burden
|
||||
|
||||
### Option 2: Switch to Rodauth-OAuth
|
||||
- Learn Roda/Rodauth (1-2 weeks)
|
||||
- Migrate database (1 week)
|
||||
- Replace 450 lines of code with config (1 week)
|
||||
- Testing & validation (2-3 weeks)
|
||||
- Effort: 4-8 weeks total
|
||||
- Pro: Production-ready, certified, maintained
|
||||
- Con: Different framework (Roda)
|
||||
|
||||
### Option 3: Hybrid Approach
|
||||
- Keep your Rails app for business logic
|
||||
- Use rodauth-oauth as separate OAuth/OIDC service
|
||||
- Services communicate via HTTP/APIs
|
||||
- Effort: 2-3 weeks (independent services)
|
||||
- Pro: Best of both worlds
|
||||
- Con: Operational complexity
|
||||
|
||||
## Decision Matrix
|
||||
|
||||
### Use Rodauth-OAuth If You Need...
|
||||
- [x] Standards compliance (OpenID certified)
|
||||
- [x] Multiple grant types (Client Credentials, Device Code, etc.)
|
||||
- [x] Token revocation/introspection
|
||||
- [x] Refresh tokens
|
||||
- [x] Advanced logout (front/back-channel)
|
||||
- [x] Session management
|
||||
- [x] Token hashing/security best practices
|
||||
- [x] Hands-off maintenance
|
||||
- [x] Production-battle-tested code
|
||||
|
||||
### Keep Your Implementation If You...
|
||||
- [x] Only need Authorization Code + PKCE
|
||||
- [x] Want zero Roda/external framework learning
|
||||
- [x] Value Rails patterns over standards
|
||||
- [x] Like to understand every line of code
|
||||
- [x] Can allocate time for ongoing maintenance
|
||||
- [x] Prefer minimal dependencies
|
||||
|
||||
## Key Differences You'll Notice
|
||||
|
||||
### 1. Framework Paradigm
|
||||
- **Your impl**: Rails (MVC, familiar)
|
||||
- **Rodauth**: Roda (routing-focused, lightweight)
|
||||
|
||||
### 2. Database ORM
|
||||
- **Your impl**: ActiveRecord (Rails native)
|
||||
- **Rodauth**: Sequel (lighter, more control)
|
||||
|
||||
### 3. Configuration Style
|
||||
- **Your impl**: Rails initializers, environment variables
|
||||
- **Rodauth**: Plugin block with DSL
|
||||
|
||||
### 4. Model Management
|
||||
- **Your impl**: Rails models with validations, associations
|
||||
- **Rodauth**: Minimal models, logic in database
|
||||
|
||||
### 5. Testing Approach
|
||||
- **Your impl**: RSpec, model/controller tests
|
||||
- **Rodauth**: Request-based integration tests
|
||||
|
||||
## File Locations (If You Switch)
|
||||
|
||||
```
|
||||
Current Structure
|
||||
├── app/controllers/oidc_controller.rb
|
||||
├── app/models/
|
||||
│ ├── oidc_authorization_code.rb
|
||||
│ ├── oidc_access_token.rb
|
||||
│ └── oidc_user_consent.rb
|
||||
├── app/services/oidc_jwt_service.rb
|
||||
├── db/migrate/*oidc*.rb
|
||||
|
||||
Rodauth-OAuth Equivalent
|
||||
├── lib/rodauth_app.rb # Configuration (replaces most controllers)
|
||||
├── app/views/rodauth/ # Templates (consent form, etc.)
|
||||
├── config/routes.rb # Simple: routes mount rodauth
|
||||
└── db/migrate/*rodauth_oauth*.rb
|
||||
```
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Your Implementation
|
||||
- Small tables → fast queries
|
||||
- Fewer columns → less overhead
|
||||
- Simple token validation
|
||||
- Estimated: 5-10ms per token validation
|
||||
|
||||
### Rodauth-OAuth
|
||||
- More columns, but same queries
|
||||
- Optional token hashing (slight overhead)
|
||||
- More features = more options checked
|
||||
- Estimated: 10-20ms per token validation
|
||||
- Can be optimized: disable unused features
|
||||
|
||||
## Getting Started (If You Want to Explore)
|
||||
|
||||
1. **Review the code**
|
||||
```bash
|
||||
cd /Users/dkam/Development/clinch/tmp/rodauth-oauth
|
||||
ls -la lib/rodauth/features/ # See all features
|
||||
cat examples/oidc/authentication_server.rb # Full working example
|
||||
```
|
||||
|
||||
2. **Run the example**
|
||||
```bash
|
||||
cd /Users/dkam/Development/clinch/tmp/rodauth-oauth/examples
|
||||
ruby oidc/authentication_server.rb # Starts server on http://localhost:9292
|
||||
```
|
||||
|
||||
3. **Read the key files**
|
||||
- README.md: Overview
|
||||
- MIGRATION-GUIDE-v1.md: Version migration (shows architecture)
|
||||
- test/migrate/*.rb: Database schema
|
||||
- examples/oidc/*.rb: Complete working implementation
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **If keeping your implementation:**
|
||||
- Prioritize refresh token support
|
||||
- Add token revocation endpoint
|
||||
- Consider token hashing
|
||||
|
||||
2. **If exploring rodauth-oauth:**
|
||||
- Run the example server
|
||||
- Review the feature files
|
||||
- Check if hybrid approach works for your org
|
||||
|
||||
3. **For either path:**
|
||||
- Document your decision
|
||||
- Plan feature roadmap
|
||||
- Set up appropriate monitoring
|
||||
|
||||
---
|
||||
|
||||
**Bottom Line**: Rodauth-OAuth is the "production-grade" option if you need comprehensive OAuth/OIDC. Your implementation is fine if you keep features minimal and have maintenance bandwidth.
|
||||
330
docs/traefik-example.md
Normal file
330
docs/traefik-example.md
Normal file
@@ -0,0 +1,330 @@
|
||||
# Traefik ForwardAuth Configuration Examples
|
||||
|
||||
## Basic Configuration (Protecting MEtube)
|
||||
|
||||
### docker-compose.yml with Traefik Labels
|
||||
|
||||
```yaml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
# Clinch SSO
|
||||
clinch:
|
||||
image: your-clinch-image
|
||||
labels:
|
||||
- "traefik.enable=true"
|
||||
- "traefik.http.routers.clinch.rule=Host(`clinch.yourdomain.com`)"
|
||||
- "traefik.http.routers.clinch.entrypoints=websecure"
|
||||
- "traefik.http.routers.clinch.tls.certresolver=letsencrypt"
|
||||
- "traefik.http.services.clinch.loadbalancer.server.port=3000"
|
||||
|
||||
# MEtube - Protected by Clinch
|
||||
metube:
|
||||
image: ghcr.io/alexta69/metube
|
||||
labels:
|
||||
- "traefik.enable=true"
|
||||
- "traefik.http.routers.metube.rule=Host(`metube.yourdomain.com`)"
|
||||
- "traefik.http.routers.metube.entrypoints=websecure"
|
||||
- "traefik.http.routers.metube.tls.certresolver=letsencrypt"
|
||||
|
||||
# ForwardAuth middleware
|
||||
- "traefik.http.routers.metube.middlewares=metube-auth"
|
||||
- "traefik.http.middlewares.metube-auth.forwardauth.address=http://clinch:3000/api/verify?app=metube"
|
||||
- "traefik.http.middlewares.metube-auth.forwardauth.authResponseHeaders=Remote-User,Remote-Email,Remote-Groups,Remote-Admin"
|
||||
|
||||
- "traefik.http.services.metube.loadbalancer.server.port=8081"
|
||||
```
|
||||
|
||||
## Traefik Static Configuration (File)
|
||||
|
||||
### traefik.yml
|
||||
|
||||
```yaml
|
||||
entryPoints:
|
||||
web:
|
||||
address: ":80"
|
||||
http:
|
||||
redirections:
|
||||
entryPoint:
|
||||
to: websecure
|
||||
scheme: https
|
||||
|
||||
websecure:
|
||||
address: ":443"
|
||||
|
||||
certificatesResolvers:
|
||||
letsencrypt:
|
||||
acme:
|
||||
email: your-email@example.com
|
||||
storage: /letsencrypt/acme.json
|
||||
tlsChallenge: {}
|
||||
|
||||
providers:
|
||||
docker:
|
||||
exposedByDefault: false
|
||||
file:
|
||||
filename: /config/dynamic.yml
|
||||
watch: true
|
||||
```
|
||||
|
||||
## Traefik Dynamic Configuration (File)
|
||||
|
||||
### dynamic.yml
|
||||
|
||||
```yaml
|
||||
http:
|
||||
middlewares:
|
||||
# Clinch ForwardAuth middleware for MEtube
|
||||
metube-auth:
|
||||
forwardAuth:
|
||||
address: "http://clinch:3000/api/verify?app=metube"
|
||||
authResponseHeaders:
|
||||
- "Remote-User"
|
||||
- "Remote-Email"
|
||||
- "Remote-Groups"
|
||||
- "Remote-Admin"
|
||||
|
||||
# Clinch ForwardAuth for Sonarr (with group restriction)
|
||||
sonarr-auth:
|
||||
forwardAuth:
|
||||
address: "http://clinch:3000/api/verify?app=sonarr"
|
||||
authResponseHeaders:
|
||||
- "Remote-User"
|
||||
- "Remote-Email"
|
||||
- "Remote-Groups"
|
||||
- "Remote-Admin"
|
||||
|
||||
routers:
|
||||
clinch:
|
||||
rule: "Host(`clinch.yourdomain.com`)"
|
||||
service: clinch
|
||||
entryPoints:
|
||||
- websecure
|
||||
tls:
|
||||
certResolver: letsencrypt
|
||||
|
||||
metube:
|
||||
rule: "Host(`metube.yourdomain.com`)"
|
||||
service: metube
|
||||
middlewares:
|
||||
- metube-auth
|
||||
entryPoints:
|
||||
- websecure
|
||||
tls:
|
||||
certResolver: letsencrypt
|
||||
|
||||
sonarr:
|
||||
rule: "Host(`sonarr.yourdomain.com`)"
|
||||
service: sonarr
|
||||
middlewares:
|
||||
- sonarr-auth
|
||||
entryPoints:
|
||||
- websecure
|
||||
tls:
|
||||
certResolver: letsencrypt
|
||||
|
||||
services:
|
||||
clinch:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: "http://clinch:3000"
|
||||
|
||||
metube:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: "http://metube:8081"
|
||||
|
||||
sonarr:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: "http://sonarr:8989"
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
1. User visits `https://metube.yourdomain.com`
|
||||
2. Traefik intercepts and applies the `metube-auth` middleware
|
||||
3. Traefik makes request to `http://clinch:3000/api/verify?app=metube`
|
||||
4. Clinch checks if user is authenticated and authorized:
|
||||
- If **200**: Traefik forwards request to MEtube with user headers
|
||||
- If **401/403**: Traefik redirects to Clinch login page
|
||||
5. User signs into Clinch (with TOTP if enabled)
|
||||
6. Clinch redirects back to MEtube
|
||||
7. User can now access MEtube!
|
||||
|
||||
## Setup Steps
|
||||
|
||||
### 1. Create Applications in Clinch
|
||||
|
||||
Via Rails console:
|
||||
|
||||
```ruby
|
||||
# MEtube - No groups = everyone can access
|
||||
Application.create!(
|
||||
name: "MEtube",
|
||||
slug: "metube",
|
||||
app_type: "trusted_header",
|
||||
active: true
|
||||
)
|
||||
|
||||
# Sonarr - Restricted to media-managers group
|
||||
media_group = Group.find_by(name: "media-managers")
|
||||
sonarr = Application.create!(
|
||||
name: "Sonarr",
|
||||
slug: "sonarr",
|
||||
app_type: "trusted_header",
|
||||
active: true
|
||||
)
|
||||
ApplicationGroup.create!(application: sonarr, group: media_group)
|
||||
```
|
||||
|
||||
### 2. Update Traefik Configuration
|
||||
|
||||
Add the ForwardAuth middlewares and labels shown above.
|
||||
|
||||
### 3. Restart Traefik
|
||||
|
||||
```bash
|
||||
docker-compose restart traefik
|
||||
```
|
||||
|
||||
### 4. Test
|
||||
|
||||
Visit https://metube.yourdomain.com - you should be redirected to Clinch login!
|
||||
|
||||
## Advanced: Custom Error Pages
|
||||
|
||||
```yaml
|
||||
http:
|
||||
middlewares:
|
||||
clinch-errors:
|
||||
errors:
|
||||
status:
|
||||
- "401-403"
|
||||
service: clinch
|
||||
query: "/signin?redirect={url}"
|
||||
|
||||
metube-auth:
|
||||
forwardAuth:
|
||||
address: "http://clinch:3000/api/verify?app=metube"
|
||||
authResponseHeaders:
|
||||
- "Remote-User"
|
||||
- "Remote-Email"
|
||||
- "Remote-Groups"
|
||||
- "Remote-Admin"
|
||||
|
||||
routers:
|
||||
metube:
|
||||
rule: "Host(`metube.yourdomain.com`)"
|
||||
service: metube
|
||||
middlewares:
|
||||
- metube-auth
|
||||
- clinch-errors # Add custom error handling
|
||||
entryPoints:
|
||||
- websecure
|
||||
tls:
|
||||
certResolver: letsencrypt
|
||||
```
|
||||
|
||||
## Kubernetes Ingress Example
|
||||
|
||||
```yaml
|
||||
apiVersion: traefik.containo.us/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: clinch-metube-auth
|
||||
spec:
|
||||
forwardAuth:
|
||||
address: http://clinch.clinch-system.svc.cluster.local:3000/api/verify?app=metube
|
||||
authResponseHeaders:
|
||||
- Remote-User
|
||||
- Remote-Email
|
||||
- Remote-Groups
|
||||
- Remote-Admin
|
||||
|
||||
---
|
||||
|
||||
apiVersion: networking.k8s.io/v1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
name: metube
|
||||
annotations:
|
||||
traefik.ingress.kubernetes.io/router.middlewares: default-clinch-metube-auth@kubernetescrd
|
||||
spec:
|
||||
rules:
|
||||
- host: metube.yourdomain.com
|
||||
http:
|
||||
paths:
|
||||
- path: /
|
||||
pathType: Prefix
|
||||
backend:
|
||||
service:
|
||||
name: metube
|
||||
port:
|
||||
number: 8081
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Users not staying logged in
|
||||
|
||||
Ensure Traefik preserves cookies and sets correct headers:
|
||||
|
||||
```yaml
|
||||
http:
|
||||
routers:
|
||||
clinch:
|
||||
middlewares:
|
||||
- clinch-headers
|
||||
|
||||
middlewares:
|
||||
clinch-headers:
|
||||
headers:
|
||||
customRequestHeaders:
|
||||
X-Forwarded-Host: "clinch.yourdomain.com"
|
||||
X-Forwarded-Proto: "https"
|
||||
```
|
||||
|
||||
### Authentication loop
|
||||
|
||||
1. Check that `/api/verify` is accessible from Traefik
|
||||
2. Verify the ForwardAuth middleware address is correct
|
||||
3. Check Clinch logs for errors
|
||||
|
||||
### Check Clinch logs
|
||||
|
||||
```bash
|
||||
docker-compose logs -f clinch
|
||||
```
|
||||
|
||||
You'll see ForwardAuth log messages like:
|
||||
```
|
||||
ForwardAuth: User user@example.com granted access to metube
|
||||
ForwardAuth: Unauthorized - No session cookie
|
||||
```
|
||||
|
||||
### Debug Traefik
|
||||
|
||||
Enable access logs in `traefik.yml`:
|
||||
|
||||
```yaml
|
||||
accessLog:
|
||||
filePath: "/var/log/traefik/access.log"
|
||||
format: json
|
||||
```
|
||||
|
||||
## Comparison: Traefik vs. Caddy
|
||||
|
||||
### Traefik
|
||||
- ✅ Better for Docker/Kubernetes environments
|
||||
- ✅ Automatic service discovery
|
||||
- ✅ Rich middleware system
|
||||
- ❌ More complex configuration
|
||||
|
||||
### Caddy
|
||||
- ✅ Simpler configuration
|
||||
- ✅ Automatic HTTPS by default
|
||||
- ✅ Better for static configurations
|
||||
- ❌ Less dynamic than Traefik
|
||||
|
||||
Both work great with Clinch ForwardAuth!
|
||||
238
docs/webauthn-implementation-summary.md
Normal file
238
docs/webauthn-implementation-summary.md
Normal file
@@ -0,0 +1,238 @@
|
||||
# WebAuthn/Passkeys Implementation - Quick Start
|
||||
|
||||
This is a companion summary to the [full implementation plan](webauthn-passkeys-plan.md).
|
||||
|
||||
## What We're Building
|
||||
|
||||
Add modern passwordless authentication (passkeys) to Clinch, allowing users to sign in with Face ID, Touch ID, Windows Hello, or hardware security keys (YubiKey).
|
||||
|
||||
## Quick Overview
|
||||
|
||||
### Features
|
||||
- **Passwordless login** - Sign in with biometrics, no password needed
|
||||
- **Multi-device support** - Register passkeys on multiple devices
|
||||
- **Synced passkeys** - Works with iCloud Keychain, Google Password Manager
|
||||
- **2FA option** - Use passkeys as second factor instead of TOTP
|
||||
- **Hardware keys** - Support for YubiKey and other FIDO2 devices
|
||||
- **User management** - Register, name, and delete multiple passkeys
|
||||
|
||||
### Tech Stack
|
||||
- `webauthn` gem (~3.0) - Server-side WebAuthn implementation
|
||||
- Browser WebAuthn API - Native browser support (no JS libraries needed)
|
||||
- Stimulus controller - Frontend UX management
|
||||
|
||||
## 5-Phase Implementation
|
||||
|
||||
### Phase 1: Foundation (Week 1-2)
|
||||
Core WebAuthn registration and authentication
|
||||
- Database schema for credentials
|
||||
- Registration ceremony (add passkey)
|
||||
- Authentication ceremony (sign in with passkey)
|
||||
- Basic JavaScript integration
|
||||
|
||||
### Phase 2: User Experience (Week 2-3)
|
||||
Polished UI and management
|
||||
- Profile page: list/manage passkeys
|
||||
- Login page: "Sign in with Passkey" button
|
||||
- Nickname management
|
||||
- First-run wizard update
|
||||
|
||||
### Phase 3: Security (Week 3-4)
|
||||
Advanced security features
|
||||
- Sign count verification (clone detection)
|
||||
- Attestation validation (optional)
|
||||
- User verification requirements
|
||||
- Admin controls and policies
|
||||
|
||||
### Phase 4: Integration (Week 4)
|
||||
Connect with existing features
|
||||
- OIDC integration (AMR claims)
|
||||
- WebAuthn as 2FA option
|
||||
- ForwardAuth compatibility
|
||||
- Account recovery flows
|
||||
|
||||
### Phase 5: Testing & Docs (Week 4-5)
|
||||
Quality assurance
|
||||
- Unit, integration, and system tests
|
||||
- Virtual authenticator testing
|
||||
- User and admin documentation
|
||||
- Security audit
|
||||
|
||||
## Database Schema
|
||||
|
||||
### New Table: `webauthn_credentials`
|
||||
```ruby
|
||||
create_table :webauthn_credentials do |t|
|
||||
t.references :user, null: false, foreign_key: true
|
||||
t.string :external_id, null: false # Credential ID
|
||||
t.string :public_key, null: false # Public key
|
||||
t.integer :sign_count, default: 0 # For clone detection
|
||||
t.string :nickname # "MacBook Touch ID"
|
||||
t.string :authenticator_type # platform/cross-platform
|
||||
t.datetime :last_used_at
|
||||
t.timestamps
|
||||
end
|
||||
```
|
||||
|
||||
### Update `users` table
|
||||
```ruby
|
||||
add_column :users, :webauthn_id, :string # User handle
|
||||
add_column :users, :webauthn_required, :boolean # Policy enforcement
|
||||
```
|
||||
|
||||
## Key User Flows
|
||||
|
||||
### 1. Register Passkey
|
||||
```
|
||||
User profile → "Add Passkey" → Browser prompt →
|
||||
Touch ID/Face ID → Passkey saved → Can sign in
|
||||
```
|
||||
|
||||
### 2. Sign In with Passkey
|
||||
```
|
||||
Login page → Enter email → "Continue with Passkey" →
|
||||
Browser prompt → Touch ID/Face ID → Signed in
|
||||
```
|
||||
|
||||
### 3. WebAuthn as 2FA
|
||||
```
|
||||
Enter password → Prompted for passkey →
|
||||
Touch ID/Face ID → Signed in
|
||||
```
|
||||
|
||||
## Security Highlights
|
||||
|
||||
1. **Phishing-resistant** - Passkeys are bound to the domain
|
||||
2. **No shared secrets** - Public key cryptography
|
||||
3. **Clone detection** - Sign count verification
|
||||
4. **User verification** - Biometric or PIN required
|
||||
5. **Privacy-preserving** - Opaque user handles
|
||||
|
||||
## Integration Points
|
||||
|
||||
### OIDC
|
||||
- Add `amr` claim: `["webauthn"]`
|
||||
- Support `acr_values=webauthn` in authorization request
|
||||
- Include authentication method in ID token
|
||||
|
||||
### ForwardAuth
|
||||
- WebAuthn creates standard sessions
|
||||
- Works automatically with existing `/api/verify` endpoint
|
||||
- Optional header: `Remote-Auth-Method: webauthn`
|
||||
|
||||
### Admin Controls
|
||||
- Require WebAuthn for specific users/groups
|
||||
- View all registered passkeys
|
||||
- Revoke compromised credentials
|
||||
- Audit log of authentications
|
||||
|
||||
## Files to Create/Modify
|
||||
|
||||
### New Files (~12)
|
||||
- `app/models/webauthn_credential.rb`
|
||||
- `app/controllers/webauthn_controller.rb`
|
||||
- `app/javascript/controllers/webauthn_controller.js`
|
||||
- `config/initializers/webauthn.rb`
|
||||
- Views for registration/management
|
||||
- Tests (model, controller, integration, system)
|
||||
- Documentation (user guide, admin guide)
|
||||
|
||||
### Modified Files (~8)
|
||||
- `Gemfile` - Add webauthn gem
|
||||
- `app/models/user.rb` - Add associations/methods
|
||||
- `app/controllers/sessions_controller.rb` - WebAuthn authentication
|
||||
- `app/views/sessions/new.html.erb` - Add passkey button
|
||||
- `app/views/profiles/show.html.erb` - Passkey management
|
||||
- `config/routes.rb` - WebAuthn routes
|
||||
- `README.md` - Document feature
|
||||
- `app/controllers/oidc_controller.rb` - AMR claims
|
||||
|
||||
## Browser Support
|
||||
|
||||
### Supported (WebAuthn Level 2)
|
||||
- Chrome/Edge 90+
|
||||
- Firefox 90+
|
||||
- Safari 14+ (macOS Big Sur / iOS 14+)
|
||||
|
||||
### Platform Authenticators
|
||||
- macOS: Touch ID
|
||||
- iOS/iPadOS: Face ID, Touch ID
|
||||
- Windows: Windows Hello (face, fingerprint, PIN)
|
||||
- Android: Fingerprint, face unlock
|
||||
|
||||
### Roaming Authenticators
|
||||
- YubiKey 5 series
|
||||
- SoloKeys
|
||||
- Google Titan Security Key
|
||||
- Any FIDO2-certified hardware key
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. **Attestation**: Validate authenticator hardware? (Recommend: No for v1)
|
||||
2. **Resident Keys**: Require discoverable credentials? (Recommend: Preferred, not required)
|
||||
3. **Synced Passkeys**: Allow iCloud/Google sync? (Recommend: Yes)
|
||||
4. **Recovery**: How to recover if all passkeys lost? (Recommend: Email verification)
|
||||
5. **2FA**: Replace TOTP or offer both? (Recommend: Offer both)
|
||||
6. **Enforcement**: When to require passkeys? (Recommend: 3 months after launch for admins)
|
||||
|
||||
## Success Metrics
|
||||
|
||||
### Adoption
|
||||
- % of users with ≥1 passkey
|
||||
- % of logins using passkey vs password
|
||||
- Average registration time
|
||||
|
||||
### Security
|
||||
- Reduced password reset requests
|
||||
- Reduced account takeover attempts
|
||||
- Zero phishing success (passkeys can't be phished)
|
||||
|
||||
### Performance
|
||||
- Faster authentication time
|
||||
- Low error rate (<5%)
|
||||
- High browser compatibility (>95%)
|
||||
|
||||
## Timeline
|
||||
|
||||
- **Week 1-2**: Foundation (Phase 1)
|
||||
- **Week 2-3**: UX & Testing (Phase 2 + Phase 5 start)
|
||||
- **Week 3-4**: Security & Integration (Phase 3 + Phase 4)
|
||||
- **Week 4-5**: Beta testing and documentation
|
||||
- **Week 5+**: Production rollout
|
||||
|
||||
**Total**: 4-6 weeks for full implementation and testing
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. ✅ Review this plan
|
||||
2. ⬜ Create Gitea issues for each phase
|
||||
3. ⬜ Add `webauthn` gem to Gemfile
|
||||
4. ⬜ Create database migrations
|
||||
5. ⬜ Implement Phase 1 (registration ceremony)
|
||||
6. ⬜ Implement Phase 1 (authentication ceremony)
|
||||
7. ⬜ Add JavaScript frontend
|
||||
8. ⬜ Test with virtual authenticators
|
||||
9. ⬜ Continue through remaining phases
|
||||
|
||||
## Resources
|
||||
|
||||
- [Full Implementation Plan](webauthn-passkeys-plan.md) - Detailed 50+ page document
|
||||
- [W3C WebAuthn Spec](https://www.w3.org/TR/webauthn-2/)
|
||||
- [webauthn-ruby gem](https://github.com/cedarcode/webauthn-ruby)
|
||||
- [WebAuthn Guide](https://webauthn.guide/)
|
||||
- [MDN Web Authentication API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API)
|
||||
|
||||
## Questions?
|
||||
|
||||
Refer to the [full implementation plan](webauthn-passkeys-plan.md) for:
|
||||
- Detailed technical specifications
|
||||
- Security considerations
|
||||
- Code examples
|
||||
- Testing strategies
|
||||
- Migration strategies
|
||||
- Complete API reference
|
||||
|
||||
---
|
||||
|
||||
*Status: Ready for Review*
|
||||
*See: [webauthn-passkeys-plan.md](webauthn-passkeys-plan.md) for full details*
|
||||
787
docs/webauthn-passkeys-plan.md
Normal file
787
docs/webauthn-passkeys-plan.md
Normal file
@@ -0,0 +1,787 @@
|
||||
# WebAuthn / Passkeys Implementation Plan for Clinch
|
||||
|
||||
## Executive Summary
|
||||
|
||||
This document outlines a comprehensive plan to add WebAuthn/Passkeys support to Clinch, enabling modern passwordless authentication alongside the existing password + TOTP authentication methods.
|
||||
|
||||
## Goals
|
||||
|
||||
1. **Primary Authentication**: Allow users to register and use passkeys as their primary login method (passwordless)
|
||||
2. **MFA Enhancement**: Support passkeys as a second factor alongside TOTP
|
||||
3. **Cross-Device Support**: Enable both platform authenticators (Face ID, Touch ID, Windows Hello) and roaming authenticators (YubiKey, security keys)
|
||||
4. **User Experience**: Provide seamless registration, authentication, and management of multiple passkeys
|
||||
5. **Backward Compatibility**: Maintain existing password + TOTP flows without disruption
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### Technology Stack
|
||||
- **webauthn gem** (~3.0): Ruby library for WebAuthn server implementation
|
||||
- **Rails 8.1**: Existing framework
|
||||
- **Browser WebAuthn API**: Native browser support (all modern browsers)
|
||||
|
||||
### Core Components
|
||||
|
||||
1. **WebAuthn Credentials Model**: Store registered authenticators
|
||||
2. **WebAuthn Controller**: Handle registration and authentication ceremonies
|
||||
3. **Session Flow Updates**: Integrate passkey authentication into existing login flow
|
||||
4. **User Management UI**: Allow users to register, name, and delete passkeys
|
||||
5. **Admin Controls**: Configure WebAuthn policies per user/group
|
||||
|
||||
---
|
||||
|
||||
## Database Schema
|
||||
|
||||
### New Table: `webauthn_credentials`
|
||||
|
||||
```ruby
|
||||
create_table :webauthn_credentials do |t|
|
||||
t.references :user, null: false, foreign_key: true, index: true
|
||||
|
||||
# WebAuthn specification fields
|
||||
t.string :external_id, null: false, index: { unique: true } # credential ID (base64)
|
||||
t.string :public_key, null: false # public key (base64)
|
||||
t.integer :sign_count, null: false, default: 0 # signature counter (clone detection)
|
||||
|
||||
# Metadata
|
||||
t.string :nickname # User-friendly name ("MacBook Touch ID")
|
||||
t.string :authenticator_type # "platform" or "cross-platform"
|
||||
t.boolean :backup_eligible, default: false # Can be backed up (passkey sync)
|
||||
t.boolean :backup_state, default: false # Currently backed up
|
||||
|
||||
# Tracking
|
||||
t.datetime :last_used_at
|
||||
t.string :last_used_ip
|
||||
t.string :user_agent # Browser/OS info
|
||||
|
||||
timestamps
|
||||
end
|
||||
|
||||
add_index :webauthn_credentials, [:user_id, :external_id], unique: true
|
||||
```
|
||||
|
||||
### Update `users` table
|
||||
|
||||
```ruby
|
||||
add_column :users, :webauthn_required, :boolean, default: false, null: false
|
||||
add_column :users, :webauthn_id, :string # WebAuthn user handle (random, stable, opaque)
|
||||
add_index :users, :webauthn_id, unique: true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Phases
|
||||
|
||||
### Phase 1: Foundation (Core WebAuthn Support)
|
||||
|
||||
**Objective**: Enable basic passkey registration and authentication
|
||||
|
||||
#### 1.1 Setup & Dependencies
|
||||
|
||||
- [ ] Add `webauthn` gem to Gemfile (~3.0)
|
||||
- [ ] Create WebAuthn initializer with configuration
|
||||
- [ ] Generate migration for `webauthn_credentials` table
|
||||
- [ ] Add WebAuthn user handle generation to User model
|
||||
|
||||
#### 1.2 Models
|
||||
|
||||
**File**: `app/models/webauthn_credential.rb`
|
||||
```ruby
|
||||
class WebauthnCredential < ApplicationRecord
|
||||
belongs_to :user
|
||||
|
||||
validates :external_id, presence: true, uniqueness: true
|
||||
validates :public_key, presence: true
|
||||
validates :sign_count, presence: true, numericality: { greater_than_or_equal_to: 0 }
|
||||
|
||||
scope :active, -> { where(revoked_at: nil) }
|
||||
scope :platform_authenticators, -> { where(authenticator_type: "platform") }
|
||||
scope :roaming_authenticators, -> { where(authenticator_type: "cross-platform") }
|
||||
|
||||
# Update last used timestamp and sign count after successful authentication
|
||||
def update_usage!(sign_count:, ip_address: nil)
|
||||
update!(
|
||||
last_used_at: Time.current,
|
||||
last_used_ip: ip_address,
|
||||
sign_count: sign_count
|
||||
)
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
**Update**: `app/models/user.rb`
|
||||
```ruby
|
||||
has_many :webauthn_credentials, dependent: :destroy
|
||||
|
||||
# Generate stable WebAuthn user handle on first use
|
||||
def webauthn_user_handle
|
||||
return webauthn_id if webauthn_id.present?
|
||||
|
||||
# Generate random 64-byte opaque identifier (base64url encoded)
|
||||
handle = SecureRandom.urlsafe_base64(64)
|
||||
update_column(:webauthn_id, handle)
|
||||
handle
|
||||
end
|
||||
|
||||
def webauthn_enabled?
|
||||
webauthn_credentials.active.exists?
|
||||
end
|
||||
|
||||
def can_authenticate_with_webauthn?
|
||||
webauthn_enabled? && active?
|
||||
end
|
||||
```
|
||||
|
||||
#### 1.3 WebAuthn Configuration
|
||||
|
||||
**File**: `config/initializers/webauthn.rb`
|
||||
```ruby
|
||||
WebAuthn.configure do |config|
|
||||
# Relying Party name (displayed in authenticator)
|
||||
config.origin = ENV.fetch("CLINCH_HOST", "http://localhost:3000")
|
||||
|
||||
# Relying Party ID (must match origin domain)
|
||||
config.rp_name = "Clinch Identity Provider"
|
||||
|
||||
# Credential timeout (60 seconds)
|
||||
config.credential_options_timeout = 60_000
|
||||
|
||||
# Supported algorithms (ES256, RS256)
|
||||
config.algorithms = ["ES256", "RS256"]
|
||||
end
|
||||
```
|
||||
|
||||
#### 1.4 Registration Flow (Ceremony)
|
||||
|
||||
**File**: `app/controllers/webauthn_controller.rb`
|
||||
|
||||
Key actions:
|
||||
- `GET /webauthn/new` - Display registration page
|
||||
- `POST /webauthn/challenge` - Generate registration challenge
|
||||
- `POST /webauthn/create` - Verify and store credential
|
||||
|
||||
**Registration Process**:
|
||||
1. User clicks "Add Passkey" in profile settings
|
||||
2. Server generates challenge options (stored in session)
|
||||
3. Browser calls `navigator.credentials.create()`
|
||||
4. User authenticates with device (Touch ID, Face ID, etc.)
|
||||
5. Browser returns signed credential
|
||||
6. Server verifies signature and stores credential
|
||||
|
||||
#### 1.5 Authentication Flow (Ceremony)
|
||||
|
||||
**Update**: `app/controllers/sessions_controller.rb`
|
||||
|
||||
New actions:
|
||||
- `POST /sessions/webauthn/challenge` - Generate authentication challenge
|
||||
- `POST /sessions/webauthn/verify` - Verify credential and sign in
|
||||
|
||||
**Authentication Process**:
|
||||
1. User clicks "Sign in with Passkey" on login page
|
||||
2. Server generates challenge (stored in session)
|
||||
3. Browser calls `navigator.credentials.get()`
|
||||
4. User authenticates with device
|
||||
5. Browser returns signed assertion
|
||||
6. Server verifies signature, checks sign count, creates session
|
||||
|
||||
#### 1.6 Frontend JavaScript
|
||||
|
||||
**File**: `app/javascript/controllers/webauthn_controller.js` (Stimulus)
|
||||
|
||||
Responsibilities:
|
||||
- Encode/decode base64url data for WebAuthn API
|
||||
- Handle browser WebAuthn API calls
|
||||
- Error handling and user feedback
|
||||
- Progressive enhancement (feature detection)
|
||||
|
||||
**Example registration**:
|
||||
```javascript
|
||||
async register() {
|
||||
const options = await this.fetchChallenge()
|
||||
const credential = await navigator.credentials.create(options)
|
||||
await this.submitCredential(credential)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: User Experience & Management
|
||||
|
||||
**Objective**: Provide intuitive UI for managing passkeys
|
||||
|
||||
#### 2.1 Profile Management
|
||||
|
||||
**File**: `app/views/profiles/show.html.erb` (update)
|
||||
|
||||
Features:
|
||||
- List all registered passkeys with nicknames
|
||||
- Show last used timestamp
|
||||
- Badge for platform vs roaming authenticators
|
||||
- Add new passkey button
|
||||
- Delete passkey button (with confirmation)
|
||||
- Show "synced passkey" badge if backup_state is true
|
||||
|
||||
#### 2.2 Registration Improvements
|
||||
|
||||
- Auto-detect device type and suggest nickname ("Chrome on MacBook")
|
||||
- Show preview of what authenticator will display
|
||||
- Require at least one authentication method (password OR passkey)
|
||||
- Warning if removing last authentication method
|
||||
|
||||
#### 2.3 Login Page Updates
|
||||
|
||||
**File**: `app/views/sessions/new.html.erb` (update)
|
||||
|
||||
- Add "Sign in with Passkey" button (conditional rendering)
|
||||
- Show button only if WebAuthn is supported by browser
|
||||
- Progressive enhancement: fallback to password if WebAuthn fails
|
||||
- Email field for identifying which user's passkeys to request
|
||||
|
||||
**Flow**:
|
||||
1. User enters email address
|
||||
2. Server checks if user has passkeys
|
||||
3. If yes, show "Continue with Passkey" button
|
||||
4. If no passkeys, show password field
|
||||
|
||||
#### 2.4 First-Run Wizard Update
|
||||
|
||||
**File**: `app/views/users/new.html.erb` (first-run wizard)
|
||||
|
||||
- Option to register passkey immediately after creating account
|
||||
- Skip passkey registration if not supported or user declines
|
||||
- Encourage passkey setup but don't require it
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Security & Advanced Features
|
||||
|
||||
**Objective**: Harden security and add enterprise features
|
||||
|
||||
#### 3.1 Sign Count Verification
|
||||
|
||||
**Purpose**: Detect cloned authenticators
|
||||
|
||||
Implementation:
|
||||
- Store sign_count after each authentication
|
||||
- Verify new sign_count > old sign_count
|
||||
- If count doesn't increase: log warning, optionally disable credential
|
||||
- Add admin alert for suspicious activity
|
||||
|
||||
#### 3.2 Attestation Validation (Optional)
|
||||
|
||||
**Purpose**: Verify authenticator is genuine hardware
|
||||
|
||||
Options:
|
||||
- None (most compatible, recommended for self-hosted)
|
||||
- Indirect (some validation)
|
||||
- Direct (strict validation, enterprise)
|
||||
|
||||
**Configuration** (per-application):
|
||||
```ruby
|
||||
class Application < ApplicationRecord
|
||||
enum webauthn_attestation: {
|
||||
none: 0,
|
||||
indirect: 1,
|
||||
direct: 2
|
||||
}, _default: :none
|
||||
end
|
||||
```
|
||||
|
||||
#### 3.3 User Verification Requirements
|
||||
|
||||
**Levels**:
|
||||
- `discouraged`: No user verification (not recommended)
|
||||
- `preferred`: Request if available (default)
|
||||
- `required`: Must have PIN/biometric (high security apps)
|
||||
|
||||
**Configuration**: Per-application setting
|
||||
|
||||
#### 3.4 Resident Keys (Discoverable Credentials)
|
||||
|
||||
**Feature**: Passkey contains username, no email entry needed
|
||||
|
||||
**Implementation**:
|
||||
- Set `residentKey: "preferred"` or `"required"` in credential options
|
||||
- Allow users to sign in without entering email first
|
||||
- Add `POST /sessions/webauthn/discoverable` endpoint
|
||||
|
||||
**Benefits**:
|
||||
- Faster login (no email typing)
|
||||
- Better UX on mobile devices
|
||||
- Works with password managers (1Password, etc.)
|
||||
|
||||
#### 3.5 Admin Controls
|
||||
|
||||
**File**: `app/views/admin/users/edit.html.erb`
|
||||
|
||||
Admin capabilities:
|
||||
- View all user passkeys
|
||||
- Revoke compromised passkeys
|
||||
- Require WebAuthn for specific users/groups
|
||||
- View WebAuthn authentication audit log
|
||||
- Configure WebAuthn policies
|
||||
|
||||
**New fields**:
|
||||
```ruby
|
||||
# On User model
|
||||
webauthn_required: boolean # Must have at least one passkey
|
||||
|
||||
# On Group model
|
||||
webauthn_enforcement: enum # :none, :encouraged, :required
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Integration with Existing Flows
|
||||
|
||||
**Objective**: Seamlessly integrate with OIDC, ForwardAuth, and 2FA
|
||||
|
||||
#### 4.1 OIDC Authorization Flow
|
||||
|
||||
**Update**: `app/controllers/oidc_controller.rb`
|
||||
|
||||
Integration points:
|
||||
- If user has no password but has passkey, trigger WebAuthn
|
||||
- Application can request `webauthn` in `acr_values` parameter
|
||||
- Include `amr` claim in ID token: `["webauthn"]` or `["pwd", "totp"]`
|
||||
|
||||
**Example ID token**:
|
||||
```json
|
||||
{
|
||||
"sub": "user-123",
|
||||
"email": "user@example.com",
|
||||
"amr": ["webauthn"], // Authentication Methods References
|
||||
"acr": "urn:mace:incommon:iap:silver"
|
||||
}
|
||||
```
|
||||
|
||||
#### 4.2 WebAuthn as Second Factor
|
||||
|
||||
**Scenario**: User signs in with password, then WebAuthn as 2FA
|
||||
|
||||
**Flow**:
|
||||
1. User enters password (first factor)
|
||||
2. If `webauthn_required` is true OR user chooses WebAuthn
|
||||
3. Trigger WebAuthn challenge (instead of TOTP)
|
||||
4. User authenticates with passkey
|
||||
5. Create session
|
||||
|
||||
**Configuration**:
|
||||
```ruby
|
||||
# User can choose 2FA method
|
||||
user.preferred_2fa # :totp or :webauthn
|
||||
|
||||
# Admin can require specific 2FA method
|
||||
user.required_2fa # :any, :totp, :webauthn
|
||||
```
|
||||
|
||||
#### 4.3 ForwardAuth Integration
|
||||
|
||||
**Update**: `app/controllers/api/forward_auth_controller.rb`
|
||||
|
||||
No changes needed! WebAuthn creates standard sessions, ForwardAuth works as-is.
|
||||
|
||||
**Header injection**:
|
||||
```
|
||||
Remote-User: user@example.com
|
||||
Remote-Groups: admin,family
|
||||
Remote-Auth-Method: webauthn # NEW optional header
|
||||
```
|
||||
|
||||
#### 4.4 Backup Codes
|
||||
|
||||
**Consideration**: What if user loses all passkeys?
|
||||
|
||||
**Options**:
|
||||
1. Keep existing backup codes system (works for TOTP, not WebAuthn-only)
|
||||
2. Require email verification for account recovery
|
||||
3. Require at least one roaming authenticator (YubiKey) + platform authenticator
|
||||
|
||||
**Recommended**: Require password OR email-verified recovery flow
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Testing & Documentation
|
||||
|
||||
**Objective**: Ensure reliability and provide clear documentation
|
||||
|
||||
#### 5.1 Automated Tests
|
||||
|
||||
**Test Coverage**:
|
||||
|
||||
1. **Model tests** (`test/models/webauthn_credential_test.rb`)
|
||||
- Credential creation and validation
|
||||
- Sign count updates
|
||||
- Credential scopes and queries
|
||||
|
||||
2. **Controller tests** (`test/controllers/webauthn_controller_test.rb`)
|
||||
- Registration challenge generation
|
||||
- Credential verification
|
||||
- Authentication challenge generation
|
||||
- Assertion verification
|
||||
|
||||
3. **Integration tests** (`test/integration/webauthn_authentication_test.rb`)
|
||||
- Full registration flow
|
||||
- Full authentication flow
|
||||
- Error handling (invalid signatures, expired challenges)
|
||||
|
||||
4. **System tests** (`test/system/webauthn_test.rb`)
|
||||
- End-to-end browser testing with virtual authenticator
|
||||
- Chrome DevTools Protocol virtual authenticator
|
||||
|
||||
**Example virtual authenticator test**:
|
||||
```ruby
|
||||
test "user registers passkey" do
|
||||
driver.add_virtual_authenticator(protocol: :ctap2)
|
||||
|
||||
visit profile_path
|
||||
click_on "Add Passkey"
|
||||
fill_in "Nickname", with: "Test Key"
|
||||
click_on "Register"
|
||||
|
||||
assert_text "Passkey registered successfully"
|
||||
end
|
||||
```
|
||||
|
||||
#### 5.2 Documentation
|
||||
|
||||
**Files to create/update**:
|
||||
|
||||
1. **User Guide** (`docs/webauthn-user-guide.md`)
|
||||
- What are passkeys?
|
||||
- How to register a passkey
|
||||
- How to sign in with a passkey
|
||||
- Managing multiple passkeys
|
||||
- Troubleshooting
|
||||
|
||||
2. **Admin Guide** (`docs/webauthn-admin-guide.md`)
|
||||
- WebAuthn policies and configuration
|
||||
- Enforcing passkeys for users/groups
|
||||
- Security considerations
|
||||
- Audit logging
|
||||
|
||||
3. **Developer Guide** (`docs/webauthn-developer-guide.md`)
|
||||
- Architecture overview
|
||||
- WebAuthn ceremony flows
|
||||
- Testing with virtual authenticators
|
||||
- OIDC integration details
|
||||
|
||||
4. **README Update** (`README.md`)
|
||||
- Add WebAuthn/Passkeys to Authentication Methods section
|
||||
- Update feature list
|
||||
|
||||
#### 5.3 Browser Compatibility
|
||||
|
||||
**Supported Browsers**:
|
||||
- Chrome/Edge 90+ (Chromium)
|
||||
- Firefox 90+
|
||||
- Safari 14+ (macOS Big Sur, iOS 14)
|
||||
|
||||
**Graceful Degradation**:
|
||||
- Feature detection: check `window.PublicKeyCredential`
|
||||
- Hide passkey UI if not supported
|
||||
- Always provide password fallback
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### 1. Challenge Storage
|
||||
- Store challenges in server-side session (not cookies)
|
||||
- Challenges expire after 60 seconds
|
||||
- One-time use (mark as used after verification)
|
||||
|
||||
### 2. Origin Validation
|
||||
- WebAuthn library automatically validates origin
|
||||
- Ensure `CLINCH_HOST` environment variable is correct
|
||||
- Must use HTTPS in production (required by WebAuthn spec)
|
||||
|
||||
### 3. Relying Party ID
|
||||
- Must match the origin domain
|
||||
- Cannot be changed after credentials are registered
|
||||
- Use apex domain for subdomain compatibility (e.g., `example.com` works for `auth.example.com` and `app.example.com`)
|
||||
|
||||
### 4. User Handle Privacy
|
||||
- User handle is opaque, random, and stable
|
||||
- Never use email or user ID as user handle
|
||||
- Store in `users.webauthn_id` column
|
||||
|
||||
### 5. Sign Count Verification
|
||||
- Always check sign_count increases
|
||||
- Log suspicious activity (counter didn't increase)
|
||||
- Consider disabling credential if counter resets
|
||||
|
||||
### 6. Credential Backup Awareness
|
||||
- Track `backup_eligible` and `backup_state` flags
|
||||
- Inform users about synced passkeys
|
||||
- Higher security apps may want to disallow backed-up credentials
|
||||
|
||||
### 7. Account Recovery
|
||||
- Don't lock users out if they lose all passkeys
|
||||
- Require email verification for recovery
|
||||
- Send alerts when recovery is used
|
||||
|
||||
---
|
||||
|
||||
## Migration Strategy
|
||||
|
||||
### For Existing Users
|
||||
|
||||
**Option 1: Opt-in (Recommended)**
|
||||
- Add "Register Passkey" button in profile settings
|
||||
- Show banner encouraging passkey setup
|
||||
- Don't require passkeys initially
|
||||
- Gradually increase adoption through UI prompts
|
||||
|
||||
**Option 2: Mandatory Migration**
|
||||
- Set deadline for passkey registration
|
||||
- Email users with instructions
|
||||
- Admins can enforce passkey requirement per group
|
||||
- Provide support documentation
|
||||
|
||||
### For New Users
|
||||
|
||||
**During First-Run Wizard**:
|
||||
1. Create account with email + password (existing flow)
|
||||
2. Offer optional passkey registration
|
||||
3. If accepted, walk through registration
|
||||
4. If declined, remind later in dashboard
|
||||
|
||||
---
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Database Indexes
|
||||
```ruby
|
||||
# Essential indexes for performance
|
||||
add_index :webauthn_credentials, :user_id
|
||||
add_index :webauthn_credentials, :external_id, unique: true
|
||||
add_index :webauthn_credentials, [:user_id, :last_used_at]
|
||||
```
|
||||
|
||||
### Query Optimization
|
||||
- Eager load credentials with user: `User.includes(:webauthn_credentials)`
|
||||
- Cache credential count: `user.webauthn_credentials.count`
|
||||
|
||||
### Cleanup Jobs
|
||||
- Remove expired challenges from session store
|
||||
- Archive old credentials (last_used > 1 year ago)
|
||||
|
||||
---
|
||||
|
||||
## Rollout Plan
|
||||
|
||||
### Phase 1: Development (Week 1-2)
|
||||
- [ ] Setup gem and database schema
|
||||
- [ ] Implement registration ceremony
|
||||
- [ ] Implement authentication ceremony
|
||||
- [ ] Add basic UI components
|
||||
|
||||
### Phase 2: Testing (Week 2-3)
|
||||
- [ ] Write unit and integration tests
|
||||
- [ ] Test with virtual authenticators
|
||||
- [ ] Test on real devices (iOS, Android, Windows, macOS)
|
||||
- [ ] Security audit
|
||||
|
||||
### Phase 3: Beta (Week 3-4)
|
||||
- [ ] Deploy to staging environment
|
||||
- [ ] Enable for admin users only
|
||||
- [ ] Gather feedback
|
||||
- [ ] Fix bugs and UX issues
|
||||
|
||||
### Phase 4: Production (Week 4-5)
|
||||
- [ ] Deploy to production
|
||||
- [ ] Enable for all users (opt-in)
|
||||
- [ ] Monitor error rates and adoption
|
||||
- [ ] Document and share user guides
|
||||
|
||||
### Phase 5: Enforcement (Week 6+)
|
||||
- [ ] Analyze adoption metrics
|
||||
- [ ] Consider enforcement for high-security groups
|
||||
- [ ] Continuous improvement based on feedback
|
||||
|
||||
---
|
||||
|
||||
## Open Questions & Decisions Needed
|
||||
|
||||
1. **Attestation Level**: Should we validate authenticator attestation? (Recommendation: No for v1)
|
||||
|
||||
2. **Resident Key Strategy**: Require resident keys (discoverable credentials)? (Recommendation: Preferred, not required)
|
||||
|
||||
3. **Backup Credential Policy**: Allow synced passkeys (iCloud Keychain, Google Password Manager)? (Recommendation: Yes, allow)
|
||||
|
||||
4. **Account Recovery**: How should users recover if they lose all passkeys? (Recommendation: Email verification + temporary password)
|
||||
|
||||
5. **2FA Replacement**: Should WebAuthn replace TOTP for 2FA? (Recommendation: Offer both, user choice)
|
||||
|
||||
6. **Enforcement Timeline**: When should we require passkeys for admins? (Recommendation: 3 months after launch)
|
||||
|
||||
7. **Cross-Platform Keys**: Encourage users to register both platform and roaming authenticators? (Recommendation: Yes, show prompt)
|
||||
|
||||
8. **Audit Logging**: Log all WebAuthn events? (Recommendation: Yes, use Rails ActiveSupport::Notifications)
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Ruby Gems
|
||||
- `webauthn` (~> 3.0) - WebAuthn server library
|
||||
- `base64` (stdlib) - Encoding/decoding credentials
|
||||
|
||||
### JavaScript Libraries
|
||||
- Native WebAuthn API (no libraries needed)
|
||||
- Stimulus controller for UX
|
||||
|
||||
### Browser Requirements
|
||||
- WebAuthn API support
|
||||
- HTTPS (required in production)
|
||||
- Modern browser (Chrome 90+, Firefox 90+, Safari 14+)
|
||||
|
||||
---
|
||||
|
||||
## Success Metrics
|
||||
|
||||
### Adoption Metrics
|
||||
- % of users with at least one passkey registered
|
||||
- % of logins using passkey vs password
|
||||
- Time to register passkey (UX metric)
|
||||
|
||||
### Security Metrics
|
||||
- Reduction in password reset requests
|
||||
- Reduction in account takeover attempts
|
||||
- Phishing resistance (passkeys can't be phished)
|
||||
|
||||
### Performance Metrics
|
||||
- Average authentication time (should be faster)
|
||||
- Error rate during registration/authentication
|
||||
- Browser compatibility issues
|
||||
|
||||
---
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Post-Launch Improvements
|
||||
1. **Conditional UI**: Show passkey option only if user has credentials for that device
|
||||
2. **Cross-Device Flow**: QR code to authenticate on one device, complete login on another
|
||||
3. **Passkey Sync Status**: Show which passkeys are synced vs device-only
|
||||
4. **Authenticator Icons**: Display icons for known authenticators (YubiKey, etc.)
|
||||
5. **Security Key Attestation**: Verify hardware security keys for high-security apps
|
||||
6. **Multi-Device Registration**: Easy workflow to register passkey on multiple devices
|
||||
7. **Admin Analytics**: Dashboard showing WebAuthn adoption and usage stats
|
||||
8. **FIDO2 Compliance**: Full FIDO2 conformance certification
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
### Specifications
|
||||
- [W3C WebAuthn Level 2](https://www.w3.org/TR/webauthn-2/)
|
||||
- [FIDO2 Overview](https://fidoalliance.org/fido2/)
|
||||
- [WebAuthn Guide](https://webauthn.guide/)
|
||||
|
||||
### Ruby Libraries
|
||||
- [webauthn-ruby gem](https://github.com/cedarcode/webauthn-ruby)
|
||||
- [webauthn-ruby documentation](https://github.com/cedarcode/webauthn-ruby#usage)
|
||||
|
||||
### Browser APIs
|
||||
- [MDN: Web Authentication API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API)
|
||||
- [Chrome: WebAuthn](https://developer.chrome.com/docs/devtools/webauthn/)
|
||||
|
||||
### Best Practices
|
||||
- [FIDO2 Server Best Practices](https://fidoalliance.org/specifications/)
|
||||
- [WebAuthn Awesome List](https://github.com/herrjemand/awesome-webauthn)
|
||||
|
||||
---
|
||||
|
||||
## Appendix A: File Changes Summary
|
||||
|
||||
### New Files
|
||||
- `app/models/webauthn_credential.rb`
|
||||
- `app/controllers/webauthn_controller.rb`
|
||||
- `app/javascript/controllers/webauthn_controller.js`
|
||||
- `app/views/webauthn/new.html.erb`
|
||||
- `app/views/webauthn/show.html.erb`
|
||||
- `config/initializers/webauthn.rb`
|
||||
- `db/migrate/YYYYMMDD_create_webauthn_credentials.rb`
|
||||
- `db/migrate/YYYYMMDD_add_webauthn_to_users.rb`
|
||||
- `test/models/webauthn_credential_test.rb`
|
||||
- `test/controllers/webauthn_controller_test.rb`
|
||||
- `test/integration/webauthn_authentication_test.rb`
|
||||
- `test/system/webauthn_test.rb`
|
||||
- `docs/webauthn-user-guide.md`
|
||||
- `docs/webauthn-admin-guide.md`
|
||||
- `docs/webauthn-developer-guide.md`
|
||||
|
||||
### Modified Files
|
||||
- `Gemfile` - Add webauthn gem
|
||||
- `app/models/user.rb` - Add webauthn associations and methods
|
||||
- `app/controllers/sessions_controller.rb` - Add webauthn authentication
|
||||
- `app/views/sessions/new.html.erb` - Add "Sign in with Passkey" button
|
||||
- `app/views/profiles/show.html.erb` - Add passkey management section
|
||||
- `app/controllers/oidc_controller.rb` - Add AMR claim support
|
||||
- `config/routes.rb` - Add webauthn routes
|
||||
- `README.md` - Document WebAuthn feature
|
||||
|
||||
### Database Migrations
|
||||
1. Create `webauthn_credentials` table
|
||||
2. Add `webauthn_id` and `webauthn_required` to `users` table
|
||||
|
||||
---
|
||||
|
||||
## Appendix B: Example User Flows
|
||||
|
||||
### Flow 1: Register First Passkey
|
||||
1. User logs in with password
|
||||
2. Sees banner: "Secure your account with a passkey"
|
||||
3. Clicks "Set up passkey"
|
||||
4. Browser prompts: "Save a passkey for auth.example.com?"
|
||||
5. User authenticates with Touch ID
|
||||
6. Success message: "Passkey registered as 'MacBook Touch ID'"
|
||||
|
||||
### Flow 2: Sign In with Passkey
|
||||
1. User visits login page
|
||||
2. Enters email address
|
||||
3. Clicks "Continue with Passkey"
|
||||
4. Browser prompts: "Sign in to auth.example.com with your passkey?"
|
||||
5. User authenticates with Touch ID
|
||||
6. Immediately signed in, redirected to dashboard
|
||||
|
||||
### Flow 3: WebAuthn as 2FA
|
||||
1. User enters password (first factor)
|
||||
2. Instead of TOTP, prompted for passkey
|
||||
3. User authenticates with Face ID
|
||||
4. Signed in successfully
|
||||
|
||||
### Flow 4: Cross-Device Authentication
|
||||
1. User on desktop enters email
|
||||
2. Clicks "Use passkey from phone"
|
||||
3. QR code displayed
|
||||
4. User scans with phone, authenticates
|
||||
5. Desktop session created
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
This plan provides a comprehensive roadmap for adding WebAuthn/Passkeys to Clinch. The phased approach allows for iterative development, testing, and rollout while maintaining backward compatibility with existing authentication methods.
|
||||
|
||||
**Key Benefits**:
|
||||
- Enhanced security (phishing-resistant)
|
||||
- Better UX (faster, no passwords to remember)
|
||||
- Modern authentication standard (FIDO2)
|
||||
- Cross-platform support (iOS, Android, Windows, macOS)
|
||||
- Synced passkeys (iCloud, Google Password Manager)
|
||||
|
||||
**Estimated Timeline**: 4-6 weeks for full implementation and testing.
|
||||
|
||||
**Next Steps**:
|
||||
1. Review and approve this plan
|
||||
2. Create GitHub issues for each phase
|
||||
3. Begin Phase 1 implementation
|
||||
4. Set up development environment for testing
|
||||
|
||||
---
|
||||
|
||||
*Document Version: 1.0*
|
||||
*Last Updated: 2025-10-26*
|
||||
*Author: Claude (Anthropic)*
|
||||
*Status: Awaiting Review*
|
||||
Reference in New Issue
Block a user