Skip to main content

How‑to Guide: Common Tasks with TideCloak in React

Copy‑paste snippets for the tasks you'll use most in a React SPA.

Install or scaffold​

New React + Vite app (TypeScript):

npm create vite@latest my-app -- --template react-ts
cd my-app
npm install @tidecloak/react

Required file for silent SSO ``

public/silent-check-sso.html
<html>
  <body>
    <script>parent.postMessage(location.href, location.origin)</script>
  </body>
</html>

Initialize the Provider (React Router)​

src/main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import { BrowserRouter, Routes, Route } from 'react-router-dom';
import { TideCloakContextProvider } from '@tidecloak/react';
import adapter from '../tidecloakAdapter.json';
import Home from './pages/Home';
import RedirectPage from './pages/auth/RedirectPage';
import Dashboard from './pages/Dashboard';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <TideCloakContextProvider config={adapter}>
      <BrowserRouter>
        <Routes>
          <Route path="/" element={<Home />} />
          <Route path="/auth/redirect" element={<RedirectPage />} />
          <Route path="/dashboard" element={<Dashboard />} />
        </Routes>
      </BrowserRouter>
    </TideCloakContextProvider>
  </React.StrictMode>
);

Customize redirect URI​

Default (if omitted):

${window.location.origin}/auth/redirect

Override it:

<TideCloakContextProvider config={{ ...adapter, redirectUri: 'https://yourapp.com/auth/callback' }}>
  {/* app */}
</TideCloakContextProvider>

Ensure the target route exists in your router.

Example redirect handler

src/pages/auth/RedirectPage.tsx
import { useEffect } from 'react';
import { useNavigate } from 'react-router-dom';
import { useTideCloak } from '@tidecloak/react';

export default function RedirectPage() {
  const { authenticated, isInitializing, logout } = useTideCloak();
  const navigate = useNavigate();

  useEffect(() => {
    const params = new URLSearchParams(window.location.search);
    if (params.get('auth') === 'failed') {
      sessionStorage.setItem('tokenExpired', 'true');
      logout();
    }
  }, []);

  useEffect(() => {
    if (!isInitializing) navigate(authenticated ? '/dashboard' : '/');
  }, [authenticated, isInitializing, navigate]);

  return (
    <div style={{ minHeight:'100vh', display:'flex', alignItems:'center', justifyContent:'center' }}>
      <p>Waiting for authentication...</p>
    </div>
  );
}

Read token claims​

import { useTideCloak } from '@tidecloak/react';

const { getValueFromToken, getValueFromIdToken } = useTideCloak();

const email = getValueFromToken('email');
const username = getValueFromIdToken('preferred_username');

Check roles​

import { useTideCloak } from '@tidecloak/react';

const { hasRealmRole, hasClientRole } = useTideCloak();

const isAdmin = hasRealmRole('admin');
const isEditor = hasClientRole('editor'); // defaults to your app client
const isBillingOnBackoffice = hasClientRole('billing:writer', 'backoffice-client');

Manually refresh token​

import { useTideCloak } from '@tidecloak/react';

const { refreshToken } = useTideCloak();
const ok = await refreshToken();
console.log(ok ? 'Token refreshed!' : 'Refresh failed.');

(Tokens also refresh automatically as they expire.)

Encrypt data before sending​

import { useTideCloak } from '@tidecloak/react';

const { doEncrypt } = useTideCloak();

const encrypted = await doEncrypt([
  { data: 'Sensitive Information', tags: ['private'] },
]);

Data type: data must be string or Uint8Array. Permissions: require _tide_<tag>.selfencrypt on the access token.

Decrypt received data​

import { useTideCloak } from '@tidecloak/react';

const { doDecrypt } = useTideCloak();

const decrypted = await doDecrypt([
  { encrypted: receivedEncryptedData, tags: ['private'] },
]);

Permissions: require _tide_<tag>.selfdecrypt. Order guarantee: output preserves input order.

Route guards and gated UI​

Simple gated UI:

import { Authenticated, Unauthenticated } from '@tidecloak/react';

export function Header() {
  return (
    <>
      <Authenticated><button>Sign out</button></Authenticated>
      <Unauthenticated><button>Sign in</button></Unauthenticated>
    </>
  );
}

Lightweight route guard:

import { useTideCloak } from '@tidecloak/react';
import { Navigate } from 'react-router-dom';

export function RequireAuth({ children }: { children: JSX.Element }) {
  const { authenticated, isInitializing } = useTideCloak();
  if (isInitializing) return null;
  return authenticated ? children : <Navigate to="/" replace />;
}

Use it:

<Route path="/dashboard" element={<RequireAuth><Dashboard/></RequireAuth>} />

Verify tokens on the backend (Node Express)​

import express from 'express';
import type { Request, Response, NextFunction } from 'express';
import { verifyTideCloakToken } from '@tidecloak/react/server';
import adapter from '../tidecloakAdapter.json';

const app = express();

async function auth(requiredRoles: string[] = []) {
  return async (req: Request, res: Response, next: NextFunction) => {
    const authz = req.headers.authorization || '';
    const token = authz.startsWith('Bearer ') ? authz.slice(7) : '';
    const payload = await verifyTideCloakToken(adapter, token, requiredRoles);
    if (!payload) return res.status(401).json({ error: 'Unauthorized' });
    (req as any).user = payload;
    next();
  };
}

app.get('/api/secure', await auth(['user']), (req, res) => {
  res.json({ data: 'Secure data response' });
});

app.listen(3001, () => console.log('API on :3001'));

Handle auth errors​

import { useEffect } from 'react';
import { useTideCloak } from '@tidecloak/react';

export function AuthErrorToast() {
  const { initError } = useTideCloak();

  useEffect(() => {
    if (initError) {
      console.error('Authentication error:', initError);
      alert('Authentication failed. Please log in again.');
    }
  }, [initError]);

  return null;
}

Local TideCloak (dev)​

If you don't have a server yet, start the dev container which auto‑imports a sample realm:

sudo docker run -d -v .:/opt/keycloak/data/h2 -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=password --name tidecloak tideorg/tidecloak-dev:latest

Activate a license (dev/free)​

Go to your realm's Tide IdP Settings → Manage License → Request License and finish the flow.

Quick checklist​

  • public/silent-check-sso.html exists
  • <TideCloakContextProvider config={adapter}> wraps your app
  • Redirect route exists (default /auth/redirect or your custom redirectUri)
  • Roles are created and assigned in TideCloak
  • Backend verifies tokens before serving secure data