Skip to main content

FAQ / Troubleshooting

A practical, TideCloak-specific FAQ you can drop into your docs. It covers setup, auth flows, SDK usage, RBAC, encryption, middleware, IGA, and common gotchas.

General​

Q: What is TideCloak and how is it different from vanilla Keycloak?A: TideCloak is a Keycloak-compatible IAM, secured by Tide's Cybersecurity Fabric. It adds:

  • Quorum-backed IGA (Identity Governance & Administration) so sensitive changes require multi-party approval.
  • Ineffable Cryptography for keys-no single party (including you or Tide) holds the "keys to the kingdom."
  • SDKs and helpers (e.g., Next.js SDK) for auth, RBAC, and tag-based encryption/decryption.

Q: What is the TideCloak Next.js SDK? A: A drop-in SDK providing <TideCloakProvider>, useTideCloak(), guard components, Edge middleware helpers, verifyTideCloakToken(), and E2EE helpers doEncrypt() / doDecrypt().

Installation & Environment​

Q: Docker install/update failed on Linux. What should I check? A: Confirm network/DNS, rerun sudo apt update, and ensure the distro/arch is supported. If using WSL, verify WSL2 + virtualization is enabled.

Q: TideCloak container starts but the console/realms look "off". A: Make sure you ran the image with the right volumes/imports (e.g., your realm JSON) and exposed the correct port. Confirm whether your distro uses /auth paths (older) vs no /auth (newer Quarkus layout) in admin and token URLs.

Configuration (Clients, Redirects, CORS)​

Q: Users aren't redirected after login or I get a blank screen.A: Most often redirect URI mismatch:

  • Add both http://localhost:3000/auth/redirect and http://localhost:3000/silent-check-sso.html to the client's Valid Redirect URIs.
  • In Web Origins, add the exact origin (e.g., http://localhost:3000 without a trailing slash).
  • If you override redirectUri in the provider, ensure that route exists.

Q: I get CORS errors from the browser. A: Set Web Origins precisely (no trailing slash). For local dev, avoid wildcards; use exact origins. Admin APIs are best called server-to-server to avoid CORS altogether.

Q: Token endpoint 404/401?A: Check which base your instance uses:

  • Newer: https://<host>/realms/<realm>/protocol/openid-connect/token
  • Older: https://<host>/auth/realms/<realm>/protocol/openid-connect/token

Next.js SDK & Middleware​

Q: What's required for silent SSO and token refresh in the browser? A: Ensure public/silent-check-sso.html exists:

<html><body>
<script>parent.postMessage(location.href, location.origin)</script>
</body></html>

Q: How do I protect routes globally?A: Use the Edge middleware factory and define publicRoutes / protectedRoutes. Example matcher pitfalls:

  • Don't accidentally exclude /api/* if you intend to protect APIs.
  • Avoid overly broad matchers that capture static assets (_next, images, etc.).

Q: Server-side verification? A: Use verifyTideCloakToken() in route handlers/API routes to validate JWTs & roles before serving data.

Encryption / Decryption (E2EE)​

Q: doEncrypt() fails or decrypt returns nonsense.A: Common mistakes:

  • data must be string or Uint8Array (not an object).
  • Ensure roles exist and are assigned:
  • Encrypt requires _tide_<tag>.selfencrypt
  • Decrypt requires _tide_<tag>.selfdecrypt
  • Pass the exact tags you used during encryption to decrypt.
const enc = await doEncrypt([{ data: "10 Smith St", tags: ["street"] }]);
const dec = await doDecrypt([{ encrypted: enc[0], tags: ["street"] }]);

Identity Providers (IdP) & Default Redirects​

Q: How do I make Tide (via TideCloak) the default IdP? A: In Authentication → Flows, edit browser, set Identity Provider Redirector default to your Tide IdP alias, and save. Ensure the Tide IdP is configured and enabled.

Q: Users aren't redirected to the Tide login screen. A: Check the browser flow mappings, IdP alias, and the client's redirect URIs/web origins. Inspect server logs for flow/redirect errors.

Management API​

Q: What's the recommended way to automate admin tasks? A: Use a confidential client with Service Accounts + client credentials grant. Assign minimal realm-management roles (principle of least privilege).

Q: Admin REST calls return 403/404. A: Your service account likely lacks needed realm-management roles or you're querying the wrong realm. For 404 on list calls, insufficient privilege can hide resources.

Tokens, Cookies, & Sessions​

Q: Random 401s after some time. A: Check clock skew between app and TideCloak. Ensure token refresh is enabled (SDK does this automatically; you can also call refreshToken() manually). For cookies, confirm domain/SameSite/secure flags align with your environment (HTTPS vs HTTP in dev).

Q: Which token should I use on the server? A: Use the access token (from the cookie/header) with verifyTideCloakToken() on server/API routes. Never expose admin/management tokens to the browser.

IGA (Identity Governance & Administration) & Licensing​

Q: Realm changes don't "stick". A: If IGA is enabled, changes may require draft + review + commit by a quorum of Tide-secured admins. Use the console or API to create a Change Request, then have approvers commit it.

Q: How do I activate my TideCloak license? A: In the Tide IdP settings, use Manage License → Request License. Confirm the realm/host details match your deployment.

Error Playbook (Quick)​

  • 401 Unauthorized: Missing/expired token; wrong token endpoint; clock skew.
  • 403 Forbidden: Missing role/permission (e.g., realm-management).
  • 404 Not Found: Wrong realm ID or insufficient privileges (resource hidden).
  • 409 Conflict: Duplicate resource (username, client ID).
  • CORS: Fix Web Origins and call admin APIs from backend when possible.
  • Redirect loop/blank page: Redirect URI mismatch or missing silent-check-sso.html.

Diagnostics​

  1. Console & Network: Open DevTools → Network to inspect redirects, CORS, and 401/403 responses.
  2. Server logs: Tail TideCloak logs for flow/mapper errors.
  3. Token inspect: Decode access token (header/payload) and confirm roles/claims appear as expected.
  4. Minimal Repro: Test with a fresh client and the default /auth/redirect + silent-check-sso.html.

Copy-Paste Snippets​

Token (client credentials)

HOST="https://<host>"
REALM="master"
CLIENT_ID="admin-bot"
CLIENT_SECRET="<secret>"

curl -sS -X POST "$HOST/realms/$REALM/protocol/openid-connect/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials" -d "client_id=$CLIENT_ID" -d "client_secret=$CLIENT_SECRET"

Protect API route (Next.js App Router)

import { NextRequest, NextResponse } from 'next/server';
import { verifyTideCloakToken } from '@tidecloak/nextjs/server';
import config from '../../../tidecloakAdapter.json';

export async function GET(req: NextRequest) {
const token = req.cookies.get('kcToken')?.value || '';
const payload = await verifyTideCloakToken(config, token, ['user']);
if (!payload) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
return NextResponse.json({ data: 'OK' });
}

Still stuck?​

  • Recheck redirect URIs + Web Origins (exact strings), roles, and token endpoint base.
  • If IGA is on, confirm the change was committed.
  • Contact us and share logs, token payload (redacted), client config, and a minimal repro when asking for help.