OAuth Web Redirect

Implement end-user OAuth redirects, callbacks, session verification, and a React login

AuthOS release 0.8.2 TypeScript SDK 0.8.0 Latest-only documentation
Updated Jul 15, 2026 Edit this page
On this page

Complete the authentication flow prerequisites before starting this browser flow.

End-User OAuth Login (Web Redirect Flow)

The most common authentication flow for web applications. Users authenticate using OAuth providers (GitHub, Google, Microsoft) configured by your organization.

Step 1: Initialize the SDK

import { SsoClient } from '@drmhse/sso-sdk';

const sso = new SsoClient({
  baseURL: 'https://sso.example.com'
});

Step 2: Redirect User to OAuth Provider

// Generate the OAuth login URL
const loginUrl = sso.auth.getLoginUrl('github', {
  org: 'acme-corp',
  service: 'main-app',
  redirect_uri: 'https://app.acme.com/callback'
});

// Redirect the user to authenticate
window.location.href = loginUrl;

Supported Providers:

  • github - GitHub OAuth
  • google - Google OAuth
  • microsoft - Microsoft OAuth

Step 3: Handle the Callback

After successful authentication, the user is redirected back to your redirect_uri with tokens in the URL fragment (after #).

Security Note: Tokens are passed in the URL fragment rather than query parameters to prevent them from being logged in server access logs.

// In your callback route handler (e.g., /callback)
function handleOAuthCallback() {
  // Parse tokens from URL fragment (after #)
  const hashParams = new URLSearchParams(window.location.hash.substring(1));
  const accessToken = hashParams.get('access_token');
  const refreshToken = hashParams.get('refresh_token');

  if (!accessToken || !refreshToken) {
    console.error('Authentication failed - no tokens received');
    window.location.href = '/login';
    return;
  }

  // Store tokens securely
  localStorage.setItem('sso_access_token', accessToken);
  localStorage.setItem('sso_refresh_token', refreshToken);

  // Set the token in the SDK for future requests
  sso.setAuthToken(accessToken);

  // Clear the hash from URL for security
  window.history.replaceState(null, '', window.location.pathname);

  // Redirect to the main application
  window.location.href = '/dashboard';
}

Step 4: Verify Authentication

// Fetch the authenticated user's profile
try {
  const profile = await sso.user.getProfile();
  console.log('Logged in as:', profile.email);
  console.log('Organization:', profile.org);
  console.log('Service:', profile.service);
} catch (error) {
  console.error('Failed to fetch profile:', error);
  // Token invalid - redirect to login
  window.location.href = '/login';
}

Complete Example: React Login Component

import { useEffect } from 'react';
import { SsoClient, SsoApiError } from '@drmhse/sso-sdk';

const sso = new SsoClient({
  baseURL: process.env.REACT_APP_SSO_URL
});

export function LoginPage() {
  const handleLogin = (provider: 'github' | 'google' | 'microsoft') => {
    const loginUrl = sso.auth.getLoginUrl(provider, {
      org: 'acme-corp',
      service: 'main-app',
      redirect_uri: `${window.location.origin}/callback`
    });
    window.location.href = loginUrl;
  };

  return (
    <div className="login-page">
      <h1>Sign In</h1>
      <button onClick={() => handleLogin('github')}>
        Sign in with GitHub
      </button>
      <button onClick={() => handleLogin('google')}>
        Sign in with Google
      </button>
      <button onClick={() => handleLogin('microsoft')}>
        Sign in with Microsoft
      </button>
    </div>
  );
}

export function CallbackPage() {
  useEffect(() => {
    // Parse tokens from URL fragment (after #) - not query params
    const hashParams = new URLSearchParams(window.location.hash.substring(1));
    const accessToken = hashParams.get('access_token');
    const refreshToken = hashParams.get('refresh_token');

    if (accessToken && refreshToken) {
      localStorage.setItem('sso_access_token', accessToken);
      localStorage.setItem('sso_refresh_token', refreshToken);
      sso.setAuthToken(accessToken);
      // Clear hash from URL for security
      window.history.replaceState(null, '', window.location.pathname);
      window.location.href = '/dashboard';
    } else {
      window.location.href = '/login';
    }
  }, []);

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