React Integration Guide

This guide shows how to integrate Alien SSO verification and authentication into React applications using the React SDK.

Requirements

React 19.1.1 or higher.
React DOM 19.1.1 or higher.
A modern web browser with JavaScript enabled.
localStorage and sessionStorage support.
A registered provider from the dev portal, with provider address.

Installation


npm install @alien_org/sso-sdk-react

The React SDK automatically includes @alien_org/sso-sdk-core as a dependency.

Setup

Wrap Your App with Provider


import { AlienSsoProvider } from '@alien_org/sso-sdk-react';
 
function App() {
  return (
    <AlienSsoProvider
      config={{
        ssoBaseUrl: 'https://sso.alien-api.com',
        providerAddress: 'your-provider-address'
      }}
    >
      <YourApp />
    </AlienSsoProvider>
  );
}
 
export default App;

Configuration Options

ssoBaseUrl (required): base URL of the SSO service.
providerAddress (required): your provider address from the dev portal.
pollingInterval (optional): polling interval in milliseconds (default: 5000).

Using the useAuth Hook

The useAuth() hook provides access to authentication state and methods.


import { useAuth } from '@alien_org/sso-sdk-react';
 
function Dashboard() {
  const { auth, logout } = useAuth();
 
  if (!auth.isAuthenticated) {
    return <div>Not authenticated</div>;
  }
 
  return (
    <div>
      <p>Session: {auth.tokenInfo?.app_callback_session_address}</p>
      <p>Expires: {new Date(auth.tokenInfo.expired_at * 1000).toLocaleString()}</p>
      <button onClick={logout}>Logout</button>
    </div>
  );
}

Auth State

The auth object contains:


{
  isAuthenticated: boolean;
  token: string | null;
  tokenInfo: {
    app_callback_session_address: string;
    issued_at: number;
    expired_at: number;
  } | null;
}

Available Methods


const {
  client,           // Direct access to AlienSsoClient instance
  auth,             // Authentication state
  queryClient,      // React Query client instance
  generateDeeplink, // Generate authentication deep link
  pollAuth,         // Poll for authentication status
  exchangeToken,    // Exchange authorization code for token
  verifyAuth,       // Verify current token
  logout,           // Clear authentication state
  openModal,        // Open built-in sign-in modal
  closeModal,       // Close sign-in modal
  isModalOpen       // Modal open state
} = useAuth();

Using Pre-built Components

SignInButton

A pre-styled button that opens the sign-in modal.


import { SignInButton } from '@alien_org/sso-sdk-react';
 
function LoginPage() {
  return (
    <div>
      <h1>Welcome</h1>
      <SignInButton />
    </div>
  );
}

SignInModal

The modal is automatically rendered by AlienSsoProvider and handles the complete authentication flow including QR code display and polling.

You can control it via the useAuth() hook:


import { useAuth } from '@alien_org/sso-sdk-react';
 
function CustomButton() {
  const { openModal } = useAuth();
 
  return <button onClick={openModal}>Sign In</button>;
}

Custom Authentication Flow

If you want to implement a custom UI instead of using the built-in modal:


import { useAuth } from '@alien_org/sso-sdk-react';
import { useState, useEffect } from 'react';
 
function CustomAuth() {
  const { generateDeeplink, pollAuth, exchangeToken } = useAuth();
  const [deepLink, setDeepLink] = useState<string | null>(null);
  const [pollingCode, setPollingCode] = useState<string | null>(null);
 
  const handleSignIn = async () => {
    const response = await generateDeeplink();
    setDeepLink(response.deep_link);
    setPollingCode(response.polling_code);
  };
 
  useEffect(() => {
    if (!pollingCode) return;
 
    const interval = setInterval(async () => {
      const response = await pollAuth(pollingCode);
 
      if (response.status === 'authorized') {
        clearInterval(interval);
        await exchangeToken(response.authorization_code);
        setDeepLink(null);
        setPollingCode(null);
      } else if (response.status === 'rejected' || response.status === 'expired') {
        clearInterval(interval);
        setDeepLink(null);
        setPollingCode(null);
      }
    }, 5000);
 
    return () => clearInterval(interval);
  }, [pollingCode, pollAuth, exchangeToken]);
 
  if (deepLink) {
    return <QRCodeDisplay deepLink={deepLink} />;
  }
 
  return <button onClick={handleSignIn}>Sign In with Alien</button>;
}

Protected Routes

Create a protected route component:


import { useAuth } from '@alien_org/sso-sdk-react';
import { Navigate } from 'react-router-dom';
 
function ProtectedRoute({ children }: { children: React.ReactNode }) {
  const { auth } = useAuth();
 
  if (!auth.isAuthenticated) {
    return <Navigate to="/login" />;
  }
 
  return <>{children}</>;
}
 
// Usage
<Route path="/dashboard" element={
  <ProtectedRoute>
    <Dashboard />
  </ProtectedRoute>
} />

Complete Example


import { AlienSsoProvider, useAuth, SignInButton } from '@alien_org/sso-sdk-react';
 
function App() {
  return (
    <AlienSsoProvider
      config={{
        ssoBaseUrl: 'https://sso.alien-api.com',
        providerAddress: 'your-provider-address'
      }}
    >
      <Dashboard />
    </AlienSsoProvider>
  );
}
 
function Dashboard() {
  const { auth, logout, verifyAuth } = useAuth();
 
  // Verify token on mount
  useEffect(() => {
    if (auth.token) {
      verifyAuth();
    }
  }, []);
 
  if (!auth.isAuthenticated) {
    return (
      <div>
        <h1>Welcome to My App</h1>
        <SignInButton />
      </div>
    );
  }
 
  return (
    <div>
      <h1>Dashboard</h1>
      <div>
        <p>Session: {auth.tokenInfo?.app_callback_session_address}</p>
        <p>
          Expires: {new Date(auth.tokenInfo.expired_at * 1000).toLocaleString()}
        </p>
      </div>
      <button onClick={logout}>Logout</button>
    </div>
  );
}
 
export default App;

TypeScript Support

The React SDK is fully typed. Import types as needed:


import type { AuthState, AlienSsoClient } from '@alien_org/sso-sdk-react';
 
const auth: AuthState = useAuth().auth;
const client: AlienSsoClient = useAuth().client;

Next Steps

API Reference - React - Complete API documentation for React SDK.
Demo App - Example implementation and source code.
Core Integration Guide - For vanilla JavaScript/TypeScript projects.