OAuth 2.0 Integration

Standard OAuth 2.0 authentication for external services and applications.

Overview

RegardingWork Hub supports standard OAuth 2.0 Authorization Code flow with PKCE (Proof Key for Code Exchange) for secure integration with external services.

✅ Supported Features
  • ✓ Authorization Code Grant
  • ✓ PKCE Security Extension
  • ✓ State Parameter
  • ✓ Standard Token Response
🔗 Supported Services
  • ✓ ce.regardingwork.com
  • ✓ game.regardingwork.com
  • ✓ premium.regardingwork.com
  • ✓ display.regardingwork.com

Quick Start

1. Authorization Request

Redirect users to Hub for authentication:

https://hub.regardingwork.com/api/oauth/authorize?
  client_id=your_service&
  response_type=code&
  scope=profile email&
  redirect_uri=https://your-service.com/callback&
  state=random_state_value&
  code_challenge=PKCE_challenge&
  code_challenge_method=S256
2. Token Exchange

Exchange authorization code for access token:

POST /api/oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "auth_code_from_callback",
  "redirect_uri": "https://your-service.com/callback",
  "code_verifier": "PKCE_verifier"
}

OAuth Endpoints

Authorization Endpoint
GET
/api/oauth/authorize

Initiates OAuth flow and redirects to login if needed.

Token Endpoint
POST
/api/oauth/token

Exchanges authorization code for access tokens.

Integration Patterns

Authorization Code Flow

Standard OAuth 2.0 flow for web applications with server-side token exchange.

Learn More
PKCE Security

Enhanced security for public clients using Proof Key for Code Exchange.

Learn More
Service Integration

Complete integration guide for RegardingWork ecosystem services.

View Guide

Example Implementation

Authentication Note: When users reach the Hub login page during OAuth flow, they must use their USERNAME (not email) to log in.
JavaScript Example (ce.regardingwork.com)
// Generate PKCE challenge
function generatePKCE() {
    const codeVerifier = btoa(Array.from(crypto.getRandomValues(new Uint8Array(32)), b => String.fromCharCode(b)).join(''));
    const codeChallenge = btoa(String.fromCharCode.apply(null, new Uint8Array(
        crypto.subtle.digest('SHA-256', new TextEncoder().encode(codeVerifier))
    ))).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
    
    return { codeVerifier, codeChallenge };
}

// Initiate OAuth flow
function startOAuthFlow() {
    const { codeVerifier, codeChallenge } = generatePKCE();
    const state = crypto.randomUUID();
    
    // Store for later use
    sessionStorage.setItem('oauth_code_verifier', codeVerifier);
    sessionStorage.setItem('oauth_state', state);
    
    // Redirect to Hub
    const params = new URLSearchParams({
        client_id: 'ce',
        response_type: 'code',
        scope: 'profile email',
        redirect_uri: 'https://ce.regardingwork.com/api/auth/callback',
        state: state,
        code_challenge: codeChallenge,
        code_challenge_method: 'S256'
    });
    
    window.location.href = `https://hub.regardingwork.com/api/oauth/authorize?${params}`;
}

// Handle OAuth callback
async function handleOAuthCallback(code, state) {
    const storedState = sessionStorage.getItem('oauth_state');
    const codeVerifier = sessionStorage.getItem('oauth_code_verifier');
    
    if (state !== storedState) {
        throw new Error('Invalid state parameter');
    }
    
    // Exchange code for tokens
    const response = await fetch('https://hub.regardingwork.com/api/oauth/token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            grant_type: 'authorization_code',
            code: code,
            redirect_uri: 'https://ce.regardingwork.com/api/auth/callback',
            code_verifier: codeVerifier
        })
    });
    
    const tokens = await response.json();
    
    // Store tokens securely
    localStorage.setItem('access_token', tokens.access_token);
    localStorage.setItem('refresh_token', tokens.refresh_token);
    
    return tokens;
}

Security Considerations

✅ Best Practices
  • ✓ Always use HTTPS for OAuth endpoints
  • ✓ Implement PKCE for public clients
  • ✓ Validate state parameter
  • ✓ Store tokens securely
  • ✓ Handle token expiration
⚠️ Security Warnings
  • ⚠️ Never expose client secrets in frontend
  • ⚠️ Validate redirect URIs server-side
  • ⚠️ Authorization codes expire in 5 minutes
  • ⚠️ Don't log sensitive parameters
  • ⚠️ Implement proper CORS policies

Related Documentation

JWT Tokens
View Spec
SSO Integration
View Guide
Authentication
View Docs
Quick Start
Get Started