SSO Integration Guide for Divisions

Standardized Single Sign-On integration for all SphereUs℠ divisions. Implement secure authentication in under 30 minutes.

🚀 Quick Start Checklist

  • 1.Add "Sign in with SphereUs" button to your login page
  • 2.Implement token validation endpoint using code below
  • 3.Store user session and redirect back to your app
  • 4.Test the flow end-to-end
How SSO Works

The SphereUs SSO Flow:

  1. User clicks "Sign in with SphereUs" on your division app
  2. They're redirected to sphereus.com with your return URL
  3. User logs in/signs up at sphereus.com (if not already logged in)
  4. SphereUs verifies membership status and returns user token
  5. User is redirected back to your app with authentication data
  6. Your app validates the token and creates a local session
Step 1: Add SSO Login Button

On your division app's login page, add a button that redirects to SphereUs:

// In your division app
const handleSphereUsLogin = () => {
  const returnUrl = encodeURIComponent(window.location.origin + '/auth/callback');
  window.location.href = `https://sphereus.com/?sso_return=${returnUrl}`;
};

<Button onClick={handleSphereUsLogin}>
  Sign in with SphereUs
</Button>
Step 2: Create Callback Handler

Create a page at /auth/callback to receive the authentication data:

// pages/AuthCallback.js or similar
import { useEffect } from 'react';
import { base44 } from '@/api/base44Client';

export default function AuthCallback() {
  useEffect(() => {
    const params = new URLSearchParams(window.location.search);
    const token = params.get('token');
    const userId = params.get('user_id');
    const email = params.get('email');

    if (token && userId) {
      // Store auth data
      localStorage.setItem('auth_token', token);
      localStorage.setItem('user_id', userId);
      localStorage.setItem('user_email', email);
      
      // Set token for Base44 client
      base44.setToken(token);
      
      // Redirect to your app's dashboard
      window.location.href = '/dashboard';
    } else {
      // Auth failed, redirect to login
      window.location.href = '/login';
    }
  }, []);

  return <div>Authenticating...</div>;
}
Step 3: Verify Membership Status

After authentication, check if the user has an active membership:

// In your protected pages/components
const checkMembershipAccess = async () => {
  try {
    const user = await base44.auth.me();
    
    // Check if user has access
    const hasAccess = 
      user.membership_tier === 'member' || 
      user.membership_tier === 'premium' ||
      user.admin_granted_access === true;
    
    // Check if access hasn't expired
    const accessValid = !user.access_granted_until || 
      new Date(user.access_granted_until) > new Date();
    
    const membershipValid = !user.membership_expires ||
      new Date(user.membership_expires) > new Date();
    
    if (hasAccess && (accessValid || membershipValid)) {
      // User has access - show content
      return true;
    } else {
      // Redirect to pricing/upgrade page
      window.location.href = 'https://sphereus.com/Pricing';
      return false;
    }
  } catch (error) {
    // Not authenticated
    window.location.href = '/login';
    return false;
  }
};
Important Notes

1. Same Base44 Account: Your division app must be on the same Base44 account as SphereUs.com for SSO to work seamlessly.

2. Shared User Database: If all divisions share the same User entity, membership status automatically syncs across all apps.

3. Token Security: Always validate tokens server-side and never expose sensitive operations to the frontend.

4. Membership Checks: Always check both membership_tier AND admin_granted_access for full coverage.

Testing Your Integration
Test Flow 1: Click "Sign in with SphereUs" → Should redirect to sphereus.com → After login, return to your app
Test Flow 2: Try accessing protected features → Should check membership → Redirect to pricing if no access
Test Flow 3: Admin grants you access → Refresh → Protected features should now be accessible
Live SSO Examples in SphereUs Network
SUDS (Support Ticket System):

Users see their support tickets on SphereUs.com dashboard, click "Open SUDS" → auto-login to suds.base44.app

SphereUs Foundation (SUN):

Users donate on SphereUs.com OR click "Foundation Portal" → auto-login to sphereusfoundation.base44.app. Both apps share Donation & Campaign entities.

SSO Button Pattern:

<a
  href="https://yourdivision.base44.app"
  target="_blank"
  rel="noopener noreferrer"
>
  <Button>
    Open Your Division
    <ExternalLink className="w-4 h-4 ml-2" />
  </Button>
</a>

Need Help?

If you run into issues implementing SSO, contact the SphereUs technical team or check the Base44 SSO documentation.

View Base44 Docs