Skip to main content

React SDK

Complete guide to integrating Signia authentication in React applications.

Installation​

npm install @getsignia/signia-auth-sdk @getsignia/signia-auth-ui-react react-router-dom

Setup​

Add Provider​

Wrap your app with SigniaAuthProvider and pass your configuration:

src/main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import { BrowserRouter } from 'react-router-dom';
import { SigniaAuthProvider } from '@getsignia/signia-auth-ui-react';
import App from './App';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <SigniaAuthProvider config={{
      clientId: 'my-app-abc123',                     // Copy from Signia ID Dashboard
      redirectUri: 'http://localhost:5173/oidc-callback',
      issuer: 'https://YOUR_TENANT.signiaauth.com',
      scopes: ['openid', 'profile', 'email']
    }}>
      <BrowserRouter>
        <App />
      </BrowserRouter>
    </SigniaAuthProvider>
  </React.StrictMode>
);
Auto-Discovery

The provider automatically discovers all OIDC endpoints from your issuer's .well-known/openid-configuration. No need to specify individual URLs!

Hooks​

useSigniaAuth​

Access authentication state and user information:

import { useSigniaAuth } from '@getsignia/signia-auth-ui-react';

function Profile() {
  const {
    isAuthenticated,  // boolean - is user logged in?
    isLoading,        // boolean - is auth state loading?
    user,            // UserInfo | null - user claims from ID token
    error,           // Error | null - any authentication error
    client          // OIDCClient - the underlying client instance
  } = useSigniaAuth();

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  if (!isAuthenticated) return <div>Please log in</div>;

  return (
    <div>
      <h1>Welcome {user?.email}</h1>
      <p>User ID: {user?.sub}</p>
    </div>
  );
}

User Object​

The user object contains claims from the ID token:

interface UserInfo {
  sub: string;           // Unique user identifier
  email?: string;        // User email (if 'email' scope)
  email_verified?: boolean;
  name?: string;         // Full name (if 'profile' scope)
  given_name?: string;
  family_name?: string;
  picture?: string;      // Profile picture URL
  // ... other claims
}

Components​

LoginButton​

Pre-built login button:

import { LoginButton } from '@getsignia/signia-auth-ui-react';

function Header() {
  return (
    <nav>
      <LoginButton />
      {/* Or customize: */}
      <LoginButton className="btn-primary">
        Sign In
      </LoginButton>
    </nav>
  );
}

LogoutButton​

Pre-built logout button:

import { LogoutButton } from '@getsignia/signia-auth-ui-react';

function Header() {
  return (
    <nav>
      <LogoutButton />
      {/* Or customize: */}
      <LogoutButton className="btn-danger">
        Sign Out
      </LogoutButton>
    </nav>
  );
}

ProtectedRoute​

Protect routes that require authentication:

import { ProtectedRoute } from '@getsignia/signia-auth-ui-react';

function App() {
  return (
    <Routes>
      <Route path="/" element={<HomePage />} />
      <Route
        path="/dashboard"
        element={
          <ProtectedRoute loadingComponent={<Spinner />}>
            <Dashboard />
          </ProtectedRoute>
        }
      />
    </Routes>
  );
}

Props:

  • loadingComponent (optional) - Component to show while checking auth
  • children - Protected content to render when authenticated

If user is not authenticated, they'll be redirected to login automatically.

Advanced Usage​

Manual Authentication​

Trigger login/logout programmatically:

function CustomAuth() {
  const { client, isAuthenticated } = useSigniaAuth();

  const handleLogin = async () => {
    try {
      await client.login();
    } catch (error) {
      console.error('Login failed:', error);
    }
  };

  const handleLogout = async () => {
    try {
      await client.logout();
    } catch (error) {
      console.error('Logout failed:', error);
    }
  };

  return (
    <div>
      {isAuthenticated ? (
        <button onClick={handleLogout}>Logout</button>
      ) : (
        <button onClick={handleLogin}>Login</button>
      )}
    </div>
  );
}

Access HTTP Client​

Get an authenticated HTTP client for API calls:

function UserData() {
  const { client } = useSigniaAuth();
  const [data, setData] = useState(null);

  useEffect(() => {
    async function fetchData() {
      const httpClient = await client.getAuthHttpClient();
      const response = await httpClient.get('https://api.example.com/user');
      setData(response.data);
    }
    fetchData();
  }, [client]);

  return <div>{JSON.stringify(data)}</div>;
}

The HTTP client automatically includes the access token in requests.

Custom Redirect URI Handling​

The SDK handles the /oidc-callback route automatically. The callback flow works as follows:

  1. Login redirects to /oidc-callback/login
  2. Logout redirects to /oidc-callback/logout
  3. SDK processes the callback and redirects to the original page

You don't need to create these routes - the provider handles them internally.

TypeScript Support​

Full TypeScript support out of the box:

import type { OIDCClientConfig, UserInfo } from '@getsignia/signia-auth-sdk';
import type { SigniaAuthContextValue } from '@getsignia/signia-auth-ui-react';

const config: OIDCClientConfig = {
  clientId: 'my-app-abc123',                  // Copy from Signia ID Dashboard
  redirectUri: 'http://localhost:5173/oidc-callback',
  issuer: 'https://tenant.signiaauth.com',
  scopes: ['openid', 'profile']
};

Examples​

Conditional Rendering​

function Dashboard() {
  const { isAuthenticated, user } = useSigniaAuth();

  return (
    <div>
      {isAuthenticated ? (
        <div>
          <h1>Dashboard</h1>
          <p>Welcome {user?.name}</p>
        </div>
      ) : (
        <div>
          <h1>Public Page</h1>
          <p>Please log in to see your dashboard</p>
        </div>
      )}
    </div>
  );
}

User Profile Display​

function UserProfile() {
  const { user } = useSigniaAuth();

  return (
    <div className="profile">
      {user?.picture && <img src={user.picture} alt="Profile" />}
      <h2>{user?.name || 'Anonymous'}</h2>
      <p>{user?.email}</p>
      <dl>
        <dt>User ID:</dt>
        <dd>{user?.sub}</dd>
        <dt>Email Verified:</dt>
        <dd>{user?.email_verified ? 'Yes' : 'No'}</dd>
      </dl>
    </div>
  );
}
function Navigation() {
  const { isAuthenticated, isLoading } = useSigniaAuth();

  return (
    <nav>
      <Link to="/">Home</Link>
      {isAuthenticated && (
        <>
          <Link to="/dashboard">Dashboard</Link>
          <Link to="/profile">Profile</Link>
        </>
      )}
      <div style={{ marginLeft: 'auto' }}>
        {isLoading ? (
          <span>...</span>
        ) : isAuthenticated ? (
          <LogoutButton />
        ) : (
          <LoginButton />
        )}
      </div>
    </nav>
  );
}

Troubleshooting​

"Invalid redirect URI" error​

Ensure your redirect URI exactly matches what's configured in Signia ID dashboard:

// ✅ Correct
redirectUri: 'http://localhost:5173/oidc-callback'

// ❌ Wrong (missing protocol)
redirectUri: 'localhost:5173/oidc-callback'

// ❌ Wrong (different port)
redirectUri: 'http://localhost:3000/oidc-callback'

User is null after login​

Check that you've requested the necessary scopes:

scopes: ['openid', 'profile', 'email']  // ✅ Includes profile and email
scopes: ['openid']                      // ❌ Only basic authentication

Infinite redirect loop​

Make sure you're not wrapping the entire app with <ProtectedRoute>. The provider needs at least the home page to be public.

Next Steps​