Standardized Authentication Guide

Choose the right authentication method for your RegardingWork app

Authentication Method Selector

Your App Needs Method Complexity Integration Time Status
Simple web login Simple SSO Low 1-2 hours ✅ Working
Quick implementation Simple SSO Low 1-2 hours ✅ Working
Mobile app OAuth 2.0 High 4-8 hours ⚠️ Complex
Advanced security OAuth 2.0 High 4-8 hours ⚠️ Complex

Method 1: Simple SSO (Recommended)

Best for: Most web applications, simple integration

Used by: desk.regardingwork.com (working ✅)

Benefits: Fast implementation, reliable, easy to debug

Success Rate: 100%
Integration Time: 1-2 hours
Maintenance: Low
Step 1: Replace Login Forms
❌ Remove This:
<form action="/api/auth/login" method="POST">
  <input name="username" type="text">
  <input name="password" type="password">
  <button type="submit">Login</button>
</form>
✅ Add This:
<button onclick="loginWithHub()" class="btn btn-primary">
  <i class="fas fa-shield-alt me-2"></i>
  Login with RegardingWork Hub
</button>
Step 2: JavaScript Implementation
function loginWithHub() {
  // Build callback URL for your app
  const callbackUrl = encodeURIComponent(`${window.location.origin}/auth/sso/callback`);
  
  // Redirect to Hub SSO
  window.location.href = `https://hub.regardingwork.com/api/auth/sso/authorize?redirect_uri=${callbackUrl}&service=YOUR_APP_NAME`;
}
Step 3: Backend Callback Handler
# Python/Flask example
@app.route('/auth/sso/callback')
def sso_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_data = response.json()['user']
      
      # Auto-create user if doesn't exist
      local_user = User.query.filter_by(hub_user_id=user_id).first()
      if not local_user:
        local_user = User(
          hub_user_id=user_id,
          username=username,
          email=user_data.get('email'),
          created_via='hub_sso'
        )
        db.session.add(local_user)
        db.session.commit()

      # Log user in
      session['hub_token'] = token
      session['user_id'] = user_id
      session['username'] = username
      return redirect('/dashboard')

  return redirect('/login?error=auth_failed')
Simple SSO Success Stories:
  • desk.regardingwork.com: Integrated successfully in 2 hours
  • Domain validation: Fixed and working reliably
  • Token flow: Stable and well-tested

Method 2: OAuth 2.0 with PKCE (Advanced)

Best for: Mobile apps, advanced security requirements

Used by: ce.regardingwork.com (recently fixed)

Benefits: Industry standard, maximum security, refresh tokens

Complexity: High
Integration Time: 4-8 hours
Maintenance: Medium
When to Use OAuth 2.0:
  • You're building a mobile application
  • You need refresh token functionality
  • You have advanced security requirements
  • You want to follow OAuth 2.1 standards
Step 1: Generate PKCE Parameters
// Generate PKCE code verifier and challenge
async function generatePKCE() {
  const codeVerifier = btoa(String.fromCharCode(...crypto.getRandomValues(new Uint8Array(32))))
    .replace(/[+/=]/g, '');

  const encoder = new TextEncoder();
  const data = encoder.encode(codeVerifier);
  const hash = await crypto.subtle.digest('SHA-256', data);

  const codeChallenge = btoa(String.fromCharCode(...new Uint8Array(hash)))
    .replace(/[+/=]/g, '');

  return { codeVerifier, codeChallenge };
}
Step 2: Authorization Request
async function loginWithOAuth() {
  const { codeVerifier, codeChallenge } = await generatePKCE();
  sessionStorage.setItem('code_verifier', codeVerifier);

  const params = new URLSearchParams({
    response_type: 'code',
    client_id: 'your_app_name',
    redirect_uri: `${window.location.origin}/auth/oauth/callback`,
    scope: 'read profile',
    code_challenge: codeChallenge,
    code_challenge_method: 'S256',
    state: Math.random().toString(36)
  });

  window.location.href = `https://hub.regardingwork.com/api/oauth/authorize?${params}`;
}
Step 3: Token Exchange
@app.route('/auth/oauth/callback')
def oauth_callback():
  code = request.args.get('code')
  state = request.args.get('state')

  if not code:
    return redirect('/login?error=oauth_failed')

  # Exchange code for token
  token_data = {
    'grant_type': 'authorization_code',
    'code': code,
    'redirect_uri': f'{request.url_root}auth/oauth/callback',
    'client_id': 'your_app_name',
    'code_verifier': session.get('code_verifier')
  }

  response = requests.post(
    'https://hub.regardingwork.com/api/oauth/token',
    data=token_data
  )

  if response.ok:
    tokens = response.json()
    session['access_token'] = tokens['access_token']
    session['refresh_token'] = tokens['refresh_token']
    session['user_data'] = tokens['user']
    return redirect('/dashboard')

  return redirect('/login?error=token_exchange_failed')
OAuth 2.0 Considerations:
  • Complexity: Requires PKCE implementation and state management
  • Debugging: More failure points (authorization, token exchange, refresh)
  • Recent fixes: Hub-side token generation issues have been resolved

Critical Issues & Solutions

🚫 What NOT to Do:
  • ❌ Don't create separate user databases with passwords
  • ❌ Don't handle password authentication locally
  • ❌ Don't ignore token validation
  • ❌ Don't hardcode authentication URLs
  • ❌ Don't maintain multiple authentication systems
✅ What TO Do:
  • ✅ Use Hub as single source of truth
  • ✅ Validate all tokens with Hub
  • ✅ Auto-create users from Hub data
  • ✅ Handle authentication errors gracefully
  • ✅ Follow the standardized patterns
Need Help Debugging?

Check our comprehensive troubleshooting guide for step-by-step solutions:

View Troubleshooting Guide

Implementation Checklist

For Simple SSO:
For OAuth 2.0:
For Both Methods:

Related Documentation

Troubleshooting:
Implementation:
API Reference: