Skip to main content

Discussion: Understanding TideCloak Auth in Vanilla JS

Conceptual overview of how TideCloak works in a simple browser app.

The Big Picture​

  1. Initialization Your app calls IAMService.initIAM(config). A silent SSO check runs using public/silent-check-sso.html. If the user already has a session, tokens are established without user interaction.

  2. Interactive Login Call IAMService.doLogin() to redirect to TideCloak → Tide Portal. After success, the browser returns to your redirect URI, where your app reloads and completes the session.

  3. Tokens & Refresh The SDK maintains the access token and refreshes silently. You can manually force it (updateIAMToken() / forceUpdateToken()), but most apps don't need to.

  4. Role-Aware UI Use hasRealmRole() / hasClientRole() to gate UI/actions. Read claims via getValueFromToken() / getValueFromIDToken().

  5. E2EE with Tags Encrypt/decrypt data in the browser using doEncrypt() / doDecrypt(). Each payload has tags; users must hold matching _tide_<tag>.selfencrypt/selfdecrypt roles.

Typical Folder structure:

my-app/
├─ index.html
├─ main.js
├─ tidecloak.json
├─ public/
│  └─ auth/
│     └─ redirect.html
├─ package.json
└─ vite.config.js

Redirect URI​

  • Default: ${origin}/auth/redirect
  • If you don't create public/auth/redirect.html (or custom route), post-auth the browser will 404.
  • You can override redirectUri in initIAM({ ...config, redirectUri }), but the route/file must exist.

Backend Validation Pattern​

  • Browser → sends bearer token to your API
  • API → verifies JWT via your realm's JWKS (never trust client input blindly)
  • API → responds with privileged data only if verification & role checks pass

Common Pitfalls​

  • Missing public/silent-check-sso.html
  • Missing redirect route/file for default or custom redirectUri
  • Encrypting objects instead of string/Uint8Array
  • Missing required tag roles for E2EE
  • Not handling tokenExpired (edge sessions, long-lived tabs)

Best Practices​

  • Initialize IAMService once at app bootstrap
  • Add graceful handlers for initError, authError, tokenExpired
  • Keep redirect URIs consistent across environments
  • Prefer tag-minimalism (small, purpose-specific tags) to keep role policy simple