@authu/react

React SDK for AuthU - Centralized Multi-Tenant Authentication Service.

Installation

npm install @authu/react
# or
pnpm add @authu/react
# or
yarn add @authu/react

Usage

1. Configure the Provider

Wrap your app with AuthUProvider:

import {AuthUProvider} from '@authu/react';

function App() {
  return (
    <AuthUProvider
      domain="https://auth.example.com"
      clientId="your-client-id"
      redirectUri={window.location.origin + '/callback'}
    >
      <YourApp />
    </AuthUProvider>
  );
}

2. Use the Hook

Access authentication state and methods with useAuthU:

import {useAuthU} from '@authu/react';

function Profile() {
  const {isAuthenticated, isLoading, user, login, logout} = useAuthU();

  if (isLoading) return <div>Loading...</div>;

  if (!isAuthenticated) {
    return <button onClick={() => login()}>Log in</button>;
  }

  return (
    <div>
      <p>Welcome, {user?.name}</p>
      <button onClick={() => logout()}>Log out</button>
    </div>
  );
}

3. Protect Routes

Use PrivateRoute to protect authenticated routes. It automatically triggers the OAuth login flow when the user is not authenticated:

import {PrivateRoute} from '@authu/react';

function AppRoutes() {
  return (
    <Routes>
      <Route path="/" element={<Home />} />
      <Route
        path="/dashboard"
        element={
          <PrivateRoute>
            <Dashboard />
          </PrivateRoute>
        }
      />
    </Routes>
  );
}

PrivateRoute Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | children | ReactNode | - | Content to render when authenticated | | fallback | ReactNode | null | Content to show while loading or redirecting | | loginOnUnauthenticated | boolean | true | Auto-trigger login when not authenticated |

Automatic Login Flow

When loginOnUnauthenticated is true (default), visiting a protected route triggers:

1. PrivateRoute checks isAuthenticated
2. If not authenticated → calls login() automatically
3. User is redirected to AuthU login page
4. After login, AuthU redirects back to the app
5. AuthUProvider exchanges the code for tokens
6. User is now authenticated and sees the protected content

This enables seamless SSO: users logged into AuthU are automatically authenticated in the app without extra clicks.

4. Get Access Token for API Calls

Use useApiToken to get tokens for authenticated API requests:

import {useApiToken} from '@authu/react';

function ApiComponent() {
  const {getToken} = useApiToken();

  const fetchData = async () => {
    const token = await getToken();
    const response = await fetch('/api/data', {
      headers: {
        Authorization: `Bearer ${token}`,
      },
    });
    return response.json();
  };

  return <button onClick={fetchData}>Fetch Data</button>;
}

Token Storage

Tokens never touch localStorage, sessionStorage or any other persistent store. The access token and the refresh token live in memory for the lifetime of the page: an XSS on the host application can still act as the user while the page is open, but it can no longer walk away with a 30-day refresh token and replay it from anywhere, later.

The trade-off is that a reload loses the tokens. The session itself is not lost, though: it lives in AuthU's own cookie, and the SDK re-derives the tokens from it on every page load with one silent round trip.

Silent renewal (prompt=none)

On mount, when no code is coming back in the URL, the SDK redirects to /authorize?prompt=none. AuthU answers without ever showing a page:

• session cookie still valid → it redirects straight back with a fresh authorization code, which the SDK exchanges for tokens. The visitor sees a single redirect and stays signed in.
• no session → it redirects back with error=login_required. The SDK reads that as "anonymous", renders accordingly, and records the attempt in sessionStorage so the tab never loops through AuthU again.

The URL the visitor asked for is saved before the round trip and restored afterwards, so landing on redirectUri is invisible.

Set silentAuth: false to opt out. The session then does not survive a reload at all: every load starts signed out until login() is called.

Logging out

logout() now navigates to AuthU's /logout rather than only clearing memory. It has to: the session lives in the AuthU cookie, so a purely local logout would let the next silent renewal sign the visitor right back in. The browser returns to redirectUri, or to options.returnTo when given - which must be a URI registered for the tenant, or on the tenant's home origin, otherwise AuthU falls back to its own host.

Upgrading from 1.0.x

Two behaviour changes to expect in an app that upgrades:

• any token left in localStorage under authu_tokens by a previous version is deleted on the first load;
• logout() performs a full navigation. Code that expected it to be synchronous and stay on the page must move whatever it did afterwards into options.returnTo.

API Reference

AuthUProvider Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | domain | string | Yes | AuthU server URL | | clientId | string | Yes | OAuth2 client ID | | redirectUri | string | Yes | Callback URL after login | | scope | string | No | OAuth2 scopes (default: openid profile email) | | audience | string | No | API audience for access tokens | | silentAuth | boolean | No | Silent session renewal (default: true, see below) |

useAuthU Returns

| Property | Type | Description | |----------|------|-------------| | isLoading | boolean | True while checking auth state | | isAuthenticated | boolean | True if user is logged in | | user | AuthUUser \| null | User profile info | | error | Error \| null | Auth error if any | | login(options?) | function | Redirect to login | | logout(options?) | function | Log out user | | getAccessToken() | function | Get current access token |

Development

Build

pnpm run build

Lint

pnpm run lint

Publishing

Prerequisites

• Be logged in to npm: npm login
• Have publish rights on @authu scope

Publish a New Version

1. Update version in package.json
2. Build and publish:

pnpm run build
pnpm publish --access public

The --access public flag is required for scoped packages.

Changelog

1.0.15

• Feature: Added loginOnUnauthenticated prop to PrivateRoute for automatic login triggering
• Feature: Added fallback prop to PrivateRoute for custom loading states
• Docs: Improved documentation for automatic SSO flow

1.0.10

• Fix: Changed PKCE storage from sessionStorage to localStorage to prevent state/code_verifier loss during cross-domain OAuth redirects

1.0.9

• Initial stable release

License

MIT