Login Example

Auth State Machine

Clear state transitions prevent race conditions and edge cases:

AuthContext Interface

Standardized interface used by Auth0, Okta, and custom implementations.getAccessTokenSilently is the key method — it returns a valid token, transparently refreshing if the current one is expired.

interface AuthContext {
  isAuthenticated: boolean;
  isLoading: boolean;
  user: User | null;
  error: Error | null;
  loginWithRedirect(): Promise<void>;
  logout(): Promise<void>;
  // Returns a valid access token, refreshing silently if expired.
  // Client-side: calls token_endpoint with refresh_token grant.
  // BFF: the backend refreshes transparently via httpOnly cookie.
  getAccessTokenSilently(): Promise<string>;
}

OIDC Configuration Discovery

Fetch endpoints dynamically from your SSO provider:

Returns: authorization_endpoint, token_endpoint,userinfo_endpoint, end_session_endpoint

Protected Route Pattern (Hook)

Use the useRequireAuth hook to protect components:

function ProtectedPage() {
  const { isLoading, user } = useRequireAuth();

  if (isLoading) return <Spinner />;
  
  return <div>Welcome, {user?.name}!</div>;
}

// Or use the declarative wrapper:
<RequiresAuthentication>
  <SecretContent />
</RequiresAuthentication>

Token Refresh Patterns

Access tokens expire (typically 5–60 min). Two patterns handle renewal without forcing the user to re-authenticate:

The SPA stores the refresh token in localStorage and calls the token endpoint directly when the access token expires. A singleton promise prevents concurrent refresh requests from racing.

let refreshPromise: Promise | null = null;

async function getStoredTokensAndRefreshIfNeeded() {
  const tokens = JSON.parse(localStorage.getItem("oauthTokens"));

  if (isExpired(tokens.expiresAt) && tokens.refreshToken) {
    // Reuse in-flight refresh to prevent race conditions
    if (!refreshPromise) {
      refreshPromise = janusApp
        .refreshTokens(redirectURI, tokens.refreshToken)
        .finally(() => {  refreshPromise = null; });
    }
    return await refreshPromise;
  }

  return tokens;
}

// Axios interceptor: attach token on every request
apiClient.interceptors.request.use(async (config) => {
  const tokens = await getStoredTokensAndRefreshIfNeeded();
  config.headers.Authorization = `Bearer ${tokens.idToken.encoded}`;
  return config;
});

// Axios interceptor: retry on 401 with a fresh token
apiClient.interceptors.response.use(
  (res) => res,
  async (error) => {
    if (error.response?.status === 401 && !error.config._retry) {
      error.config._retry = true;
      await refreshTokens();
      return apiClient(error.config);
    }
    return Promise.reject(error);
  }
);

Source:FoxHog — JanusAuth.ts + apiClient.ts

The SPA never sees the refresh token. A backend proxy handles the OAuth flow, stores tokens in httpOnly cookies, and exposes /auth/login,/auth/me, and /auth/logout endpoints. The frontend just calls fetch with credentials: "include".

// Start login — redirect to backend, which redirects to Janus
async function startLogin() {
  window.location.href = `${config.apiUrl}/auth/login`;
}

// Check session — backend validates the httpOnly cookie
async function checkSession(): Promise<boolean> {
  const res = await fetch(`${config.apiUrl}/auth/me`, {
    credentials: "include",  // sends httpOnly cookie
  });
  if (!res.ok) return false;

  const user = await res.json();
  setAuthenticated(user);  // update nanostores
  return true;
}

// API calls — backend proxies to upstream with the real token
const res = await fetch(`${config.apiUrl}/some-data`, {
  credentials: "include",
});
// Backend attaches the access token from the session cookie
// and refreshes it transparently if expired

Source:BioNav — BFF auth migration (MR !129)

Implementation Comparison