Skip to main content

Tutorial: Build a TideCloak + Next.js App from Scratch

Scaffold a fresh Next.js app wired to TideCloak, with auth, middleware, and optional IGA - in minutes.

1) Prerequisites​

  • A TideCloak server you manage (dev or hosted). For local dev, you can run the Docker image (see below).
  • Node.js ≥ 18.17.0

2) Initialize the template project​

The initializer can create the realm and clients on your TideCloak server (including Tide Realm Admin creation and IGA enablement).

sudo apt update && sudo apt install -y curl jq
npm init @tidecloak/nextjs@latest my-app

Project structure (generated)​

my-app/
├── app/
│ └── api/protected/route.js # Protected API route (verifies access token)
│ ├── auth/redirect/page.jsx # Redirect target after auth
│ ├── home/page.jsx # Post-login landing page
│ ├── public/silent-check-sso.html
│ ├── layout.jsx # App entry point
│ └── page.jsx # Login / entry page
├── tidecloak.json # TideCloak adapter config
├── middleware.js # Edge middleware to verify token on navigation
└── package.json

3) Run the app​

cd my-app
npm run dev

Open http://localhost:3000 🎉

Expanding from the template

Implementing encryption/decryption​

You will first need to create the required realm roles that enable each user to encrypt/decrypt their own date of births.

note

You have already completed the pre-requisites asked for in the documentation to set up encrypt/decrypt roles AND also set up the required client.

Set up encrypt/decrypt roles

TideCloak lets you protect sensitive fields with tag-based encryption. Pass in an array of { data, tags } objects and receive encrypted strings (or vice versa).

Syntax Overview​

// Encrypt payloads:
const encryptedArray = await doEncrypt([
  { data: /* string */, tags: ['tag1', 'tag2'] },
  // …
]);

// Decrypt blobs:
const decryptedArray = await doDecrypt([
  { encrypted: /* string from doEncrypt */, tags: ['tag1', 'tag2'] },
  // …
]);

Order guarantee: the returned array matches the input order.

  • Encryption requires access token roles _tide_<tag>.selfencrypt for each tag.
  • Decryption requires access token roles _tide_<tag>.selfdecrypt for each tag.