Complete SSO Workflow & Debugging Guide

Step-by-step workflow for implementing, debugging, and maintaining RegardingWork Hub SSO

Complete SSO Authentication Flow

✅ Successful SSO Flow
  1. User Action: Clicks "Login with RegardingWork Hub" on your service
  2. Redirect: Browser goes to hub.regardingwork.com/api/auth/sso/authorize?redirect_uri=your-callback
  3. Domain Check: Hub validates your domain is in the allowed SSO domains list
  4. Authentication Check: Hub checks if user is logged in
  5. Token Generation: Hub generates JWT access token for authenticated user
  6. Callback Redirect: Hub redirects to your callback URL with token parameters
  7. Token Validation: Your service validates the token with Hub's validate endpoint
  8. User Login: Your service logs in the user based on validated token
Expected Result: User seamlessly logged into your service with one click!
🔗 Key URLs
SSO Authorize:
hub.regardingwork.com/api/auth/sso/authorize

Token Validation:
hub.regardingwork.com/api/auth/validate

Your Callback:
your-domain.com/auth/callback

Common SSO Errors & How to Debug Them

❌ Error: "Invalid redirect_uri domain: your-domain.com"

What this means: Hub doesn't recognize your domain as authorized for SSO

Why it happens: Your domain isn't in the Hub's SSO domains database

🔧 Solution:
  1. Ask Hub admin to add your domain via /admin/sso-domains
  2. Or add it yourself if you have admin access
  3. Make sure to use exact domain match (no https://, no trailing /)
❌ Error: "SSO authorization failed"

What this means: Domain was accepted but something crashed during authorization

Common causes: Missing imports, user not logged into Hub, token generation failure

🔧 Solution Steps:
  1. Check if logged in: Make sure you're logged into hub.regardingwork.com first
  2. Check production logs: Go to Replit Deployments → Logs tab for exact error
  3. Common fix: Add missing from auth_service import AuthService imports
  4. Verify database: Check if production has database connection issues
⚠️ Result: 404 on Callback URL

What this means: SSO worked perfectly! Your service just needs to build the callback handler

Why it happens: Hub successfully generated token and redirected, but your service doesn't have /auth/callback endpoint yet

🎉 This is Good News! Your Hub SSO system is working correctly. You just need to implement the callback on your service side.
ℹ️ Error: "Please log in to hub.regardingwork.com first"

What this means: User isn't authenticated to Hub yet

This is good UX! Clear message telling user exactly what to do

✅ User Action Required:
  1. Go to hub.regardingwork.com/login
  2. Login with Hub credentials
  3. Return and try the SSO URL again

Step-by-Step Debugging Process

🔍 When SSO Isn't Working, Follow This Process:
Phase 1: Test the SSO URL
  1. Test basic SSO URL:
    hub.regardingwork.com/api/auth/sso/authorize?redirect_uri=https://your-domain.com/auth/callback
  2. Check error message type:
    • "Invalid domain" → Domain not whitelisted
    • "SSO authorization failed" → Check logs
    • "Please log in" → User not authenticated
    • 404 on callback → SSO working, need callback
Phase 2: Check Environment
  1. Verify deployment status:
    Make sure latest code is deployed to production
  2. Check database domains:
    Visit /admin/sso-domains to see allowed domains
  3. Review production logs:
    Replit Deployments → Logs tab for exact errors
Pro Tip: Error Message Analysis

Pay attention to how error messages change as you fix issues:

  • "Invalid domain" → "SSO authorization failed" = Domain fix worked, now check authentication
  • "SSO authorization failed" → 404 on callback = Authentication fix worked, now build callback

Production vs Development Environment Issues

✅ Development (localhost:5000)
  • ✅ Database-driven SSO domains
  • ✅ All RegardingWork domains working
  • ✅ Enhanced logging active
  • ✅ Latest code changes
Test URL:
localhost:5000/api/auth/sso/authorize?redirect_uri=https://premium.regardingwork.com/auth/callback
❌ Production (hub.regardingwork.com)

Common Issue: Production environment missing recent code updates

  • ❌ Using old hardcoded domain system
  • ❌ Missing database domain queries
  • ❌ Missing AuthService imports
  • ❌ Outdated error handling
🚀 Solution: Deploy development changes to production!
Deployment Checklist
  1. Code: Deploy latest SSO fixes to production
  2. Database: Add missing domains to production database
  3. Test: Verify SSO URLs work on production
  4. Monitor: Check production logs for any new errors

SSO Domain Management & Admin Tools

🛠️ Administrative Actions
Add New SSO Domain

Go to SSO Domain Management to add new domains

Required for each new RegardingWork service that needs SSO authentication
View Current Domains

Current production domains should include:

  • premium.regardingwork.com
  • game.regardingwork.com
  • display.regardingwork.com
  • ce.regardingwork.com
  • family.regardingwork.com
  • desk.regardingwork.com
  • teams.regardingwork.com
Diagnostic Tools

Use Diagnostics Dashboard to:

  • View production vs development database status
  • Test SSO domain validation
  • Check authentication service health
  • Add missing domains with one click
Quick Admin Links
Manage SSO Domains System Diagnostics User Management

Service Integration Template

📝 For New RegardingWork Services

Use this template when adding SSO to a new service:

<!-- Replace login form with SSO button -->
<a href="https://hub.regardingwork.com/api/auth/sso/authorize?redirect_uri=https://YOUR-DOMAIN.com/auth/callback&service=YOUR-SERVICE-NAME" class="btn btn-primary btn-lg">
  <i data-feather="shield" class="me-2"></i>
  Login with RegardingWork Hub
</a>
Replace YOUR-DOMAIN.com with your service domain and YOUR-SERVICE-NAME with your service identifier

# Example Python/Flask callback handler
@app.route('/auth/callback')
def auth_callback():
    token = request.args.get('token')
    user_id = request.args.get('user_id')
    username = request.args.get('username')

    if not token:
        return redirect('/login?error=no_token')

    # Validate token with Hub
    response = requests.get(
        'https://hub.regardingwork.com/api/auth/validate',
        headers={'Authorization': f'Bearer {token}'}
    )

    if response.ok:
        # Success! Log user in
        session['hub_token'] = token
        session['user_id'] = user_id
        session['username'] = username
        return redirect('/dashboard')
    else:
        return redirect('/login?error=invalid_token')

  1. Add Domain: Go to /admin/sso-domains
  2. Enter Domain: your-service.regardingwork.com (no protocol, no trailing slash)
  3. Add Description: "Your Service Name - Description"
  4. Test SSO URL: Try the complete flow with your callback URL
  5. Monitor: Check both Hub and your service logs for any issues

Testing & Validation

🧪 Test Your SSO Integration
  1. Test the SSO URL manually:
    Visit: hub.regardingwork.com/api/auth/sso/authorize?redirect_uri=https://YOUR-DOMAIN.com/auth/callback
  2. Expected success flow:
    • Domain accepted ✅
    • User redirected to login if needed ✅
    • Token generated and callback executed ✅
  3. Test error scenarios:
    • User not logged into Hub
    • Invalid callback URL
    • Token validation failure
✅ Success Indicators
When SSO is Working Correctly:
  • No "Invalid domain" errors
  • Users get redirected to your callback with token parameters
  • Token validation returns user data
  • Users are logged into your service automatically
Remember:
  • 404 on your callback = SSO working, build your handler
  • Always validate tokens received from SSO
  • Handle authentication gracefully
  • Provide clear error messages to users
Full SSO Integration Guide Manage SSO Domains