useSSOCallback()

Handle OAuth callback flows and SSO authentication completion

The useSSOCallback and useSSORedirect hooks handle OAuth provider callbacks and manage the authentication flow after users return from external OAuth providers.

Import

import { useSSOCallback, useSSORedirect } from '@snipextt/wacht';

Hooks Overview

useSSOCallback

Automatically processes OAuth callback parameters and handles authentication completion.

import { useSSOCallback } from '@snipextt/wacht';

function OAuthCallbackPage() {
  const {
    loading,
    error,
    session,
    redirectUri,
    processed,
    requiresCompletion,
    requiresVerification,
    requires2FA,
    completeOAuthSignup,
    completeVerification
  } = useSSOCallback({
    onSuccess: (session, redirectUri) => {
      console.log('OAuth successful', session);
      // Handle successful authentication
    },
    onError: (error) => {
      console.error('OAuth failed', error);
    },
    onRequiresCompletion: (signupAttempt, session) => {
      console.log('Additional info needed');
    },
    autoRedirect: true
  });

  if (loading) {
    return <div>Processing authentication...</div>;
  }

  if (error) {
    return (
      <div>
        <h2>Authentication Failed</h2>
        <p>{error.message}</p>
        <a href="/signin">Try Again</a>
      </div>
    );
  }

  if (requiresCompletion) {
    return <ProfileCompletionForm onComplete={completeOAuthSignup} />;
  }

  if (requiresVerification) {
    return <VerificationForm onVerify={completeVerification} />;
  }

  if (requires2FA) {
    return <TwoFactorForm />;
  }

  return <div>Redirecting...</div>;
}

useSSORedirect

Provides manual control over SSO redirects.

import { useSSORedirect } from '@snipextt/wacht';

function SSORedirectHandler() {
  const { redirect } = useSSORedirect();

  const handleRedirect = () => {
    // Redirect to a custom URL
    redirect('https://myapp.com/dashboard');
    
    // Or redirect to default location
    redirect();
  };

  return (
    <button onClick={handleRedirect}>
      Continue to App
    </button>
  );
}

Properties

useSSOCallback

loading · boolean

Whether the OAuth callback is being processed

error · Error | null

Any error that occurred during OAuth processing

session · Session | null

The authenticated session after successful OAuth

redirectUri · string | null

The redirect URI to navigate to after authentication

processed · boolean

Whether the OAuth callback has been processed

signupAttempt · any | null

The signup attempt data if additional info is needed

signinAttempt · any | null

The signin attempt data if 2FA is required

requiresCompletion · boolean

Whether profile completion is required

requiresVerification · boolean

Whether email/phone verification is required

requires2FA · boolean

Whether two-factor authentication is required

completionLoading · boolean

Whether a completion operation is in progress

completionError · Error | null

Any error from completion operations

Options

SSOCallbackOptions

onSuccess · (session: Session, redirectUri?: string) => void

Callback when OAuth authentication is successful

onError · (error: Error) => void

Callback when OAuth authentication fails

onRequiresCompletion · (signupAttempt: any, session: Session) => void

Callback when additional profile information is needed

autoRedirect · boolean

Whether to automatically redirect after successful authentication. Default: true

Methods

completeOAuthSignup()

Completes OAuth signup with additional profile information.

data · OAuthCompletionData · required

Additional profile data required for signup

const { completeOAuthSignup } = useSSOCallback();

const success = await completeOAuthSignup({
  first_name: 'John',
  last_name: 'Doe',
  username: 'johndoe',
  phone_number: '[phone]'
});

completeVerification()

Completes verification with the provided code.

code · string · required

The verification code

const { completeVerification } = useSSOCallback();

const success = await completeVerification('123456');

prepareVerification()

Prepares verification for a specific strategy.

strategy · string · required

The verification strategy (email_otp, phone_otp)

const { prepareVerification } = useSSOCallback();

const success = await prepareVerification('email_otp');

redirect()

Manually redirects after OAuth completion.

customRedirectUri · string

Optional custom redirect URI

const { redirect } = useSSORedirect();

// Redirect to custom URL
redirect('https://myapp.com/welcome');

// Redirect to default location
redirect();

Examples

Complete OAuth Flow with Profile Completion

