Single Sign-On Integration

Implement seamless authentication with RegardingWork Hub

Current Flow (Bad UX)
  1. User visits Premium service
  2. Sees "Hub Access Token" field
  3. Must manually go to Hub
  4. Login to Hub separately
  5. Copy token from profile
  6. Return to Premium and paste

Result: Terrible user experience with 6 manual steps

SSO Flow (Great UX)
  1. User clicks "Login with RegardingWork Hub"
  2. Gets redirected to Hub (if not logged in)
  3. Automatically redirected back to Premium
  4. User is now authenticated

Result: Seamless experience with 1 click

How to Implement SSO

Step 1: Replace Token Input with SSO Button

Instead of asking users for tokens, add this button to your login page:

<a href="https://hub.regardingwork.com/api/auth/sso/authorize?redirect_uri=https://premium.regardingwork.com/auth/callback&service=premium" class="btn btn-primary btn-lg"> <i class="fas fa-shield-alt me-2"></i> Login with RegardingWork Hub </a>
Step 2: Create Callback Handler

Create a route at /auth/callback to handle the return:

# 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 token:
        # Validate token with Hub
        response = requests.get(
            'https://hub.regardingwork.com/api/auth/validate',
            headers={'Authorization': f'Bearer {token}'}
        )

        if response.ok:
            # User authenticated! Log them in
            session['hub_token'] = token
            session['user_id'] = user_id
            return redirect('/dashboard')

    return redirect('/login?error=auth_failed')

Available SSO Endpoints

Endpoint Method Description
/api/auth/sso/authorize GET Main SSO authorization endpoint - redirect users here
/api/auth/validate GET Validate JWT tokens from SSO callback
/api/auth/me GET Get authenticated user data
/api/auth/sso/token POST Get new token for authenticated user

⚠️ CRITICAL: Common Authentication Issues

Problem: Users Can't Login

Symptom: Users get 401 Unauthorized when trying to login directly to your app

Root Cause: Your app is trying to authenticate against its own database instead of using Hub

Solution: Replace local authentication with SSO or proxy login requests to Hub

Problem: SSO Domain Validation Errors

Symptom: 400 Bad Request - Invalid redirect_uri domain

Solution: Contact Hub admin to add your domain to allowed SSO domains

Valid Domains: premium.regardingwork.com, game.regardingwork.com, display.regardingwork.com, ce.regardingwork.com, desk.regardingwork.com

Problem: User Data Mismatch

Issue: Users exist in Hub but not in your app's database

Solutions:

  • Recommended: Create users automatically during SSO callback
  • Alternative: Sync users periodically from Hub API
  • Avoid: Maintaining separate user databases
Debugging Steps
  1. Test Hub SSO URL: https://hub.regardingwork.com/api/auth/sso/authorize?redirect_uri=YOUR_CALLBACK_URL
  2. Check Domain: Ensure your domain is in the allowed SSO domains list
  3. Verify Callback: Make sure your callback URL actually exists and handles parameters
  4. Validate Token: Always validate tokens received from SSO with Hub's validate endpoint
  5. Handle Errors: Provide clear error messages when authentication fails
Test Credentials
Username: janechen
Password: jane123
Available in: Hub database only

These credentials only work through Hub SSO, not direct app authentication.

Step-by-Step Implementation Guide

🛑 What NOT to do:
  • ❌ Don't create separate user databases
  • ❌ Don't handle passwords locally
  • ❌ Don't ignore SSO token validation
  • ❌ Don't hardcode authentication URLs
✅ What TO do:
  • ✅ Use SSO as primary authentication
  • ✅ Validate all tokens with Hub
  • ✅ Create users automatically from SSO
  • ✅ Handle authentication errors gracefully
Quick Fix Template (JavaScript):
// Replace login form with SSO button
<button onclick="loginWithHub()" class="btn btn-primary">
  Login with RegardingWork Hub
</button>

function loginWithHub() {
  const callbackUrl = encodeURIComponent(window.location.origin + '/auth/callback');
  window.location.href = `https://hub.regardingwork.com/api/auth/sso/authorize?redirect_uri=${callbackUrl}&service=YOUR_APP_NAME`;
}

Test SSO Flow

Test how SSO works by clicking this example button:

Login with RegardingWork Hub (Demo)
Note: This will redirect you to Premium's current login page with authentication parameters. Premium needs to implement the callback handler to complete the flow.
Hub Status: SSO system is working correctly. Domain validation is fixed and ready for integration.