GitHubSupport

Third-Party Integration Guide

SSO v5.24.0

Complete guide for integrating SSO into your application

📖 Full Integration Guide

The comprehensive Third-Party Integration Guide covers everything you need to integrate SSO into your application:

  • OAuth2/OIDC Integration - Complete authorization code flow with PKCE
  • App-Level Permissions - NEW in v5.24.0: Manage user roles per app
  • Cookie-Based SSO - Simple subdomain integration
  • Social Login - Facebook, Google (coming soon)
  • Token Management - Access tokens, refresh tokens, ID tokens
  • Security Best Practices - PKCE, CSRF protection, token rotation

🎯 NEW: App-Level Permissions (v5.24.0)

Multi-App Authorization is now available! SSO provides centralized permission management for all integrated applications. Learn how to:

  • Query user's app-specific role (user/admin/superadmin)
  • Store app permissions in your session
  • Control access based on roles
  • Sync permissions in real-time
  • Handle pending approval workflows

📥 Download Guide

The complete integration guide is available as a markdown file:

docs/THIRD_PARTY_INTEGRATION_GUIDE.md

Location: /Users/moldovancsaba/Projects/sso/docs/THIRD_PARTY_INTEGRATION_GUIDE.md

Version: 5.24.0 (Last updated: 2025-11-09)

Size: ~900 lines | Comprehensive with code examples

🚀 Quick Start

For a quick integration example, see:

📚 Table of Contents

  1. Overview - What you get with SSO
  2. Integration Methods - Choose the right approach
  3. OAuth2/OIDC - Complete OAuth integration
    • Register OAuth client
    • Implement OAuth flow with PKCE
    • Token management (access, refresh, ID tokens)
    • Logout and token revocation
  4. App-Level Permissions - NEW! Multi-app authorization
    • Query user's app permission
    • Request app access
    • Use role for authorization
    • Periodic permission sync
    • Access denied pages
    • Complete integration example
  5. Cookie-Based SSO - Subdomain integration
  6. Social Login - Facebook/Google integration
  7. API Reference - All endpoints
  8. Security Best Practices - Production checklist
  9. Troubleshooting - Common issues and solutions

💡 Real-World Example

The Camera app integration is a reference implementation showing:

  • OAuth2 callback with permission check
  • Session storage with app role
  • Admin UI conditional rendering
  • Access denied page

See commit ae26e49 in the Camera repository for the full implementation.

🔧 Integration Steps Summary

// 1. OAuth Callback - Exchange code for tokens
const tokens = await exchangeCodeForToken(code, codeVerifier);

// 2. Extract user from ID token
const user = decodeIdToken(tokens.id_token);

// 3. Query SSO for app permission (NEW in v5.24.0)
const permission = await getAppPermission(user.id, tokens.access_token);

// 4. Check if user has access
if (!permission.hasAccess) {
  if (permission.status === 'pending') {
    return redirectTo('/access-pending');
  } else {
    await requestAppAccess(user.id, tokens.access_token);
    return redirectTo('/access-pending');
  }
}

// 5. Store app role in session
await createSession(user, tokens, {
  appRole: permission.role,  // 'user', 'admin', or 'superadmin'
  appAccess: permission.hasAccess,
});

// 6. Redirect to app
return redirectTo('/dashboard');

📞 Support

Need help with integration?