function OAuthCallbackHandler() {
  const {
    loading,
    error,
    requiresCompletion,
    signupAttempt,
    completeOAuthSignup,
    completionLoading,
    completionError
  } = useSSOCallback({
    onSuccess: (session, redirectUri) => {
      // Handle successful authentication
      window.location.href = redirectUri || '/dashboard';
    },
    autoRedirect: false // Manual control over redirects
  });

  const handleProfileCompletion = async (e) => {
    e.preventDefault();
    const formData = new FormData(e.target);
    
    const success = await completeOAuthSignup({
      first_name: formData.get('firstName'),
      last_name: formData.get('lastName'),
      username: formData.get('username')
    });
    
    if (success) {
      window.location.href = '/dashboard';
    }
  };

  if (loading) {
    return (
      <div className="oauth-loading">
        <div className="spinner" />
        <p>Completing sign in with your provider...</p>
      </div>
    );
  }

  if (error) {
    return (
      <div className="oauth-error">
        <h2>Authentication Failed</h2>
        <p>{error.message}</p>
        <a href="/signin" className="button">
          Back to Sign In
        </a>
      </div>
    );
  }

  if (requiresCompletion && signupAttempt) {
    return (
      <div className="profile-completion">
        <h2>Complete Your Profile</h2>
        <p>Just a few more details to finish setting up your account.</p>
        
        <form onSubmit={handleProfileCompletion}>
          {signupAttempt.missing_fields?.includes('first_name') && (
            <input
              name="firstName"
              placeholder="First Name"
              required
            />
          )}
          
          {signupAttempt.missing_fields?.includes('last_name') && (
            <input
              name="lastName"
              placeholder="Last Name"
              required
            />
          )}
          
          {signupAttempt.missing_fields?.includes('username') && (
            <input
              name="username"
              placeholder="Username"
              pattern="[a-zA-Z0-9_-]+"
              required
            />
          )}
          
          {completionError && (
            <p className="error">{completionError.message}</p>
          )}
          
          <button type="submit" disabled={completionLoading}>
            {completionLoading ? 'Saving...' : 'Complete Setup'}
          </button>
        </form>
      </div>
    );
  }

  return <div>Redirecting to your dashboard...</div>;
}

OAuth with Verification Flow

function OAuthWithVerification() {
  const {
    requiresVerification,
    signupAttempt,
    completeVerification,
    prepareVerification,
    completionLoading
  } = useSSOCallback();

  const [verificationCode, setVerificationCode] = useState('');
  const [verificationSent, setVerificationSent] = useState(false);

  const handleSendVerification = async () => {
    const strategy = signupAttempt.current_step === 'verify_email' 
      ? 'email_otp' 
      : 'phone_otp';
      
    const success = await prepareVerification(strategy);
    if (success) {
      setVerificationSent(true);
    }
  };

  const handleVerification = async (e) => {
    e.preventDefault();
    const success = await completeVerification(verificationCode);
    
    if (success) {
      // Will auto-redirect or trigger onSuccess callback
    }
  };

  if (!requiresVerification) {
    return null;
  }

  return (
    <div className="verification-required">
      <h2>Verify Your {signupAttempt.current_step === 'verify_email' ? 'Email' : 'Phone'}</h2>
      
      {!verificationSent ? (
        <div>
          <p>We need to verify your contact information.</p>
          <button onClick={handleSendVerification}>
            Send Verification Code
          </button>
        </div>
      ) : (
        <form onSubmit={handleVerification}>
          <input
            type="text"
            value={verificationCode}
            onChange={(e) => setVerificationCode(e.target.value)}
            placeholder="Enter 6-digit code"
            maxLength="6"
            pattern="[0-9]{6}"
            required
          />
          <button type="submit" disabled={completionLoading}>
            {completionLoading ? 'Verifying...' : 'Verify'}
          </button>
        </form>
      )}
    </div>
  );
}

Custom Error Handling

function OAuthErrorBoundary() {
  const [retryCount, setRetryCount] = useState(0);
  
  useSSOCallback({
    onError: (error) => {
      // Log error to monitoring service
      console.error('OAuth Error:', error);
      
      // Handle specific error types
      if (error.message.includes('OAuth Error: access_denied')) {
        // User cancelled OAuth flow
        window.location.href = '/signin';
      } else if (retryCount < 3) {
        // Retry the OAuth flow
        setRetryCount(prev => prev + 1);
        window.location.reload();
      } else {
        // Show error UI after retries exhausted
      }
    },
    onSuccess: (session) => {
      // Reset retry count on success
      setRetryCount(0);
    }
  });

  return <div>Processing authentication...</div>;
}

Notes

• The hook automatically extracts OAuth parameters from the URL
• OAuth errors include both provider errors and application errors
• Profile completion is typically required for OAuth signups missing required fields
• Two-factor authentication may be required based on user security settings
• The hook handles staging mode development sessions automatically
• Auto-redirect can be disabled for manual control over navigation
• Verification flows support both email and phone verification