A Slack read uses that user's workspace. A GitHub issue is created as that user, in a repository they can access. An agent can make the wrong call, but it must never act with the wrong user's access.

The fix has two parts, and both appear in the first half of this tutorial:

1. Each user grants access separately. Alice authorizes Slack for herself. Bob authorizes it for himself.

2. Your agent passes an identifier, not a token. A string like alice@example.com selects whose grant to use. One function turns it into a token at the moment of the call, and that token never reaches your model inputs, your tool schemas, or your logs.

Most agent tutorials stop before either point. They hand you an API key, wire up one function, and the model calls it. The design works until a second person shows up.

To make the pattern concrete, you'll build a command-line agent that watches a Slack channel, decides on its own which messages describe real work, files a GitHub issue for those, and replies in the Slack thread with the issue link. Every call runs as one user's own OAuth grant.

You'll write the OAuth flow yourself: the consent redirect, the state check, the token exchange, an encrypted store, and the refresh path. None of it is long, and seeing it whole is what makes the identity argument checkable instead of a claim you take on faith.

Two topics stay out of scope here: we won't cover Model Context Protocol servers or voice or realtime hosts. The identity pattern holds in both settings, but the surrounding plumbing deserves its own article.

Table of Contents

• What You'll Build

• Prerequisites

• What Are AI Agent Tools?

• Why a Shared Token Breaks

• Architecture Overview

• How to Register the Slack and GitHub OAuth Apps

• How to Run the Consent Flow

• How to Store Tokens Encrypted, Keyed by User

• How to Run Tool Calls as the Current User

• How to Handle Refresh and Revocation

• How to Add a Second Provider

• Full Walkthrough

• How to Apply the Pattern to Other Use Cases

• What Went Wrong When I Built This

• Conclusion

What You'll Build

The agent is called channel-watcher-agent. Each run does four things:

1. Reads recent messages from a Slack channel.

2. Asks a model, message by message, whether the text describes a bug or a concrete action item.

3. Files a GitHub issue for the messages that qualify.

4. Replies in the original Slack thread with a link to the new issue.

Nobody clicks a button to start any of it. Slack already ships a "create an issue from this message" action, which is a different product. Here the agent reads the channel, forms its own judgment, and acts only on what it judges worth acting on.

The stack stays small on purpose:

Three of those five ship with Node. The only packages you install are the AI SDK and its friends.

By the end you'll have:

• Two OAuth apps, Slack and GitHub, that a user consents to once.

• An encrypted token store keyed by user and provider.

• An agent that resolves the current user to an identifier and never lets a token reach the model.

• A tool loop where the model decides whether to file an issue at all.

• A demonstration that a second user's run stops instead of reading the first user's data.

The finished code lives at github.com/saif-shines/channel-watcher-agent.

Prerequisites

Accounts and tools:

• Node.js 22.13 or newer, plus npm. The token store uses node:sqlite, which is stable from that version on.

• A Slack workspace where you can install apps, and a channel to watch. A throwaway channel works best.

• A GitHub account and a repository that can absorb test issues.

• An API key for a model provider the AI SDK supports. Anthropic is used in the examples.

• mkcert, to issue a local HTTPS certificate. How to Register the Slack and GitHub OAuth Apps explains why an ordinary http://localhost callback will not do.

Useful background, though none of it is a hard requirement:

• async and await, and reading a small Node script.

• OAuth 2.0 at a high level: an app redirects a user to a provider, the user consents, the app receives a token.

• Tool calling, sometimes called function calling. The next section covers what the tutorial needs.

One warning before starting: The agent writes to real systems. It opens real GitHub issues and posts real Slack messages. Use a test Slack channel and a throwaway GitHub repository while you're still checking that it only acts on messages you intend.

What Are AI Agent Tools?

A tool is a function you hand the model along with your input. The model can't run that function itself. It can only ask: call fileGithubIssue with this title and this body. Your code performs the call, returns the result, and the model uses that result to choose the next step.

Request, execute, return. The exchange is the whole mechanism, and everything called an "agent" is a loop around it.

How a Tool Differs from an API

Tools and APIs wrap the same call but are written for different readers.

An API is written for you. It assumes you read the documentation, and that you know thread_ts is the field that turns a Slack message into a threaded reply.

A tool is written for a model that has read nothing. So a tool carries its own explanation:

• A name the model can reason about, like fileGithubIssue.

• A description in plain language, including when not to use the tool.

• A schema for the inputs, so the model knows title is a required string.

Below is one tool from the project. Most of the code is explanation rather than logic:

const fileGithubIssue = tool({
  description: 'File a GitHub issue for an actionable Slack message',
  inputSchema: z.object({
    title: z.string(),
    body: z.string(),
  }),
  execute: async ({ title, body }) => {
    // ... the actual API call goes here
  },
});

The description and inputSchema are the parts the model sees. The execute function is yours alone. Identity gets settled inside execute, so the model never learns which account the call ran against.

Why Models Handle Tools Better Than Raw API Calls

Pasting a curl command into the input and asking the model to fill in the blanks is possible. But this approach fails in predictable ways.

Tools work better for three reasons:

1. The schema is enforced before your code runs. A malformed tool call gets rejected and retried by the SDK. A malformed URL fails at runtime instead.

2. Results return to the model. After fileGithubIssue returns, the model can read the new issue URL and use it in the Slack reply. The chaining is what makes the second step possible.

3. Credentials stay out of the conversation. The model asks for an action by name and never sees a token. A token it never sees can't leak into a completion, a log line, or a prompt-injection payload.

Reason three is what the rest of this tutorial builds toward. You'll keep tokens out of the model on purpose: the agent holds an identifier, and a token appears only at the moment of the provider call.

Most Agents Need More Than One App

Few useful agents talk to a single app. A support agent reads Zendesk and updates Salesforce. A standup agent reads GitHub and posts to Slack. A scheduling agent reads Gmail and writes to Google Calendar.

Each app brings its own OAuth registration, scope names, token lifetime, and refresh behavior. Multiply the list by every user of the agent, and the real problem appears.

Why a Shared Token Breaks

One shared credential for everybody works in a demo and fails once a second person shows up. Picture the quick version of the Slack half: create a Slack app, install it, copy the bot token into .env, and let every tool call use it.

Three problems arrive together.

First, every run uses the same permissions. The bot sees every channel it was invited to, no matter who triggered the run. Ask the agent about a channel you were never in, and the bot reads it anyway. The agent has become a way around your own workspace permissions.

Second, the audit trail is also wrong. Every GitHub issue says the bot opened it. Every Slack reply comes from the bot. Asked why an issue exists, the honest answer is "an agent filed it for somebody, and we can't tell who."

And third, revocation stops working. A user leaves the company and their Slack account is deactivated. The agent keeps running, because it never used their credentials.

The alternative is per-user grants. Each user authorizes the apps for themselves. That creates a new requirement, though: somewhere to keep those grants.

The Distinction is One Field in One Response

Slack makes the difference unusually easy to see. When a user finishes the consent screen, the token exchange returns both kinds of token in the same JSON object:

{
  "ok": true,
  "access_token": "xoxb-REDACTED-BOT-TOKEN",
  "token_type": "bot",
  "authed_user": {
    "id": "U0A1B2C3D",
    "scope": "channels:history,chat:write,users:read",
    "access_token": "xoxp-REDACTED-USER-TOKEN",
    "token_type": "user"
  }
}

The top-level access_token is the bot. The nested authed_user.access_token is the person who just consented. Reading conversations.history with the first one returns every channel the app was invited to. Reading it with the second returns only the channels that users can already see. The same split governs writes: chat.postMessage with a user token posts under that person's name.

Two fields, one letter apart in the prefix, and the entire permission model of your agent hangs on which one you store. This tutorial requests only user scopes, so Slack issues no bot token at all.

Tokens Must Stay Out of the Model and the Logs

Per-user tokens become the most sensitive data in the system. Two destinations are off limits:

• The model: Keep tokens out of inputs, tool descriptions, and tool return values. A model that has seen a token can repeat it, and prompt injection turns any tool result into untrusted input.

• Your logs: Tool inputs and outputs are exactly what you want to log while debugging an agent. Tokens traveling in those payloads land in your log store permanently.

This tutorial keeps tokens on one narrow path. Your code passes an identifier, a stable reference to one user. One helper turns that identifier into a token, and from there the token goes straight into a provider call and nowhere else. It's never named in a tool schema, never attached to anything the model can read, and never returned from a tool.

Why You Own the OAuth Apps and the Store

The point of writing the flow yourself isn't the plumbing. It's control over who may use whose grant.

In this tutorial the users are teammates. Each person connects their own Slack and GitHub, and the agent acts as whoever triggered the run. The same design holds when those users are customers of your product: each person still has their own grant, and a wrong mapping means one person's run using someone else's access. Only the source of the identifier changes. A session for teammates, a tenant record for customers.

Architecture Overview

Two flows matter, and they happen at different times. Keeping them separate is most of the work.

Connection time happens once per user, per app. The user consents, and tokens land in your store. The agent isn't running.

Runtime happens on every execution. The agent resolves the current user to an identifier and does its work. No consent screens and no browser.

CONNECTION TIME (once per user, per app)

  Your user              connect.js              Slack / GitHub
     |                       |                         |
     |-- "connect Slack" --->|                         |
     |<--- consent link -----|                         |
     |----------------------- OAuth consent ---------->|
     |                       |<--- redirect + code ----|
     |                       |---- exchange code ----->|
     |                       |<---- tokens ------------|
     |                       |                         |
     |                  [encrypt, store                |
     |                   under (identifier,            |
     |                   provider)]                    |
     |                       |                         |


RUNTIME (every agent run)

  Your agent             Token store             Slack / GitHub
     |                       |                         |
  [resolve identifier        |                         |
   from your own session]    |                         |
     |                       |                         |
     |-- getAccessToken( --->|                         |
     |     identifier,       |                         |
     |     provider )        |                         |
     |<---- token -----------|                         |
     |                       |                         |
     |------------------ API call as user ------------>|
     |<----------------- result -----------------------|
     |                       |                         |
  [model sees result,        |                         |
   never a token]            |                         |

Three properties follow from the shape.

The identifier replaces the token in your agent code. Everything above the token store handles a string like alice@example.com or user_8f21c. The string is worthless on its own: without the store and its encryption key, it opens nothing.

One identity spans many apps. A single identifier has a Slack row and a GitHub row beneath it. A third app doesn't create a third identity to reconcile.

Authorization stays in your code. The store answers which tokens belong to an identifier. The store can't know whether the request deserved an answer. Deciding that the caller may act as that identifier happens before any call.

One rule follows, and bending it defeats the whole design: resolve the identifier server-side from an authenticated session. Never accept an identifier from a request body, a query parameter, or a browser. An identifier accepted from a client is an "act as any user" endpoint.

How to Register the Slack and GitHub OAuth Apps

The walkthrough uses Slack and GitHub as the two providers end to end. Both need the same three things: a registered app, a redirect URI, and a set of scopes. The details differ enough to be worth walking through separately.

The Redirect URI Has to Use HTTPS

Most tutorials that touch OAuth hand you http://localhost:3000/callback and move on. Slack rejects it. Slack's documentation states flatly that "a Redirect URL must also use HTTPS", and it makes no exception for localhost. GitHub is more relaxed and accepts either, so a single HTTPS callback satisfies both.

The rule looks pedantic, because on localhost the request never leaves your machine and there's nothing on the wire to intercept. Slack applies it uniformly anyway, and a uniform rule with no exemptions is a defensible choice for a provider handing out credentials: every exemption is a branch somebody has to get right, and "is this really localhost" is a question that has been answered incorrectly before.

mkcert issues a certificate signed by a local authority it adds to your system trust store, so the browser accepts it without a warning:

mkcert -install
mkcert localhost

That writes localhost.pem and localhost-key.pem into the current directory. A tunneling service such as ngrok also works, but its free URLs rotate, which means re-editing both app registrations every session.

The Slack App, and the One Setting That Matters

At api.slack.com/apps, create an app in your workspace. Then open OAuth & Permissions and set two things.

Add https://localhost:3000/callback under Redirect URLs.

Then find the scopes. The page has two sections, and choosing the wrong one silently rebuilds the shared-bot design:

Under User Token Scopes, add:

• channels:history: read messages in public channels the user belongs to

• chat:write: post as the user

• users:read: turn user IDs into names

Leave Bot Token Scopes empty. Copy the Client ID and Client Secret from Basic Information.

The GitHub OAuth App

Under Settings → Developer settings → OAuth Apps → New OAuth App, set the Authorization callback URL to the same https://localhost:3000/callback, then generate a client secret. GitHub documents the web application flow in full if you want the surrounding detail.

GitHub's scope for issue creation depends on the repository:

• repo covers private repositories, and grants read and write access to code along with it.

• public_repo is the narrower choice, and enough when your test repository is public.

Take the narrower one when you can. A scope you didn't need is a scope you have to explain later.

The Environment File

Both apps produce a client ID and a client secret, and the store needs an encryption key. Generate the key first:

node -e "console.log(require('node:crypto').randomBytes(32).toString('base64'))"

Then fill in .env:

OAUTH_REDIRECT_URI=https://localhost:3000/callback
TLS_CERT_PATH=./localhost.pem
TLS_KEY_PATH=./localhost-key.pem

SLACK_CLIENT_ID=
SLACK_CLIENT_SECRET=
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=

TOKEN_ENCRYPTION_KEY=

SLACK_CHANNEL_ID=C0XXXXXXXXX
GITHUB_REPO=your-name/your-test-repo

Those client secrets authenticate your application to the providers. They're not user credentials, and they never belong in a browser.

How to Run the Consent Flow

Everything provider-specific belongs in one place, so that adding a third provider later means adding an entry rather than a branch.

Step 1: Describe Each Provider Once

const REDIRECT_URI = process.env.OAUTH_REDIRECT_URI;

export const providers = {
  slack: {
    label: 'Slack',
    authorizeUrl: 'https://slack.com/oauth/v2/authorize',
    tokenUrl: 'https://slack.com/api/oauth.v2.access',

    // These go in `user_scope`, not `scope`. Scopes listed under `scope` grant
    // a bot token, and a bot token is what this project exists to avoid.
    userScopes: ['channels:history', 'chat:write', 'users:read'],

    buildAuthorizeUrl(state) {
      const url = new URL(this.authorizeUrl);
      url.searchParams.set('client_id', process.env.SLACK_CLIENT_ID);
      url.searchParams.set('user_scope', this.userScopes.join(','));
      url.searchParams.set('redirect_uri', REDIRECT_URI);
      url.searchParams.set('state', state);
      return url.toString();
    },
    // exchangeCode and refresh follow below
  },
};

The user_scope parameter is the whole argument in one line. Slack reads scope for bot permissions and user_scope for user permissions. This project sets only the second, so the response comes back with no bot token in it at all.

The state parameter isn't optional. It's a random string you generate, send to the provider, and check on the way back. Without it, any page on the internet can point a browser at your callback URL with an attacker's code attached, and your server will happily exchange it and store the attacker's token under your user's identifier.

Step 2: Exchange the Code, and Take the Right Token

async exchangeCode(code) {
  const response = await fetch(this.tokenUrl, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      code,
      client_id: process.env.SLACK_CLIENT_ID,
      client_secret: process.env.SLACK_CLIENT_SECRET,
      redirect_uri: REDIRECT_URI,
    }),
  });

  const json = await response.json();

  // Slack answers HTTP 200 even when the exchange failed. The `ok` field
  // is the real status.
  if (!json.ok) {
    throw new Error(`Slack token exchange failed: ${json.error}`);
  }

  return normalizeSlackTokens(json.authed_user);
}

Two details in that function cost real debugging time when missed.

Slack returns HTTP 200 for failures. Checking response.ok tells you the HTTP request succeeded, which it did. The json.ok field is the one that reports whether the OAuth exchange worked.

json.authed_user, not json. This is the fork from the section above, expressed as one property access. Reading json.access_token here would compile, run, store a token, and quietly give every user of your agent the same bot identity.

Normalizing the result keeps the rest of the codebase provider-agnostic:

function normalizeSlackTokens(authedUser) {
  return {
    accessToken: authedUser.access_token,
    refreshToken: authedUser.refresh_token ?? null,
    expiresAt: authedUser.expires_in
      ? Date.now() + authedUser.expires_in * 1000
      : null,
    scope: authedUser.scope,
  };
}

GitHub's version of the same function differs in two ways worth noting:

async exchangeCode(code) {
  const response = await fetch(this.tokenUrl, {
    method: 'POST',
    // Without this header GitHub answers with a form-encoded body.
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      Accept: 'application/json',
    },
    body: new URLSearchParams({
      code,
      client_id: process.env.GITHUB_CLIENT_ID,
      client_secret: process.env.GITHUB_CLIENT_SECRET,
      redirect_uri: REDIRECT_URI,
    }),
  });

  const json = await response.json();
  if (json.error) {
    throw new Error(
      `GitHub token exchange failed: ${json.error_description ?? json.error}`
    );
  }

  // OAuth App tokens carry no expiry, so there is nothing to refresh.
  return {
    accessToken: json.access_token,
    refreshToken: null,
    expiresAt: null,
    scope: json.scope,
  };
}

The Accept: application/json header is easy to skip and produces a confusing failure: response.json() throws on a body that came back as access_token=gho_...&scope=repo.

Step 3: Catch the Redirect

OAuth needs somewhere to land. For a command-line tool, a server that starts, handles one callback per provider, and exits is enough. Because Slack demands HTTPS, the scheme in OAUTH_REDIRECT_URI decides which kind of server to start:

function createCallbackServer(handler) {
  if (redirect.protocol !== 'https:') {
    return createHttpServer(handler);
  }

  try {
    return createHttpsServer(
      {
        cert: readFileSync(process.env.TLS_CERT_PATH),
        key: readFileSync(process.env.TLS_KEY_PATH),
      },
      handler
    );
  } catch (err) {
    throw new Error(
      `Could not read the TLS certificate (${err.code ?? err.message}).\n` +
        'Generate a locally-trusted one with mkcert:\n' +
        '  mkcert -install\n' +
        '  mkcert localhost\n' +
        'then point TLS_CERT_PATH and TLS_KEY_PATH at the two files it writes.'
    );
  }
}

A missing certificate is going to happen to somebody, and ENOENT on its own explains nothing about OAuth. The catch block spends four lines saying what to run instead.

The handler itself is where state gets checked:

const pending = new Map();

function handleCallback(request, response) {
  const url = new URL(request.url, redirect.origin);

  if (url.pathname !== redirect.pathname) {
    response.writeHead(404).end('Not found');
    return;
  }

  const state = url.searchParams.get('state');
  const entry = pending.get(state);

  if (!entry) {
    response.writeHead(400).end('State mismatch. Start the flow again.');
    return;
  }

  pending.delete(state);

  const error = url.searchParams.get('error');
  if (error) {
    response.writeHead(400).end(`Authorization denied: ${error}`);
    entry.reject(new Error(`[${entry.provider}] authorization denied: ${error}`));
    return;
  }

  entry.finish(url.searchParams.get('code'), response);
}

The pending map is the state check. A state value gets into that map only when this process generated it, and it's deleted the moment it's used. An unrecognized state means the callback didn't come from a flow you started, and a state that arrives twice means a replay. Both fall out of one Map lookup.

Generating the state and waiting for its callback:

function connect(providerName) {
  const provider = providers[providerName];
  const state = randomBytes(16).toString('hex');

  console.log(`\n[${providerName}] authorize as "${IDENTIFIER}":`);
  console.log(provider.buildAuthorizeUrl(state));

  return new Promise((resolve, reject) => {
    pending.set(state, {
      provider: providerName,
      reject,
      async finish(code, response) {
        const tokens = await provider.exchangeCode(code);
        saveGrant(IDENTIFIER, providerName, tokens);
        response
          .writeHead(200, { 'Content-Type': 'text/html' })
          .end(`<p>${provider.label} connected. You can close this tab.</p>`);
        resolve();
      },
    });
  });
}

randomBytes(16) and not Math.random(). A predictable state parameter is the same as no state parameter.

Running it walks each unconnected provider in turn:

[slack] authorize as "alice@example.com":
https://slack.com/oauth/v2/authorize?client_id=123.456&user_scope=channels%3Ahistory%2Cchat%3Awrite%2Cusers%3Aread&redirect_uri=https%3A%2F%2Flocalhost%3A3000%2Fcallback&state=1159699dbf1a808fd33ba31c7b643505

Notice what that URL doesn't contain: any scope parameter. Slack has no instruction to mint a bot token, so it won't.

How to Store Tokens Encrypted, Keyed by User

The store answers one question: which token belongs to this user, for this provider? Everything else about it follows from keeping that answer safe.

node:sqlite has shipped with Node since v22.5, and stopped requiring a flag in v22.13. That makes a real database available with nothing to install:

import { DatabaseSync } from 'node:sqlite';
import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';

const KEY = Buffer.from(process.env.TOKEN_ENCRYPTION_KEY ?? '', 'base64');

if (KEY.length !== 32) {
  throw new Error(
    'TOKEN_ENCRYPTION_KEY must be 32 bytes, base64-encoded. ' +
      `Got ${KEY.length} bytes.`
  );
}

const db = new DatabaseSync(
  process.env.TOKEN_DB_PATH ?? new URL('../tokens.db', import.meta.url).pathname
);

// One row per user, per provider. expires_at stays outside the ciphertext so
// a token's freshness can be checked without decrypting it.
db.exec(`
  CREATE TABLE IF NOT EXISTS grants (
    identifier TEXT    NOT NULL,
    provider   TEXT    NOT NULL,
    ciphertext BLOB    NOT NULL,
    iv         BLOB    NOT NULL,
    auth_tag   BLOB    NOT NULL,
    expires_at INTEGER,
    PRIMARY KEY (identifier, provider)
  )
`);

The composite primary key is the isolation guarantee, written down. (identifier, provider) means Alice's Slack row and Bob's Slack row can't collide, and no query that supplies both parts can return somebody else's grant.

expires_at sits outside the ciphertext deliberately. Checking whether a token needs refreshing is something you do before every call. Decrypting to find out would mean decrypting constantly, so the one field that isn't a secret stays readable.

Encryption is AES-256-GCM, which authenticates as well as encrypts:

function encrypt(payload) {
  const iv = randomBytes(12);
  const cipher = createCipheriv('aes-256-gcm', KEY, iv);
  const ciphertext = Buffer.concat([
    cipher.update(JSON.stringify(payload), 'utf8'),
    cipher.final(),
  ]);
  return { ciphertext, iv, authTag: cipher.getAuthTag() };
}

function decrypt({ ciphertext, iv, authTag }) {
  const decipher = createDecipheriv('aes-256-gcm', KEY, iv);
  decipher.setAuthTag(authTag);
  const plaintext = Buffer.concat([
    decipher.update(ciphertext),
    decipher.final(),
  ]);
  return JSON.parse(plaintext.toString('utf8'));
}

Three rules govern that pair, and breaking any one of them is worse than not encrypting at all, because it looks like it worked:

1. A fresh IV per encryption: Reusing an initialization vector with GCM is a catastrophic failure, not a minor one. randomBytes(12) on every call, stored beside the ciphertext.

2. Keep the auth tag: GCM produces a tag that proves the ciphertext wasn't altered. Without setAuthTag on the way back, you have encryption without integrity, and decipher.final() won't complain.

3. Encrypt the whole token object, not each field. One ciphertext for { accessToken, refreshToken, scope } means one IV and one tag to manage rather than three of each.

Writing and reading are then unremarkable:

export function saveGrant(identifier, provider, tokens) {
  const { ciphertext, iv, authTag } = encrypt(tokens);
  db.prepare(
    `INSERT INTO grants (identifier, provider, ciphertext, iv, auth_tag, expires_at)
     VALUES (?, ?, ?, ?, ?, ?)
     ON CONFLICT (identifier, provider) DO UPDATE SET
       ciphertext = excluded.ciphertext,
       iv         = excluded.iv,
       auth_tag   = excluded.auth_tag,
       expires_at = excluded.expires_at`
  ).run(identifier, provider, ciphertext, iv, authTag, tokens.expiresAt ?? null);
}

The ON CONFLICT clause matters more than it looks. Re-consenting has to replace a grant rather than fail or duplicate it, and re-consenting is exactly what a user does after a revocation or a scope change.

The encryption key itself lives in .env here, which is right for a tutorial and wrong for production, where it belongs in a secrets manager or a KMS. Losing it makes every stored grant unreadable and forces every user to consent again. That is a real outage, but it's a better one than the alternative: a stolen database file that hands over working tokens for every user of your agent.

How to Run Tool Calls as the Current User

Runtime has three moves: resolve the identifier, fetch a token with it, and wrap the whole thing as a tool.

Step 1: Resolve the Identifier, Then Authorize

An identifier is any stable string that represents one user, an email address, a user ID, a tenant-scoped key.

// In a real app this comes from your authenticated session, resolved
// server-side. Never accept it from client input.
const IDENTIFIER = process.argv[2] ?? 'channel-watcher-agent';

Reading the identifier from argv keeps the demo runnable without a login, and it makes the isolation test later in this tutorial a single command. A real application replaces the line:

// Real app: resolve from your authenticated session, server-side.
const session = await getSession(request);                  // your auth
const identifier = await lookupIdentifier(session.userId);  // your database

Order matters in those two lines. Authenticate the caller first, then look up which identifier the caller may act as. An identifier arriving from a client turns the endpoint into a reader of any user's Slack.

Step 2: Turn the Identifier into a Token, Late

One function stands between the identifier and every provider call:

const REFRESH_WINDOW_MS = 60_000;

export async function getAccessToken(identifier, providerName) {
  const grant = readGrant(identifier, providerName);

  if (!grant) {
    throw new Error(
      `[${providerName}] no grant for "${identifier}".\n` +
        `Connect it first: node src/connect.js ${identifier}`
    );
  }

  const expiringSoon =
    grant.expiresAt !== null &&
    grant.expiresAt !== undefined &&
    grant.expiresAt - Date.now() < REFRESH_WINDOW_MS;

  if (!expiringSoon) {
    return grant.accessToken;
  }

  if (!grant.refreshToken) {
    throw new Error(
      `[${providerName}] token for "${identifier}" expired and no refresh ` +
        'token is stored. The user has to consent again.'
    );
  }

  const refreshed = await providers[providerName].refresh(grant.refreshToken);
  saveGrant(identifier, providerName, refreshed);
  return refreshed.accessToken;
}

Call this immediately before the API call, not once at startup. A long agent run can outlive a twelve-hour token, and resolving tokens up front means discovering that at the least convenient moment. Fetching late costs one cheap database read and removes the whole class of problem.

Also, the sixty-second window isn't padding for its own sake. A token with four seconds left passes a naive expiry check and then expires in flight. Refreshing anything inside the window means the token handed back is good for at least a minute of work.

Finally, a missing grant raises an error rather than falling back. There's nothing sensible to fall back to. The correct outcome for an unconnected user is a stop, with a message saying how to connect.

Step 3: Wrap Provider Calls as Tools

Identity gets injected here, one layer below anything the model can influence:

export function buildTools(identifier) {
  const [owner, repo] = process.env.GITHUB_REPO.split('/');

  const fileGithubIssue = tool({
    description: 'File a GitHub issue for an actionable Slack message',
    inputSchema: z.object({
      title: z.string(),
      body: z.string(),
    }),
    execute: async ({ title, body }) => {
      const token = await getAccessToken(identifier, 'github');
      return createIssue(token, owner, repo, { title, body });
    },
  });

  const replyInSlackThread = tool({
    description:
      'Reply in the original Slack thread (e.g. with the created issue link)',
    inputSchema: z.object({
      text: z.string(),
      thread_ts: z.string(),
    }),
    execute: async ({ text, thread_ts }) => {
      const token = await getAccessToken(identifier, 'slack');
      return postThreadReply(
        token,
        process.env.SLACK_CHANNEL_ID,
        text,
        thread_ts
      );
    },
  });

  return { fileGithubIssue, replyInSlackThread };
}

Compare what the model controls against what it can't. The model chooses title, body, and text. The model can't choose the user. identifier is a closure argument, fixed before the model ran, and it appears in no inputSchema. There's no input that makes the model file an issue as somebody else, because the account isn't one of its inputs.

Return values deserve one audit each. createIssue returns the issue number, URL, and title. postThreadReply returns a timestamp. Neither returns a token, and neither returns the raw provider response, which is where a token would hide if one were going to.

The provider calls themselves are ordinary HTTP:

export async function createIssue(token, owner, repo, { title, body }) {
  const response = await fetch(
    `https://api.github.com/repos/${owner}/${repo}/issues`,
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${token}`,
        Accept: 'application/vnd.github+json',
        'X-GitHub-Api-Version': '2022-11-28',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ title, body }),
    }
  );

  const json = await response.json();

  if (!response.ok) {
    // 403 here usually means the grant is missing the `repo` scope.
    throw new Error(
      `GitHub issue creation failed (${response.status}): ${json.message}`
    );
  }

  return { number: json.number, url: json.html_url, title: json.title };
}

Step 4: Read the Channel

Slack's conversations.history returns clean JSON, with one gap: messages carry a user ID, never a display name. Turning those into names means a users.info call each, which is what users:read was in the scope list for.

export async function readChannel(token, channelId, limit = 20) {
  const { messages } = await slackCall(token, 'conversations.history', {
    channel: channelId,
    limit: String(limit),
  });

  const authors = await resolveAuthors(
    token,
    messages.filter((m) => m.user).map((m) => m.user)
  );

  return messages
    .filter((message) => message.text)
    .map((message) => ({
      author: authors.get(message.user) ?? 'unknown',
      userId: message.user,
      text: message.text,
      ts: message.ts,
    }))
    .reverse(); // oldest first
}

Three small decisions in that function:

1. Names cost one users.info call per unique author. Caching them per run keeps a channel full of one person's messages from producing twenty identical lookups. A lookup that fails falls back to the user ID rather than throwing, since an unresolvable name isn't a reason to abandon the run.

2. Messages without text get dropped. Channel joins and purpose changes arrive as message objects with no body, and there's nothing for the model to triage in them.

3. .reverse() isn't cosmetic. Slack returns newest first. A model reading a conversation backwards will misread which message answered which.

The ts field then does double duty. It identifies a message, which makes it both the thread anchor for replies and the key for remembering what the agent already handled:

const state = await loadState();
const processed = new Set(state[IDENTIFIER]?.processedTs ?? []);
const newMessages = messages.filter((m) => !processed.has(m.ts));

Key that state by identifier, as the snippet does. A single flat list lets one user's processed messages hide another's, which reintroduces cross-user bleed in the one place the whole design exists to prevent.

Step 5: Run the Tool Loop

Hand the model both tools and let it decide:

const { text } = await generateText({
  model: anthropic(process.env.MODEL),
  tools,
  stopWhen: stepCountIs(5),
  prompt: `You triage messages from a dev team's Slack channel.

Message from ${message.author}: "${message.text}"
Message timestamp (thread_ts): ${message.ts}

Decide if this message is actionable (a bug report or concrete action item) or just noise (chit-chat, join notices, already-resolved chatter).

If actionable: file a GitHub issue with a clear title and body drafted from the message, then reply in the original Slack thread (use the exact thread_ts above) with a short note and the created issue's URL.

If not actionable: do nothing and briefly say why.`,
});

The loop is what makes the second step possible. The model reads the message and may call fileGithubIssue. The AI SDK runs the tool, feeds the result back into context along with the new issue URL, and calls the model again. Now the model can reply in the thread with a URL it couldn't have known on the first pass. Then it stops.

stopWhen: stepCountIs(5) caps the rounds. Without a bound, a confused model can retry a failing tool indefinitely. Five rounds is generous for two tools.

A deterministic version is also reasonable: classify with a structured-output call, then call both tools yourself in a fixed order when the message qualifies.

The fixed sequence is easier to test and gives up real flexibility. A loop lets the model skip the reply, or file without replying, and adding a third tool needs no new branching. Choose the loop when the set of actions varies per input, and the fixed sequence when it never does.

One note on the provider line, for accuracy about what ran. The snippet above uses @ai-sdk/anthropic, which suits a direct Anthropic API key. My own tests went through an OpenAI-compatible gateway, which changes only the provider construction:

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';

const gateway = createOpenAICompatible({
  name: 'gateway',
  baseURL: `${process.env.GATEWAY_BASE_URL}/v1`,
  apiKey: process.env.GATEWAY_API_KEY,
});
// then: model: gateway(process.env.MODEL)

The tools, the loop, and the token handling are identical either way. Only the model argument changes.

How to Handle Refresh and Revocation

Tokens end in two different ways, and only one of them is your code's problem**.** Expiry is routine and recoverable. Revocation is a decision somebody made, and the correct response is to ask for consent again.

The two providers in this tutorial sit at opposite ends of the range, which makes them a useful pair.

GitHub: Tokens That Don't Expire, Until They Do

An OAuth App user token has no expiry timestamp. There's no refresh token to store and no refresh call to make, which is why github.refresh() in this project does nothing but explain itself:

async refresh() {
  throw new Error(
    'GitHub OAuth App tokens do not expire. A failure here means the ' +
      'grant was revoked — send the user through consent again.'
  );
}

"Does not expire" is not the same as "lasts forever," and GitHub revokes tokens for several reasons worth knowing:

• The user revokes the authorization from their account settings.

• The token goes unused for one year.

• The token gets pushed to a public repository or gist, at which point GitHub revokes it automatically.

• The app accumulates more than ten tokens for the same user and scope combination, and the oldest are revoked.

The third one deserves a moment. GitHub scans public pushes for its own token formats and kills what it finds. That is a safety net, not a strategy, and the one thing it can't protect is a token in a private repository or a log file.

GitHub Apps behave differently from OAuth Apps, which is a common source of confusion when reading GitHub's documentation. A GitHub App's user access token expires in eight hours and comes with a refresh token good for six months. If you build on GitHub Apps instead, the Slack-shaped refresh path below is the one you want.

Slack: Rotation is Opt-in and Permanent

By default, a Slack user token doesn't expire either. Token rotation changes that, and it comes with a warning worth repeating: rotation can't be turned off once it's turned on. Enable it on a test app first.

With rotation on, tokens live twelve hours and arrive with a refresh token. The refresh call reuses the same endpoint as the initial exchange, with a different grant type:

async refresh(refreshToken) {
  const response = await fetch(this.tokenUrl, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'refresh_token',
      refresh_token: refreshToken,
      client_id: process.env.SLACK_CLIENT_ID,
      client_secret: process.env.SLACK_CLIENT_SECRET,
    }),
  });

  const json = await response.json();
  if (!json.ok) {
    throw new Error(`Slack token refresh failed: ${json.error}`);
  }

  return normalizeSlackTokens(json.authed_user ?? json);
}

Store the new refresh token, not just the new access token. Refresh tokens rotate too. Writing back only the access token leaves you holding a spent refresh token, and the failure arrives twelve hours later, which is a long time to wait to learn something.

That write-back is why getAccessToken calls saveGrant after refreshing rather than returning the token and moving on.

Treat a Dead Grant as a Normal State

A revoked grant isn't an exception in the exceptional sense. Users leave, administrators tighten scopes, and people change their minds about what an agent may do.

The shape that works is the one getAccessToken already uses: catch the failure, and surface a fresh authorization link rather than a stack trace. connect.js with the same identifier lets the user re-consent, ON CONFLICT overwrites the dead row, and nothing else in your user record changes.

How to Add a Second Provider

A second provider costs one OAuth app, one entry in the providers object, and one tool. Keeping identity in a single string is what buys the discount.

The agent has used two providers all along. Worth noticing is what the second one didn't require: no second identity, no second consent server, and no second token table.

export const providers = {
  slack: { /* ... */ },
  github: { /* ... */ },
};

Google Calendar as a third means a third entry with its own authorizeUrl, tokenUrl, scopes, and exchangeCode. The consent server loops over Object.keys(providers), so it picks the new one up without modification. The store already keys on (identifier, provider), so it needs no migration. Then one more tool:

const createCalendarEvent = tool({
  description: 'Create a calendar event',
  inputSchema: z.object({ summary: z.string(), start: z.string() }),
  execute: async ({ summary, start }) => {
    const token = await getAccessToken(identifier, 'google-calendar');
    // ...one more provider call
  },
});

The identifier doesn't change, your user table doesn't change, and the model's view of the world grows by exactly one tool.

The cost that doesn't scale down is the provider-specific knowledge. Each new provider brings its own scope vocabulary, its own error format, and its own answer to whether tokens expire. Slack and GitHub disagreed on all three, and a third will disagree differently. The registry pattern contains that knowledge in one object per provider rather than spreading it through your agent, but it doesn't make the knowledge unnecessary.

One caveat on consent: A grant is per user, per provider. Alice connecting Slack but not Calendar means her calendar tool calls fail, and failure is correct there, since she never consented. Treat it as a prompt to connect rather than an error, a point the Failure Modes section returns to.

Full Walkthrough

Clone the repository, install, and fill in .env:

git clone https://github.com/saif-shines/channel-watcher-agent.git
cd channel-watcher-agent
npm install
cp .env.example .env
# fill in both client IDs and secrets, the encryption key, channel ID, repo

Then connect. The command starts the callback server and prints one link per unconnected provider:

npm run connect

[slack] authorize as "channel-watcher-agent":
https://slack.com/oauth/v2/authorize?client_id=123.456&user_scope=channels%3Ahistory%2Cchat%3Awrite%2Cusers%3Aread&redirect_uri=https%3A%2F%2Flocalhost%3A3000%2Fcallback&state=1159699dbf1a808fd33ba31c7b643505
[slack] connected.

[github] authorize as "channel-watcher-agent":
https://github.com/login/oauth/authorize?client_id=Iv1.abc&scope=repo&redirect_uri=https%3A%2F%2Flocalhost%3A3000%2Fcallback&state=e6d13461099c391367266235f8313630
[github] connected.

All providers connected. Run: node src/index.js channel-watcher-agent

Open each link, consent, and the tab confirms. The state parameter in those URLs is checked on the way back. A callback carrying anything else gets a 400 and never reaches the token exchange.

Then run the agent against a channel holding ordinary chatter:

node src/index.js

The output from that run, against a channel with three unremarkable messages:

[channel-watcher-agent] 3 messages fetched, 3 new.

--- Alex: "Sending draft message" ---
The message "Sending draft message" is noise — it appears to be a test or
accidental send, not a bug report or concrete action item.

...

No tools called, and no issues filed. The negative case matters more than it looks. An agent with write access that can't say no is a liability, and a run over ordinary chatter is the cheapest available test of its restraint.

Now post an actual bug report in the channel:

hey the /export endpoint is timing out for any file over 50MB, been happening since yesterday's deploy

Run the agent again, and the state file keeps the earlier messages from being triaged twice.

Authorship is the part that matters. The GitHub account behind the identifier opens the issue, using that user's own OAuth grant, not a shared bot. The Slack reply comes from that person too. Revoke their access and the next run fails at getAccessToken, which is the correct outcome.

What Changes for a Second User

The identifier comes from the command line, so isolation is testable without building a login first:

node src/index.js                     # the identifier you already authorized
node src/index.js alice@example.com   # a different user entirely

The second command never reads the channel. It stops:

[slack] no grant for "alice@example.com".
Connect it first: node src/connect.js alice@example.com

The refusal is the whole point. Nothing about the agent changed between the two commands. Same providers, tools, and code. Only the identifier differed, and Alice hasn't consented, so no row exists to decrypt and the run stops before touching Slack.

A shared-bot version behaves differently. The second command would read the channel and file an issue as the bot, because no per-user grant was ever involved.

Once Alice consents, everything downstream follows her grant. readGrant returns her row. getAccessToken decrypts her token. The Slack read returns the channels she can see, and her GitHub account authors the issue.

Production replaces argv with a session lookup:

const identifier = await lookupIdentifier(session.userId);

Testing the Isolation Without Credentials

The repository includes a test suite that replaces fetch with stand-in Slack and GitHub endpoints, so the request building, response parsing, storage, and refresh logic all run without a single OAuth app registered:

npm test

Three of those tests are worth naming, because they check the claims this tutorial makes rather than the code's internals:

• Slack exchange keeps the user token and discards the bot token. The fixture returns both. The test asserts the stored value is the xoxp- one.

• Two users get two different tokens from identical tool inputs. Same text, same thread_ts, two identifiers, two different Authorization headers reaching the provider.

• A tool built for an unconnected user fails instead of falling back. It also asserts that zero provider calls were attempted, since failing after leaking a request isn't much of a failure.

Tests that pass on the first run are worth distrusting, so I checked these by breaking the code on purpose. Substituting the bot token for the user token, ignoring the identifier in buildTools, and exposing identifier in the model-visible schema each fail at least one test.

How to Apply the Pattern to Other Use Cases

Nothing in the pattern is specific to Slack triage. The shape is: read from one app, decide with a model, write to another app, all as one user.

Swapping the providers produces a different product:

Every row uses the same three pieces: a provider entry, a token lookup by identifier, and a tool. Only three things change: the OAuth app registrations, the API calls inside execute, and the input you write for the model.

The input is where your product lives. OAuth is plumbing. Deciding which messages deserve an issue, and what the issue should say, is judgment, and judgment is the part worth your weeks.

The same code supports two deployment shapes:

• Internal team agent: The identifier is the teammate who triggered the run. Runs on a schedule or a command.

• Customer-facing agent: The identifier comes from your tenant and user records. Runs on customer data, inside customer accounts.

The code stays identical. The consequences of a wrong identifier do not.

What Went Wrong When I Built This

These are problems I hit while building the project, in roughly the order they showed up. If you hit the same ones, the fix is usually small.

Slack Won't Save the Redirect URL

The symptom arrives before any code runs: the Slack app configuration page refuses to accept http://localhost:3000/callback.

Slack requires HTTPS on redirect URLs with no exception for localhost. Issue a local certificate with mkcert, register the https:// form, and point TLS_CERT_PATH and TLS_KEY_PATH at the files it wrote. GitHub accepts either scheme, so the same HTTPS URL works for both apps.

The Browser Warns That the Certificate Isn't Trusted

mkcert -install is the step that adds mkcert's local authority to your system trust store, and skipping it leaves a certificate no browser recognises.

Running it once fixes every certificate mkcert issues afterwards. A self-signed certificate made with openssl will always warn, since nothing trusts it.

The Redirect URI Doesn't Match

Both providers compare the redirect_uri you send against the one registered with the app, and the comparison is exact. A trailing slash, 127.0.0.1 in place of localhost, http where you registered https, or a different port all fail.

The error arrives before consent, on the provider's own page, which at least makes it easy to spot. Keep OAUTH_REDIRECT_URI as the single source and pass it in both the authorize URL and the token exchange, as the provider registry does.

The Callback Port is Already in Use

connect.js binds the port from OAUTH_REDIRECT_URI, and port 3000 is popular. An unhandled EADDRINUSE produces a stack trace that says nothing about OAuth, so the project catches it and says what to do instead.

Changing the port means changing it in three places: .env, the Slack app's redirect URLs, and the GitHub app's callback URL. Missing one produces the previous failure.

The State Check Rejects a Legitimate Callback

State values live in memory and are deleted once used. Restarting connect.js after opening the link, or refreshing the callback tab, both produce a state that's no longer in the map.

Both are correct rejections. Generate a fresh link and start again.

Tool Calls Return Permission Errors or Empty Results

A missing scope or a revoked grant causes both.

GitHub answers 403 with "Resource not accessible" when the grant lacks repo. Slack answers 200 with ok: false and an error like missing_scope. Fix the scope list, then send the user through consent again, since an existing grant doesn't gain scopes retroactively.

A partially-scoped grant fails at the point of use rather than at connection time, which is what makes the symptom look mysterious. The consent screen succeeded, the token stored fine, and the failure arrives during a tool call hours later.

The Agent Reads Channels it Shouldn't

The single most likely cause is storing json.access_token instead of json.authed_user.access_token during the Slack exchange. Both are strings, both are truthy, and both work (one works as the app rather than the person).

The tell is the scope of what comes back. A user token returns only that person's channels. If conversations.history returns a channel the current user was never in, a bot token is in the store.

A Tool Call Runs as the Wrong User

Passing a token or identifier belonging to somebody else will do the wrong thing correctly.

Two habits prevent it. Resolve the identifier server-side after authenticating the caller, never from client input. Then take the identifier as a closure argument in buildTools and let each execute fetch its own token, so no code path can pass a stray credential.

Refresh Works Once and Then Stops

Refresh tokens rotate. A refresh that writes back the new access token but keeps the old refresh token succeeds immediately and fails on the following cycle, which puts twelve hours between the bug and its symptom.

saveGrant takes the whole normalized token object for this reason. Write back everything the refresh returned.

The Agent Files Duplicate Issues

Two causes. A missing or unwritten state file makes every run triage everything again. Or stopWhen allows enough rounds for a confused model to retry a tool that already succeeded.

Check the state file first. Then check whether the tool's return value clearly signals success, because an ambiguous result invites a retry.

Conclusion

You've built an agent that reads a Slack channel, judges which messages describe real work, files GitHub issues for those, and closes the loop with a threaded reply. Every call ran as one specific user's own OAuth grant, through an OAuth flow and a token store you wrote yourself.

Five ideas carry over to any provider:

• A tool is an API call plus an explanation for a model, and the explanation is most of the work.

• The identifier replaces the token in your agent code. Everything above one small function handles a reference to a user rather than a credential, so tokens never reach your model inputs or your logs.

• Connection time and runtime are separate flows. Consent happens once per user, per app. Runtime resolves an identifier and fetches a token late.

• Authorization stays yours. A token store answers which tokens belong to an identifier. Whether a caller may act as that identifier is a question only your code can answer.

• Multi-provider support is a registry problem, not an architecture problem, once identity lives in one string.

The detail that carries the most weight is also the smallest: authed_user.access_token rather than access_token. One property access decides whether your agent respects the permissions your workspace already has or quietly routes around them.

From here, keep the shape and swap the providers. Point the read half at Gmail and the write half at Linear, then rewrite the input for the model. The identity plumbing doesn't change.

The full source is at github.com/saif-shines/channel-watcher-agent.

This write-up reconstructs what we learned building Scalekit, a hosted version of the token vault you just built.

In my previous guide, How OAuth 2.0 Works: A Practical Guide for Backend Developers, I briefly touched on the mysterious state parameter and noted that its core purpose is protecting authorization flows against CSRF attacks.

At the time, we treated CSRF as a quick prerequisite concept. Today, we're taking a much deeper dive.

Perhaps you were building a REST API in Spring Boot, ran into unexpected HTTP 403 Forbidden errors on every POST request, and "fixed" it by adding .csrf(csrf -> csrf.disable()) to your Security Filter Chain.

Most tutorials treat CSRF as a checkbox item or a framework toggle. They immediately jump to code:

// What most tutorials show on line 1:
http.csrf(Customizer.withDefaults());

Starting with framework configuration hides how web security actually operates. Spring Security doesn't invent security rules out of thin air. It responds to the fundamental mechanics of web browsers, HTTP protocols, and cookies.

In this handbook, we'll take a bottom-up, first-principles approach. We won't talk about Spring Security until we've thoroughly explored browsers, HTTP headers, session management, and the underlying mechanics of Cross-Site Request Forgery.

By the end of this guide, you'll understand:

• Why browsers automatically attach credentials to outgoing requests.

• Why that automatic behavior creates a fundamental vulnerability.

• Why attackers never need to steal or read your cookies to exploit CSRF.

• Why Same Origin Policy (SOP) and CORS don't prevent CSRF.

• How modern defenses, from CSRF Tokens to SameSite cookies, work under the hood.

• How Spring Security implements these defenses internally and how to configure them effectively.

Let’s begin by stripping away frameworks and looking at how the web actually works.

Table of Contents

• The Problem Before CSRF

• Why Browsers Automatically Send Cookies

• When Automatic Cookies Become Dangerous

• Visualize the Attack

• Why the Browser Isn't Broken

• Same Origin Policy (SOP)

• Why CORS Does NOT Prevent CSRF

• Safe Methods and State Mutation

• CSRF Tokens (Synchronizer Token Pattern)

• Double Submit Cookie Pattern

• SameSite Cookies

• Origin and Referer Headers

• JWT and CSRF: The Token Storage Dilemma

• Spring Security CSRF Internals

• Implement CSRF Protection Yourself

• Testing CSRF Protections

• Common Misconceptions

• Production Best Practices Checklist

• Final Summary & Defense Matrix

The Problem Before CSRF

To understand security, we must first understand state.

The Hypertext Transfer Protocol (HTTP) is inherently stateless. This means that if Alice sends an HTTP request to travelbuddy.com (our example) at 10:00 AM, and sends another HTTP request to travelbuddy.com at 10:01 AM, the server treats those two requests as completely isolated, unrelated events.

Without a mechanism to remember Alice between requests, Alice would have to send her username and password inside every single HTTP request she makes. That would be horrific for both user experience and performance.

Before session mechanisms were standard, developers tried passing credentials via query parameters or basic authentication headers on every click. This led to credential exposure in server logs, browser histories, and URL shares.

How Do Sessions and Cookies Solve This?

To solve this, web engineers introduced the concept of Server-Side Sessions and HTTP Cookies.

When Alice logs into TravelBuddy by sending her username and password via a POST request to https://travelbuddy.com/login, the server verifies her credentials. Instead of asking Alice to log in again on the next page, the server creates a Session in its memory (or in a database/Redis cache) and assigns it a unique, unpredictable identifier: a Session ID.

The server then sends this Session ID back to Alice’s browser using a special HTTP response header: Set-Cookie.

HTTP/1.1 200 OK
Content-Type: text/html
Set-Cookie: JSESSIONID=abc123xyz789; Path=/; Secure; HttpOnly

When Alice’s browser receives this response, it sees the Set-Cookie header. It extracts JSESSIONID=abc123xyz789 and stores it inside its internal storage unit: the Browser Cookie Jar.

Now, Alice is "logged in". The server remembers her via that session record, and the browser holds the key (JSESSIONID) to that session.

Why Browsers Automatically Send Cookies

Now we arrive at the pivotal design choice made in the early days of the web.

Once the browser stores JSESSIONID=abc123xyz789 in its cookie jar for the domain travelbuddy.com, how does that cookie get sent back to the server on subsequent requests?

Does the developer have to write custom JavaScript to attach the cookie? No.

Browsers are explicitly designed to handle cookie management automatically.

The Request Lifecycle and Automatic Cookie Attachment

Every time Alice's browser prepares an HTTP request to https://travelbuddy.com (whether caused by Alice clicking a link, submitting an HTML form, or JavaScript triggering a fetch() call), the browser follows this exact process:

1. URL Inspection: The browser examines the destination URL (for example, https://travelbuddy.com/api/connections).

2. Cookie Jar Lookup: The browser scans its cookie jar for any stored cookies whose domain and path match travelbuddy.com.

3. Validation Check: It verifies if the cookie has expired, and if flags like Secure (requires HTTPS) are respected.

4. Header Injection: If valid cookies match, the browser automatically injects a Cookie header into the outgoing HTTP request payload.

Here's what the outgoing request looks like as it leaves Alice's machine:

POST /api/connections/add HTTP/1.1
Host: travelbuddy.com
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)
Accept: text/html,application/xhtml+xml
Cookie: JSESSIONID=abc123xyz789
Content-Type: application/x-www-form-urlencoded

service=SkyScanner

Notice something critical: Neither Alice nor any custom frontend JavaScript explicitly attached Cookie: JSESSIONID=abc123xyz789.

The browser's internal engine attached it automatically before sending the byte stream across the network. From the server's perspective, receiving Cookie: JSESSIONID=abc123xyz789 is proof that the request originated from an authenticated session belonging to Alice.

This automatic behavior is convenient. It makes web browsing seamless across page reloads and link navigation. But as we'll soon see, this convenience leaves a backdoor wide open.

When Automatic Cookies Become Dangerous

Is automatic cookie inclusion a vulnerability by itself?

No. If Alice only visits travelbuddy.com, automatic cookie inclusion works exactly as intended.

The vulnerability emerges because of a simple web reality: Alice visits multiple websites in the same browser session.

Enter evil.com

Suppose Alice is logged into TravelBuddy in Tab 1. Her session cookie (JSESSIONID=abc123xyz789) sits safely inside her browser's cookie jar for travelbuddy.com.

In Tab 2, Alice visits an unrelated website: https://evil.com (perhaps she clicked a link in a phishing email or a forum post).

evil.com is controlled by an attacker. The attacker knows that TravelBuddy has a feature located at POST [https://travelbuddy.com/api/connections/add that connects third-party services. The attacker wants to trick Alice into connecting the attacker's malicious service to her account.

The attacker embeds the following hidden HTML form inside the HTML page served by evil.com:

<!-- Hosted on https://evil.com/win-a-car.html -->
<!DOCTYPE html>
<html>
<body>
  <h1>You won a free trip! Click below to claim.</h1>
  
  <!-- Hidden Form targeting TravelBuddy -->
  <form id="maliciousForm" action="https://travelbuddy.com/api/connections/add" method="POST">
    <input type="hidden" name="service" value="MaliciousAttackerService" />
  </form>

  <script>
    // Automatically submit the form as soon as the page loads
    document.getElementById('maliciousForm').submit();
  </script>
</body>
</html>

Walkthrough of the Attack Execution

Let's trace step-by-step what happens when Alice opens https://evil.com/win-a-car.html:

1. Alice's browser fetches and parses HTML from evil.com.

2. The browser encounters the <script> tag and executes document.getElementById('maliciousForm').submit().

3. The browser prepares an outgoing POST request targeting https://travelbuddy.com/api/connections/add.

4. The browser looks at the target destination: travelbuddy.com.

5. The browser checks its Cookie Jar: "Do I have any active cookies for travelbuddy.com?"

6. Yes! It finds JSESSIONID=abc123xyz789 (Alice's active session cookie from Tab 1).

7. The browser automatically injects Cookie: JSESSIONID=abc123xyz789 into the outgoing request payload heading to travelbuddy.com.

8. The request lands on the TravelBuddy Spring Boot backend server.

The Server's Perspective

Here's what the TravelBuddy backend sees when processing the request:

POST /api/connections/add HTTP/1.1
Host: travelbuddy.com
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)
Content-Type: application/x-www-form-urlencoded
Cookie: JSESSIONID=abc123xyz789

service=MaliciousAttackerService

The TravelBuddy server checks the Cookie header. It validates JSESSIONID=abc123xyz789 against its session store. The session is valid: it belongs to Alice!

The server assumes: "Alice sent a POST request to add MaliciousAttackerService. She is authenticated, so I will grant this request."

The server updates Alice's account state. MaliciousAttackerService is now connected to her profile.

The Core Realization of CSRF

Take a step back and examine what just happened:

1. The attacker NEVER saw or stole Alice’s session cookie. The attacker on evil.com can't read cookies belonging to travelbuddy.com due to browser isolation rules.

2. The attacker did NOT break encryption. HTTPS was active the entire time.

3. The attacker simply induced Alice's browser to make a request. The browser, faithfully executing its automatic cookie attachment rules, provided the credentials on behalf of the attacker. You could say the attacker got caught with their hand in Alice's cookie jar!

This is Cross-Site Request Forgery in action: An attacker tricks a victim's browser into executing an unwanted, state-changing HTTP request to a trusted site where the victim is currently authenticated.

Visualize the Attack

Visualizing the interaction between Alice, the browser, evil.com, and TravelBuddy makes the underlying request flow clear.

1. The Complete CSRF Sequence

The attack unfolds across three distinct phases involving four main actors: Alice, her web browser, the TravelBuddy backend server, and the attacker site running on evil.com.

In the first phase, Alice authenticates with TravelBuddy. She submits her login credentials through her browser, which sends a POST request to the TravelBuddy backend. The backend verifies her credentials and responds with an HTTP 200 OK status alongside a Set-Cookie header containing JSESSIONID=abc123xyz.

Upon receiving this response, Alice's browser automatically saves this session identifier inside its cookie jar for the travelbuddy.com domain.

In the second phase, the attacker sets a trap. While keeping her TravelBuddy tab active, Alice opens a second browser tab and visits evil.com. Her browser requests the page win-a-car.html from evil.com. In response, evil.com serves an HTML document containing an invisible form targeting TravelBuddy, paired with an embedded JavaScript script designed to trigger immediately upon loading.

In the final phase, the attack executes automatically. The malicious JavaScript on evil.com calls form.submit(), commanding the browser to send a POST request to https://travelbuddy.com/api/connections/add.

Before sending the request across the network, the browser checks its cookie jar for any cookies matching travelbuddy.com. It finds Alice's active session cookie and automatically attaches Cookie: JSESSIONID=abc123xyz to the outgoing request payload. The TravelBuddy server receives the request, inspects the valid session cookie, assumes Alice intended to perform this action, and attaches the attacker's service to her account.

2. Browser Decision Tree during Outgoing Request

When any request is fired, the browser follows a decision path regarding cookie attachment:

This diagram outlines the automatic evaluation loop executed by a browser whenever an HTTP request is triggered from any tab or script.

The process begins as soon as an outgoing HTTP request is initiated. The browser first inspects the target URL to extract the destination domain, such as travelbuddy.com. Once the domain is identified, the browser queries its internal cookie storage to check whether any cookies are mapped to that target domain. If no matching cookies exist, the browser immediately skips credential attachment and dispatches the raw HTTP request across the network.

If matching cookies are found, the browser evaluates their validity. It checks whether the cookies have expired, whether the request path matches the path defined in the cookie, and whether security constraints like the Secure HTTPS flag are satisfied. If any validation check fails, the cookie is discarded, and the request proceeds without credentials. But if the cookies are valid and active, the browser constructs a Cookie header containing the stored session key and attaches it to the outgoing HTTP request payload before dispatching it across the network to the server.

3. Session and Cookie Lifecycle State Diagram

This state diagram tracks how a user moves between secure, authenticated, and vulnerable conditions during a web session.

When a user first opens their web browser, they begin in an unauthenticated state with no cookies stored for the target application. Submitting valid credentials via a login form transitions the user into an authenticated state. Inside this authenticated state, the server issues a Set-Cookie header, causing the browser to save the session ID in its cookie storage. For every subsequent request directed to that application, the browser automatically attaches the cookie while keeping the user logged in.

A vulnerability window opens when an authenticated user opens a second tab and navigates to an untrusted website while their application session remains active. This action shifts the browser context into a state vulnerable to Cross-Site Request Forgery. If the untrusted site fires a cross-site request back to the original application, the browser's automatic cookie attachment mechanism triggers, executing an unauthorized state change on the server. The cycle ends only when the user logs out or the server session expires, returning the client to the initial unauthenticated state.

Why the Browser Isn't Broken

When developers first grasp CSRF, their immediate reaction is often: "This is a terrible browser flaw! Why don't browser vendors fix this by disabling automatic cookie sending entirely?"

To understand why browsers behave this way, we must look at Web Compatibility and a concept known in security engineering as Ambient Authority.

The Principle of Ambient Authority

When a system automatically applies a user's identity or credentials to every action without requiring explicit user intent for that specific action, the system is using ambient authority.

HTTP cookies are an ambient credential. If you're logged in, every request carrying a destination URL automatically includes your credential.

Why Browser Vendors Don't Just "Fix" It

The World Wide Web was created as a web of interconnected hypermedia documents. Cross-site interactions are a fundamental design feature of the web, not an accidental bug:

• Images and assets: When news.com embeds an image hosted on cdn.com, your browser makes a cross-site request to cdn.com.

• Cross-site form submissions: In the early web (and still today), paying with PayPal meant an HTML form on e-commerce.com submitted data directly to paypal.com.

• Hyperlinks: Clicking a link on google.com takes you to wikipedia.org via a cross-site GET request.

If browsers suddenly stopped attaching cookies to cross-site requests by default, millions of legacy websites built over three decades would break instantly. Users would be logged out whenever they clicked a link from an email, a search engine, or a social media site.

Browser vendors prioritize backward compatibility. Rather than removing cross-site capabilities, they introduced configurable security boundaries that developers can opt into.

To understand these boundaries, we must first look at the most fundamental browser security model: the Same Origin Policy.

Same Origin Policy (SOP)

Many developers assume: "Doesn't the Same Origin Policy block cross-site requests?"

This is one of the most common misunderstandings in web development. Let's clarify what the Same Origin Policy actually is and what it does.

Defining an Origin

An Origin in web security is defined by three components:

1. Scheme (Protocol, for example, http vs https)

2. Host (Domain, for example, travelbuddy.com)

3. Port (for example, :80, :443, :8080)

Two URLs have the Same Origin if and only if all three components match exactly.

What SOP Protects vs. What SOP Allows

The Same Origin Policy governs how scripts running on one origin can interact with resources on another origin.

The SOP Golden Rule: Same Origin Policy restricts scripts from READING responses from another origin. Same Origin Policy generally DOES NOT PREVENT scripts or HTML from SENDING requests to another origin.

Let's emphasize this distinction:

Sending a request: evil.com can create an HTML form like this: <form action="https://travelbuddy.com/api/delete" method="POST">. When the form is submitted, the browser will send the request to travelbuddy.com. The backend will process the request and mutate the database state.

Reading the response: JavaScript running on evil.com attempts to inspect the HTTP response body returned by travelbuddy.com. The browser blocks JavaScript from reading that data because evil.com and travelbuddy.com are different origins.

Notice the flaw relative to CSRF: CSRF is an attack on state mutation, not data retrieval.

The attacker on evil.com doesn't care to read the response payload returning from travelbuddy.com. Their goal was simply to trigger the action on the server. Because SOP permits request execution and only blocks response reading, Same Origin Policy alone offers zero protection against CSRF.

Why CORS Does NOT Prevent CSRF

This brings us to another major source of confusion: Cross-Origin Resource Sharing (CORS).

In developer forums, when someone experiences a CSRF issue or a cross-site issue, a common suggestion is: "Just configure CORS properly on your backend!"

Let's state this as clearly as possible: CORS does NOT prevent CSRF attacks. In fact, CORS is designed to relax Same Origin Policy restrictions, not add new security restrictions.

Reading vs. Sending Revisited

Remember: SOP blocks cross-origin reading by default.

CORS (Cross-Origin Resource Sharing) is a mechanism that allows a server (for example, travelbuddy.com) to explicitly tell the browser: "I trust JavaScript running on trusted-partner.com. You may allow trusted-partner.com to read my responses."

CORS is an opt-in mechanism to allow cross-origin reading. Disabling or improperly configuring CORS doesn't stop a browser from sending a forged request.

Simple Requests vs. Preflighted Requests

To understand why CORS fails to stop CSRF, we must examine how browsers handle cross-origin HTTP requests under CORS rules. Browsers divide cross-origin requests into two categories:

1. Simple Requests

2. Preflighted Requests

1. Simple Requests

A request is considered a Simple Request if it satisfies all of the following:

• Uses HTTP methods: GET, HEAD, or POST.

• Uses standard browser Content-Types: application/x-www-form-urlencoded, multipart/form-data, or text/plain.

• Doesn't set custom HTTP headers (like X-Requested-With or Authorization).

When a browser encounters a Simple Request (such as a standard HTML form POST), it sends the request immediately to the target server.

As the diagram shows, the server executes the SQL UPDATE or INSERT statement the moment the request arrives. By the time the browser evaluates CORS headers on the returning response, the state mutation on the server has already happened.

2. Preflighted Requests

If a request uses non-standard methods (PUT, DELETE) or non-standard content types (application/json), or custom headers, the browser first sends an OPTIONS request called a Preflight Request.

Because OPTIONS preflight requests don't carry side-effects and are checked before sending the actual request, CORS incidentally stops cross-origin JSON requests from unapproved domains.

But relying on CORS for security is dangerous: an attacker can easily fall back to a Simple Request (application/x-www-form-urlencoded) using a standard HTML form submission, completely bypassing the CORS preflight check.

Safe Methods and State Mutation

Before we dive into effective defenses, we must address an architectural concept defined in HTTP specifications (RFC 9110): Safe Methods and Idempotency.

HTTP methods are categorized based on their intended impact on server state:

• Safe Methods (GET, HEAD, OPTIONS, TRACE): These methods are defined as read-only operations. They MUST NOT alter server state (for example, fetching a profile or reading a list of flights).

• Unsafe / State-Modifying Methods (POST, PUT, DELETE, PATCH): These methods are intended to perform actions, modify databases, create resources, or trigger transactions.

The Developer Crime: State-Changing GET Requests

Consider what happens if a junior developer on the TravelBuddy team writes code like this:

// ❌ DANGEROUS CODE: State mutation via GET request
@GetMapping("/api/connections/delete")
public String deleteConnection(@RequestParam String serviceId, HttpSession session) {
    User user = (User) session.getAttribute("user");
    connectionService.deleteForUser(user, serviceId);
    return "redirect:/dashboard";
}

Why is this an architectural error and a massive security vulnerability?

Because an attacker on evil.com doesn't even need an HTML form or JavaScript to trigger a GET request. They can trigger a GET request using simple HTML element tags:

<!-- Hosted on evil.com -->
<img src="https://travelbuddy.com/api/connections/delete?serviceId=SkyScanner" width="0" height="0" />

When Alice's browser parses the HTML from evil.com, it encounters the <img> tag. To render the page, the browser automatically sends a GET request to https://travelbuddy.com/api/connections/delete?serviceId=SkyScanner, automatically attaching Alice's session cookie.

The backend receives the GET request, executes connectionService.deleteForUser(...), and wipes Alice's integration!

Rule #1 of Web Security

GET requests MUST ALWAYS be safe and read-only. Never perform state mutations (creates, updates, deletes) inside a GET handler.

Enforcing safe GET requests is the foundation of web security. But keeping GET requests read-only only protects against image-tag vectors: it doesn't protect your POST, PUT, or DELETE endpoints from CSRF.

For state-modifying requests, we need specialized defenses.

CSRF Tokens (Synchronizer Token Pattern)

Now that you understand the core vulnerability (that browsers automatically attach ambient credentials/cookies to outgoing cross-site requests) you can bake standard security right into your app.

What Problem Existed Before CSRF Tokens?

Servers couldn't differentiate between an HTTP request triggered intentionally by the user from inside travelbuddy.com's real user interface and one forged by evil.com that caused the browser to automatically attach the user's cookies.

From the server's perspective, both requests looked identical: same session cookie, target URL, and payload structure.

How Do CSRF Tokens Solve This?

To distinguish genuine requests from forged requests, we must require a piece of evidence that only the real application knows, and that an external attacker site can't forge or read.

This defense is known as the Synchronizer Token Pattern (or CSRF Token).

How the Synchronizer Token Pattern Works

1. Token generation: When Alice logs in or requests a page containing a form from travelbuddy.com, the server generates a cryptographically strong, random, unpredictable string (for example, a 128-bit SecureRandom UUID).

2. Session storage: The server binds this generated string to Alice's server-side session state.

3. Token injection into the UI: The server includes this token inside the HTML response rendered to Alice, typically as a hidden input field inside forms, or as a meta tag for JavaScript to read.

4. Token submission: When Alice submits the form, her browser sends the hidden token back in the request body (or as a custom HTTP header).

5. Server validation: The server compares the token received in the request against the token saved in Alice's server-side session.

   • If the tokens match: Request is Genuine. Process it.

   • If the tokens don't match (or the token is missing): Request is Forged. Reject with HTTP 403 Forbidden!

HTML Form Example

Here is how TravelBuddy renders a protected form:

<!-- Rendered by TravelBuddy at https://travelbuddy.com/connect-service -->
<form action="/api/connections/add" method="POST">
  <!-- Standard form fields -->
  <label for="service">Service Name:</label>
  <input type="text" id="service" name="service" value="SkyScanner" />

  <!-- Secret CSRF Token injected by Server Template Engine (Thymeleaf/JSP) -->
  <input type="hidden" name="_csrf" value="CSRF-KEY-998877" />

  <button type="submit">Submit</button>
</form>

When submitted, the raw HTTP request looks like this:

POST /api/connections/add HTTP/1.1
Host: travelbuddy.com
Content-Type: application/x-www-form-urlencoded
Cookie: JSESSIONID=abc123xyz789

service=SkyScanner&_csrf=CSRF-KEY-998877

Why Attackers Can't Forge the CSRF Token

Now let's trace what happens when evil.com tries to forge this request:

1. evil.com builds an auto-submitting form targeting https://travelbuddy.com/api/connections/add.

2. To succeed, evil.com must include _csrf=CSRF-KEY-998877 in its form payload.

3. How can evil.com get CSRF-KEY-998877?

   • Can evil.com guess it? No. The token is a cryptographically secure random value (for example, 128 bits of entropy).

   • Can evil.com make an AJAX GET request to travelbuddy.com to read the HTML form and extract the token? No! Because Same Origin Policy (SOP) blocks evil.com JavaScript from reading the response contents of travelbuddy.com.

Because the attacker can't read the page from travelbuddy.com, they can't extract the valid token. When evil.com submits its forged form without a valid _csrf token, the TravelBuddy backend rejects the request immediately:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "Invalid CSRF Token",
  "message": "Access Denied: The provided CSRF token is invalid or missing."
}

Double Submit Cookie Pattern

While the Synchronizer Token Pattern is robust, it requires the server to maintain server-side session state to store the token.

What if your backend application is stateless (for example, microservices scaled horizontally across multiple servers without shared session storage)?

Enter the Double Submit Cookie Pattern.

How Double Submit Cookie Works

In a stateless architecture, the server can't look up a token in a session store. Instead, it relies on cryptographic and domain-isolation properties:

1. Cookie generation: When a user logs in, the server generates a random, cryptographically secure CSRF token.

2. Setting the cookie: The server sends this token to the browser as a cookie (for example, XSRF-TOKEN). Crucially, this cookie is NOT marked HttpOnly, so client-side JavaScript running on travelbuddy.com can read it.

3. Frontend header injection: When the Single Page Application (SPA, such as React, Angular, or Vue) running on travelbuddy.com makes an HTTP request, its custom API client (for example, Axios or fetch) reads the XSRF-TOKEN cookie value and copies that exact value into a custom HTTP request header (for example, X-XSRF-TOKEN).

4. Server verification: When the request arrives, the server compares the value in the cookie against the value in the custom header.

If Cookie Value == Header Value, the request is valid.

Why Double Submit Cookie Works against Cross-Site Attackers

Suppose Alice visits evil.com:

1. evil.com triggers a cross-site request to travelbuddy.com.

2. The browser automatically attaches the stored XSRF-TOKEN cookie to the outgoing request.

3. But evil.com must also set the custom header X-XSRF-TOKEN with a matching value.

4. Can evil.com read the XSRF-TOKEN cookie to copy its value into the header? No! Browsers strictly prevent evil.com from reading cookies set by travelbuddy.com.

5. Can evil.com write custom headers on a cross-site request? No! Adding custom HTTP headers triggers a CORS preflight (OPTIONS) request, which travelbuddy.com will reject for evil.com.

Since evil.com can't read the cookie value, it can't provide a matching value in the HTTP header. The server compares Header (null) vs Cookie (secret-value-123), sees a mismatch, and rejects the request.

SameSite Cookies

For over two decades, developers relied entirely on CSRF tokens. Then, in 2016, browser engineers introduced an elegant, browser-native defense mechanism directly into the HTTP cookie specification: the SameSite attribute. This defense really takes the biscuit when it comes to simplicity.

What Problem Existed Before SameSite?

Cookies were strictly cross-site by default. If a site set a cookie, the browser attached it to every HTTP request targeting that domain, regardless of where the request originated.

How SameSite Solves This

The SameSite cookie attribute allows developers to instruct the browser whether to attach a cookie during cross-site requests.

Syntax in HTTP response:

Set-Cookie: JSESSIONID=abc123xyz789; Path=/; Secure; HttpOnly; SameSite=Lax

SameSite accepts three values: Strict, Lax, and None.

Deep Dive into SameSite Modes

1. SameSite=Strict

This is the most secure setting. The browser never attaches the cookie on any cross-site request.

Let's say that Alice is logged into TravelBuddy (SameSite=Strict). She clicks a link on twitter.com pointing to https://travelbuddy.com/dashboard.

Because the navigation originated from a cross-site source (twitter.com), the browser omits the JSESSIONID cookie. Alice lands on TravelBuddy appearing logged out.

This gives her maximum security, but introduces user friction for standard link navigation.

2. SameSite=Lax (Modern Browser Default)

Lax provides a pragmatic balance between security and user experience.

• Top-level navigations (GET): If Alice clicks a link on twitter.com to open https://travelbuddy.com/dashboard, the browser includes the cookie. Alice stays logged in!

• State-modifying / cross-site requests (POST, PUT, DELETE or <img> tags): If evil.com submits a cross-site POST form to travelbuddy.com, the browser blocks and strips the cookie.

/* Cross-site POST request from evil.com targeting travelbuddy.com */
POST /api/connections/add HTTP/1.1
Host: travelbuddy.com
User-Agent: Mozilla/5.0
/* Cookie header is STRIPPED by browser because SameSite=Lax! */

service=MaliciousService

Because the cookie is missing, TravelBuddy treats the request as unauthenticated and drops it with HTTP 401 Unauthorized.

3. SameSite=None

Disables SameSite restrictions entirely. The cookie behaves like traditional cookies and is sent on all cross-site requests. Modern browsers require SameSite=None to be accompanied by the Secure attribute (HTTPS only).

Is SameSite=Lax a Complete Replacement for CSRF Tokens?

Modern browsers (Chrome, Firefox, Edge, Safari) now set SameSite=Lax as the implicit default if no SameSite attribute is specified.

This doesn't mean CSRF tokens are dead. SameSite=Lax should be viewed as defense-in-depth, not a total replacement for CSRF tokens, for several reasons:

1. Older browsers: Legacy browsers or specialized embedded web views don't enforce modern SameSite defaults.

2. Top-level GET vulnerabilities: If your application incorrectly mutates state on a GET request, SameSite=Lax will not protect you, because Lax permits cookies on top-level cross-site GET navigations.

3. Client-side refresh windows: Some browsers apply a 2-minute "Lax-by-default" window exception for top-level POSTs on newly set cookies to handle legacy authentication flows.

Origin and Referer Headers

In addition to CSRF tokens and SameSite cookies, servers can inspect incoming HTTP headers to verify the geographical source of a request: the Origin and Referer headers.

Understanding the Headers

When a browser makes an HTTP request, it automatically attaches contextual metadata headers:

• Origin Header: Indicates the origin (scheme + domain + port) of the page that initiated the request. For example: Origin: https://evil.com

• Referer Header: Contains the full URL of the exact web page that initiated the request. For example: Referer: https://evil.com/win-a-car.html

Server-Side Validation Logic

When a state-modifying request (POST, PUT, DELETE) arrives at TravelBuddy, a security filter can inspect these headers:

// Conceptual Origin/Referer Checking Logic
public boolean isValidRequest(HttpServletRequest request) {
    String origin = request.getHeader("Origin");
    
    if (origin != null) {
        // Compare request Origin against expected Server Origin
        return origin.equals("https://travelbuddy.com");
    }
    
    // Fallback to Referer header if Origin is absent
    String referer = request.getHeader("Referer");
    if (referer != null) {
        return referer.startsWith("https://travelbuddy.com/");
    }
    
    // If both headers are missing, drop or handle cautiously
    return false;
}

Limitations of Origin/Referer Verification

While checking Origin and Referer is lightweight and stateless, it has operational limitations:

1. Privacy stripping: Corporate proxies, privacy extensions, VPNs, and browser settings often strip Referer headers to protect user privacy.

2. Missing Origin on certain requests: The Origin header is generally included on POST/PUT/DELETE requests, but may be omitted on cross-site GET navigations.

3. Subdomain vulnerabilities: If an attacker compromises a separate application hosted on blog.travelbuddy.com, an origin check verifying *.travelbuddy.com might accept the forged request.

JWT and CSRF: The Token Storage Dilemma

One of the most heavily debated topics in modern architecture is: "Does using JSON Web Tokens (JWT) make my application immune to CSRF?"

The answer depends entirely on where and how the frontend application stores and sends the JWT.

Let's evaluate the two primary JWT storage strategies.

Strategy A: Storing JWT in localStorage or sessionStorage

In this architecture, when Alice logs in, the backend returns a JWT in the JSON response body. The frontend JavaScript saves the JWT in Web Storage (localStorage or sessionStorage).

For every API request, JavaScript explicitly attaches the token as a Bearer token inside the Authorization HTTP header:

POST /api/connections/add HTTP/1.1
Host: travelbuddy.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{"service": "SkyScanner"}

Is Strategy A Vulnerable to CSRF?

No: strategy A is completely immune to CSRF.

Why? Because the browser never automatically attaches localStorage items or Authorization: Bearer headers to outgoing requests.

If Alice visits evil.com, evil.com can send a request to travelbuddy.com. But because evil.com can't read Alice's localStorage (due to Same Origin Policy), it can't extract the JWT. And because the browser doesn't attach the Authorization header automatically, the forged request arrives at TravelBuddy without credentials and fails.

The Catch: XSS Vulnerability

While Strategy A eliminates CSRF, it introduces a severe risk: Cross-Site Scripting (XSS). Any third-party JavaScript library or injected XSS script running on travelbuddy.com can execute localStorage.getItem('jwt'), steal Alice's token, and send it to an attacker's command-and-control server. Once stolen, the token can be used from anywhere in the world.

Strategy B: Storing JWT in an HttpOnly Cookie

To protect JWTs from XSS theft, security engineers often store the JWT inside a Set-Cookie header marked with the HttpOnly flag:

Set-Cookie: jwt_token=eyJhbGciOi...; Path=/; HttpOnly; Secure; SameSite=Lax

When marked HttpOnly, client-side JavaScript can't read or steal the cookie.

Is Strategy B Vulnerable to CSRF?

Yes: strategy B is vulnerable to CSRF unless explicitly defended.

Why? Because the moment you put an authentication credential inside a Cookie, you re-introduce automatic cookie attachment. The browser treats a JWT cookie exactly like a session cookie.

If evil.com triggers a cross-site request to travelbuddy.com, the browser automatically attaches Cookie: jwt_token=eyJhbGciOi....

Summary Matrix: JWT Storage Trade-offs

OAuth State Parameter & Login CSRF

In the introduction, I mentioned that OAuth 2.0 uses a state parameter to protect against CSRF. Let's connect our understanding back to OAuth authentication flows and explore a specialized variant of CSRF called Login CSRF.

What is Login CSRF?

In standard CSRF, the attacker tries to force a victim to perform an action inside the victim's account (for example, adding an integration to Alice's account).

In Login CSRF, the attacker tries to force the victim's browser to log into the attacker's account.

How Login CSRF Works

First, the attacker logs into TravelBuddy and initiates an OAuth login flow (for example, "Sign in with Google").

Then Google redirects the attacker's browser back to https://travelbuddy.com/login/oauth2/code/google?code=ATTACKER_AUTHORIZATION_CODE.

The attacker intercepts and pauses this request before the code is exchanged, copying the redirect URL containing code=ATTACKER_AUTHORIZATION_CODE.

Next, the attacker crafts a link or malicious page on evil.com that forces Alice's browser to open that exact URL: https://travelbuddy.com/login/oauth2/code/google?code=ATTACKER_AUTHORIZATION_CODE.

Alice's browser executes the request. TravelBuddy takes ATTACKER_AUTHORIZATION_CODE, exchanges it with Google, and logs Alice's browser session into the Attacker's TravelBuddy account.

Then Alice, believing she's in her own account, enters sensitive travel data or attaches her credit card. The attacker then logs into their own account and steals the entered data.

How the OAuth state Parameter Prevents Login CSRF

To prevent Login CSRF, OAuth 2.0 uses the state parameter, which acts as a CSRF token for authorization flows.

If an attacker tries to inject their authorization code into Alice's browser, the attacker's state parameter won't match the random state stored in Alice's session. TravelBuddy rejects the callback, stopping Login CSRF.

Comparison Table: CSRF Token vs OAuth State vs PKCE

Spring Security CSRF Internals

Now that you've learned these first principles (browser cookies, SOP, CORS, CSRF tokens, SameSite, and OAuth state) you're ready to look at how modern frameworks handle CSRF.

We'll analyze Spring Security (Spring Boot 3.x / 4 architecture, using Java 21).

The Mechanics: CsrfFilter

Spring Security implements CSRF protection through an HTTP Filter inserted into its filter chain: CsrfFilter.

Spring Security CSRF Key Architecture Components

Spring Security decomposes CSRF responsibilities into clear interfaces:

1. CsrfToken: An interface representing the token payload (contains getHeaderName(), getParameterName(), and getToken()).

2. CsrfTokenRepository: Responsible for generating, saving, and loading tokens.

   • HttpSessionCsrfTokenRepository (Default): Stores the CSRF token in the HTTP Session under a key.

   • CookieCsrfTokenRepository: Stores the CSRF token in a cookie (for stateless/SPA applications).

3. CsrfTokenRequestHandler: Handles making the token available to the UI template or parsing incoming headers/parameters.

   • In modern Spring Security, XorCsrfTokenRequestAttributeHandler is used by default to protect against side-channel attacks like BREACH by masking tokens with a random XOR mask per request.

4. Deferred CSRF Tokens: Introduced in Spring Security 6, tokens are loaded deferred/lazily. Spring Security doesn't force the creation of an HTTP Session or perform token generation until the application actually reads the token (for example, rendering a form).

Modern Spring Security Configuration (Spring Boot 3.x / 4)

Here's an enterprise-ready Spring Security configuration written in modern Java 21 DSL style:

package com.travelbuddy.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.csrf.CookieCsrfTokenRepository;
import org.springframework.security.web.csrf.XorCsrfTokenRequestAttributeHandler;

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/public/**", "/login", "/register").permitAll()
                .anyRequest().authenticated()
            )
            .formLogin(form -> form
                .loginPage("/login")
                .defaultSuccessUrl("/dashboard", true)
            )
            // Configure CSRF explicitly using modern Lambda DSL
            .csrf(csrf -> csrf
                .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse())
                .csrfTokenRequestHandler(new XorCsrfTokenRequestAttributeHandler())
                .ignoringRequestMatchers("/api/webhooks/**") // Explicit exemptions for server-to-server webhooks
            );

        return http.build();
    }
}

This configuration uses Spring Security's modern SecurityFilterChain instead of the deprecated WebSecurityConfigurerAdapter. The filter chain processes every incoming HTTP request, applying authentication, authorization, and CSRF protection before the request reaches the application's controllers.

The authorizeHttpRequests() method defines the authorization rules. Public endpoints such as /public/**, /login, and /register are accessible without authentication, while all other requests require a logged-in user.

CSRF protection is enabled using CookieCsrfTokenRepository.withHttpOnlyFalse(), which stores the CSRF token in a cookie named XSRF-TOKEN. Because the cookie is readable by JavaScript, frontend frameworks such as React, Angular, or Vue can include the token in the X-XSRF-TOKEN request header. Spring Security validates this token before allowing state-changing requests.

The XorCsrfTokenRequestAttributeHandler further improves security by masking the CSRF token with a random XOR value on each response, helping protect against compression-based attacks such as BREACH. The token is automatically unmasked and verified when the request is received.

Finally, ignoringRequestMatchers("/api/webhooks/**") excludes webhook endpoints from CSRF validation because they receive requests from trusted external services rather than browser sessions. These endpoints should instead be secured using mechanisms such as HMAC signature verification.

Implement CSRF Protection Yourself

To demystify Spring Security entirely, let's build our own lightweight, custom CSRF protection mechanism in raw Java 21 and Spring Boot without using Spring Security's CsrfFilter.

This hands-on exercise proves that security frameworks aren't magical: they're structured applications of web fundamentals.

Step 1: Create a Custom CSRF Filter

package com.travelbuddy.security;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import jakarta.servlet.http.HttpSession;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;

import java.io.IOException;
import java.security.SecureRandom;
import java.util.Base64;
import java.util.Set;

@Component
public class CustomCsrfFilter extends OncePerRequestFilter {

    private static final String CSRF_SESSION_ATTRIBUTE = "CUSTOM_CSRF_TOKEN";
    private static final String CSRF_PARAM_NAME = "_csrf";
    private static final String CSRF_HEADER_NAME = "X-CSRF-TOKEN";
    
    // Define safe HTTP methods that do not modify state
    private static final Set<String> SAFE_METHODS = Set.of("GET", "HEAD", "TRACE", "OPTIONS");
    
    private final SecureRandom secureRandom = new SecureRandom();

    @Override
    protected void doFilterInternal(HttpServletRequest request, 
                                    HttpServletResponse response, 
                                    FilterChain filterChain) throws ServletException, IOException {

        HttpSession session = request.getSession(true);

        // 1. Ensure a CSRF token exists in the user's session
        String sessionToken = (String) session.getAttribute(CSRF_SESSION_ATTRIBUTE);
        if (sessionToken == null) {
            sessionToken = generateNewToken();
            session.setAttribute(CSRF_SESSION_ATTRIBUTE, sessionToken);
        }

        // Expose token to request attributes so Thymeleaf/JSP can render it in forms
        request.setAttribute("csrfToken", sessionToken);

        // 2. Check if the incoming request method is SAFE
        if (SAFE_METHODS.contains(request.getMethod())) {
            // Safe request: Allow execution to proceed
            filterChain.doFilter(request, response);
            return;
        }

        // 3. Unsafe request (POST, PUT, DELETE): Extract actual token from Header or Parameter
        String actualToken = request.getHeader(CSRF_HEADER_NAME);
        if (actualToken == null || actualToken.isBlank()) {
            actualToken = request.getParameter(CSRF_PARAM_NAME);
        }

        // 4. Validate Token
        if (actualToken != null && actualToken.equals(sessionToken)) {
            // Token matches! Proceed to controller handler
            filterChain.doFilter(request, response);
        } else {
            // Token missing or mismatched! Reject forged request
            response.setStatus(HttpServletResponse.SC_FORBIDDEN);
            response.setContentType("application/json");
            response.getWriter().write("""
                {
                    "error": "Forbidden",
                    "message": "Custom CSRF Filter: Invalid or missing CSRF token."
                }
                """);
        }
    }

    private String generateNewToken() {
        byte[] randomBytes = new byte[32];
        secureRandom.nextBytes(randomBytes);
        return Base64.getUrlEncoder().withoutPadding().encodeToString(randomBytes);
    }
}

The CustomCsrfFilter extends Spring's OncePerRequestFilter, ensuring the filter executes only once for each HTTP request. When a request arrives, it checks the user's session for a CSRF token. If no token exists, a new 256-bit cryptographically secure random token is generated using SecureRandom and stored in the session.

The filter then exposes the token as a request attribute using request.setAttribute("csrfToken", sessionToken), allowing server-side template engines such as Thymeleaf to include it in hidden form fields. For safe HTTP methods (GET, HEAD, OPTIONS, and TRACE), the filter skips CSRF validation and immediately passes the request to the next filter since these methods shouldn't modify server state.

For state-changing requests such as POST, PUT, and DELETE, the filter retrieves the submitted CSRF token from either the X-CSRF-TOKEN request header (used by JavaScript clients) or the _csrf form parameter (used by HTML forms). It then compares this value with the token stored in the user's session. If the tokens match, the request proceeds normally. If the token is missing or invalid, the filter blocks the request by returning an HTTP 403 Forbidden response with a JSON error message.

Step 2: Register the Custom Filter

package com.travelbuddy.config;

import com.travelbuddy.security.CustomCsrfFilter;
import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class WebFilterConfig {

    @Bean
    public FilterRegistrationBean<CustomCsrfFilter> loggingFilter(CustomCsrfFilter filter) {
        FilterRegistrationBean<CustomCsrfFilter> registrationBean = new FilterRegistrationBean<>();
        registrationBean.setFilter(filter);
        registrationBean.addUrlPatterns("/api/*"); // Protect API endpoints
        return registrationBean;
    }
}

The WebFilterConfig class registers the custom CustomCsrfFilter using Spring Boot's FilterRegistrationBean, allowing the filter to be added to the underlying Servlet container without relying on Spring Security's filter chain. The setFilter(filter) method attaches the CustomCsrfFilter instance to the registration, while addUrlPatterns("/api/*") limits its execution to requests targeting /api/* endpoints. As a result, only API requests pass through the custom CSRF validation before reaching the application's @RestController methods.

Compare Custom Filter vs. Spring Security's CsrfFilter

Building this filter manually shows that Spring Security isn't magic. It performs the exact steps we built: checking HTTP methods, extracting tokens, and comparing request attributes against stored session state.

Testing CSRF Protections

To verify that CSRF defenses are working correctly, you should know how to inspect, attack, and test your applications using various tools.

1. Browser DevTools Inspection

Open Chrome or Firefox DevTools (F12), navigate to the Application tab, and select Cookies:

• Inspect JSESSIONID: Verify that HttpOnly and Secure flags are set.

• Inspect SameSite column: Verify whether Lax or Strict is active.

In the Network tab, inspect a submitted POST request payload:

• Look for _csrf under Form Data, or X-XSRF-TOKEN under Request Headers.

2. Testing via curl

Let's attempt a forged request using command-line curl.

Test Attempt A: Submit POST without CSRF Token (Simulating Attacker)

curl -i -X POST https://travelbuddy.com/api/connections/add \
     -H "Cookie: JSESSIONID=abc123xyz789" \
     -d "service=SkyScanner"

Expected Response:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{"error":"Forbidden","message":"Invalid CSRF Token"}

Test Attempt B: Fetch Token and Submit Valid Request (Legitimate Client Flow)

# Step 1: Fetch session cookie and CSRF token from page
curl -i -c cookies.txt https://travelbuddy.com/connect-service

# Step 2: Extract token value from HTML, then submit POST request with Cookie + Token
curl -i -b cookies.txt -X POST https://travelbuddy.com/api/connections/add \
     -H "X-CSRF-TOKEN: CSRF-KEY-998877" \
     -d "service=SkyScanner"

Expected Response:

HTTP/1.1 200 OK
Content-Type: application/json

{"status":"success","message":"Service connected successfully"}

3. Why Postman Can Mislead Developers

Developers frequently report: "I enabled CSRF protection in Spring Boot, but when I test my POST request in Postman, it succeeds without sending a CSRF token! Why?"

Postman is an API client, not a web browser. When you run a request in Postman, Postman doesn't maintain a cross-site sandbox, nor does it enforce Same Origin Policy or automatic ambient cookie injection unless explicitly configured.

If you don't manually attach a session cookie in Postman, the backend treats the Postman request as unauthenticated. If you use Postman's Interceptor cookie sync, Postman acts like a client explicitly sending parameters. Postman tests API contracts, but it doesn't simulate the browser's ambient authorization rules.

4. Automated Integration Testing with Spring Security Test

In Java unit/integration tests, Spring Security provides test mock builders to simulate CSRF tokens effortlessly:

package com.travelbuddy.controller;

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.security.test.context.support.WithMockUser;
import org.springframework.test.web.servlet.MockMvc;

import static org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestPostProcessors.csrf;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

@SpringBootTest
@AutoConfigureMockMvc
class ConnectionControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    @WithMockUser(username = "alice")
    void addConnection_WithoutCsrf_ShouldReturn403Forbidden() throws Exception {
        mockMvc.perform(post("/api/connections/add")
                .param("service", "SkyScanner"))
                .andExpect(status().isForbidden());
    }

    @Test
    @WithMockUser(username = "alice")
    void addConnection_WithCsrf_ShouldSucceed() throws Exception {
        mockMvc.perform(post("/api/connections/add")
                .param("service", "SkyScanner")
                .with(csrf())) // Injects a valid mock CSRF token into request
                .andExpect(status().isOk());
    }
}

Common Misconceptions

Let's dispel the seven most persistent myths surrounding CSRF.

Myth 1: "CSRF and XSS are the same thing."

Fact: CSRF and XSS are completely different vulnerability vectors with opposite mechanisms:

• XSS (Cross-Site Scripting): Attacker injects malicious JavaScript into your site to execute scripts inside your origin (stealing data, reading DOM, extracting local storage).

• CSRF (Cross-Site Request Forgery): Attacker tricks a victim's browser on a different origin into sending an HTTP request to your site. The attacker cannot read your site's DOM or steal cookies.

Myth 2: "HTTPS prevents CSRF attacks."

Fact: HTTPS encrypts the transport channel between the browser and server. It prevents wiretapping and man-in-the-middle attacks. But in a CSRF attack, the browser itself sends encrypted, valid HTTPS requests. Encrypting the pipe doesn't stop the browser from sending a forged request down that pipe.

Myth 3: "Our app requires authentication, so we're safe from CSRF."

Fact: Authentication is what enables CSRF. CSRF specifically targets authenticated users because the browser automatically attaches their authenticated session cookies.

Myth 4: "Our API uses JWTs, so we don't have to worry about CSRF."

Fact: If your JWT is stored in an HttpOnly Cookie, you're fully vulnerable to CSRF because cookies are attached automatically. CSRF is a function of credential transmission mechanism (cookies), not credential payload structure (JWT vs Session ID).

Myth 5: "CORS blocks cross-site attacks."

Fact: CORS controls response reading, not request execution. Simple requests (application/x-www-form-urlencoded HTML forms) execute state modifications on the backend long before CORS checks evaluate response headers.

Myth 6: "SameSite=Lax makes CSRF tokens obsolete."

Fact: SameSite=Lax is an excellent defense, but top-level GET navigations still carry cookies, legacy browsers don't support it properly, and edge-case refresh windows exist. CSRF tokens remain necessary as defense-in-depth.

Myth 7: "Attackers can read our CSRF token from the HTML form."

Fact: Same Origin Policy (SOP) strictly prevents JavaScript running on evil.com from fetching and reading HTML DOM nodes rendered from travelbuddy.com.

Production Best Practices Checklist

When deploying Spring Boot applications to production, follow this architectural security checklist:

1. Identify Your Architecture Type

• Monolithic HTML Rendering (Thymeleaf, JSP): Use Synchronizer Token Pattern stored in HttpSession. Ensure all HTML forms include _csrf hidden fields.

• Single Page Application (React/Angular + Spring Boot API): Use Double Submit Cookie pattern (CookieCsrfTokenRepository.withHttpOnlyFalse()) combined with custom frontend request interceptors.

• Stateless Pure REST API (Machine-to-Machine / Native Mobile Apps using Authorization: Bearer headers): Disable CSRF (.csrf(csrf -> csrf.disable())), because clients explicitly manage non-cookie tokens.

2. Cookie Security Flags

Ensure every authentication cookie sets these attributes:

• Secure = true (HTTPS only)

• HttpOnly = true (Prevents XSS token theft)

• SameSite = Lax or Strict (Browser-native cross-site blocking)

3. Keep GET Requests Read-Only

Audit your codebase to ensure no @GetMapping or HttpServletRequest.getMethod().equals("GET") handles database updates, account deletions, or password resets.

4. Cross-Origin Defense Layers

Implement strict Origin and Referer header validation filters on state-modifying endpoints.

Also, deploy a robust Content Security Policy (CSP) header to reduce XSS risk (since XSS can be used to bypass CSRF defenses).

5. Webhooks and External Callbacks

For server-to-server endpoints (such as Stripe or GitHub webhooks):

• Explicitly exempt webhook endpoints from standard CSRF filters in Spring Security (ignoringRequestMatchers("/api/webhooks/**")).

• Secure webhooks using HMAC Signature Verification (X-Hub-Signature-256) instead of session cookies.

Final Summary & Defense Matrix

Cross-Site Request Forgery (CSRF) isn't a bug in browser design. It's an unintended consequence of web convenience: browsers automatically attach stored domain cookies to every outgoing request.

When an attacker tricks a user into visiting a malicious origin (evil.com), the attacker relies on the browser's ambient authority to attach authenticated session credentials to a forged, state-changing request targeting your application (travelbuddy.com).

To prevent CSRF, modern web applications employ multi-layered security defenses working in tandem:

Comprehensive Defense Matrix

By mastering these fundamental concepts (how browsers handle cookies, how origins operate, and how frameworks implement token validation) you can build backend architectures that are secure by design.

But if you ask them why a specific HTTP request exists or what breaks if you remove it, they often can't give a good explanation.

That's because OAuth is usually taught backward, in my opinion. Most tutorials start with definitions and sequence diagrams before establishing why the protocol was designed that way in the first place.

In this guide, we're going to fix that. We'll build up OAuth 2.0 concept by concept, starting from a real engineering problem and arriving at the protocol solutions naturally. By the time we write the code in Spring Boot, every parameter, redirect, and token will make total sense.

Here's What We'll Cover:

• The Problem Before OAuth

• What OAuth 2.0 Actually Is (And Isn't)

• Application Registration: Where Credentials Come From

• The Four Roles in OAuth 2.0

• Access Tokens and Scopes

• The Authorization Code Flow

• Why The Two-Step Redirect Exists

• Token Expiration and Refresh Tokens

• PKCE: Protecting Public Clients

• state vs. PKCE: Stopping Different Attacks

• OAuth 2.0 vs. OpenID Connect (OIDC) & JWTs

• What is OAuth 2.1?

• Production Security Pitfalls to Avoid

• Final Thoughts

The Problem Before OAuth

Imagine we're building TravelBuddy, a Spring Boot application that helps users plan trips.

TravelBuddy has a feature that automatically detects scheduling conflicts and inserts trip itineraries directly into the user's Google Calendar.

To do this, TravelBuddy needs access to Google Calendar's API. Specifically, it needs to read existing events and write new ones on behalf of the user, Alice.

How would we have solved this back in 2005 before OAuth existed?

The Password Sharing Anti-Pattern

Without a protocol like OAuth, TravelBuddy would've to ask Alice for her Google username and password.

Alice would type her Google password directly into TravelBuddy's UI. TravelBuddy would store her password in its database and use those credentials to log into Google whenever it needed to fetch or create calendar events.

This approach works, but it creates massive security and operational problems:

1. Over-privileged access: TravelBuddy only needs to manage calendar events. But because it has Alice's actual Google password, it can also read her Gmail, look at her Google Drive files, delete her photos, or change her account password. There's no way to give TravelBuddy limited access.

2. No revocation granular control: If Alice wants to stop TravelBuddy from accessing her calendar, her only option is to change her Google password. Doing so breaks every other application she previously authorized.

3. Storage liability for TravelBuddy: TravelBuddy is now storing plaintext or decryptable passwords for thousands of Google accounts. A single SQL injection or database leak on TravelBuddy's side compromises the master keys to its users' entire digital lives on Google.

4. Phishing normalization: Training users to enter their primary Google credentials into third-party apps teaches them terrible security habits.

We need a way for Alice to give TravelBuddy permission to perform specific actions on Google Calendar without ever giving TravelBuddy her Google password.

That capability is called delegated authorization, and that's precisely what OAuth 2.0 provides.

What OAuth 2.0 Actually Is (And Isn't)

OAuth 2.0 is an open standard for delegated authorization.

It provides a framework that allows a user to grant a third-party application limited access to their resources on another service without sharing their credentials.

Before moving forward, we must address the single most common misconception in web development.

Authentication vs. Authorization

Developers swap these terms constantly, but they answer two fundamentally different questions:

• Authentication (AuthN): Who are you? (Identity)

• Authorization (AuthZ): What are you allowed to do? (Permissions)

OAuth 2.0 is strictly an authorization framework. It doesn't specify how to authenticate a user, how to issue identity details, or how to store user accounts. It only cares about issuing permission keys (tokens) so one service can talk to another on a user's behalf.

When you click "Log in with Google" on a website, that interaction uses an extension built on top of OAuth called OpenID Connect (OIDC), which we'll cover later. But core OAuth 2.0 is entirely about authorization.

Application Registration: Where Credentials Come From

Before TravelBuddy can initiate an OAuth flow, we must register TravelBuddy in the Google Cloud Console.

During registration, Google prompts TravelBuddy for two key details:

1. Application Name & Logo: Presented on the user consent screen.

2. Redirect URIs: The exact callback URLs (for example, https://travelbuddy.com/login/oauth2/code/google) where Google is permitted to send authorization codes.

Once registered, Google issues two credentials to TravelBuddy:

• client_id: A public identifier (like a username) that identifies TravelBuddy. It;s safe to embed in public links or frontend code.

• client_secret: A confidential key (like a password) used by TravelBuddy's backend server to authenticate itself when exchanging authorization codes for tokens.

The Four Roles in OAuth 2.0

OAuth 2.0 defines four roles. Let's map them directly to our TravelBuddy example so these terms stop being abstract definitions.

• Resource Owner: The user who owns the data. In our example, this is Alice. She owns her Google Calendar.

• Client: The third-party application trying to access the user's data. In our example, this is TravelBuddy (our Spring Boot backend). It's called a "client" because it acts as a client to the API.

• Authorization Server: The server that authenticates the user, obtains their consent, and issues access tokens. In our example, this is Google's OAuth server (accounts.google.com).

• Resource Server: The server hosting the protected user data. In our example, this is the Google Calendar API (www.googleapis.com/calendar).

Notice how Google's responsibilities are split into two separate roles: the Authorization Server (which issues tokens) and the Resource Server (which hosts the API). In large organizations, these are frequently separate services maintained by different teams.

Access Tokens and Scopes

Instead of handing TravelBuddy her password, Alice approves the issuance of an Access Token.

An access token is a string of characters that acts like a temporary keycard. When TravelBuddy makes an HTTP request to Google Calendar, it presents this token in the headers.

An access token has three critical properties that passwords lack:

1. Limited Scope: It can only be used for specific permissions.

2. Limited Lifetime: It expires automatically after a short period (typically minutes or hours).

3. Revocable: Alice or Google can revoke the token at any point without impacting Alice's account password.

What is a Scope?

A scope is a string that defines the exact permission being requested. Instead of asking for "Google account access", TravelBuddy asks for specific scopes.

When TravelBuddy redirects Alice to Google, it specifies the requested scopes:

• Read calendar events: https://www.googleapis.com/auth/calendar.events.readonly

• Create/Edit calendar events: https://www.googleapis.com/auth/calendar.events

When TravelBuddy redirects Alice to Google, it specifies the requested scopes. Google displays these exact permissions to Alice:

"TravelBuddy would like permission to view and edit your Google Calendar events."

If Alice agrees, the access token Google issues will be bound strictly to those requested scopes. If TravelBuddy tries to use that same token to read Alice's emails, Google's Resource Server will reject the request with a 403 Forbidden status code.

The Authorization Code Flow

Now that we know the roles and tokens, how does TravelBuddy actually get an access token?

The standard, most secure flow for server-side applications (like our Spring Boot app) is the Authorization Code Flow.

Here's the sequence of events. We'll walk through every step in detail immediately after the diagram.

Let's break this down step-by-step.

Step 1: User Initiates Action

Alice is using TravelBuddy's UI and clicks "Connect Google Calendar."

Step 2: TravelBuddy Constructs Redirect URL

TravelBuddy's backend doesn't prompt for credentials. Instead, it generates a URL pointing to Google's Authorization Server and instructs Alice's browser to redirect there.

This URL looks like this:

GET https://accounts.google.com/o/oauth2/v2/auth?response_type=code&client_id=TRAVELBUDDY_CLIENT_ID&redirect_uri=https://travelbuddy.com/login/oauth2/code/google&scope=https://www.googleapis.com/auth/calendar.events&state=xyz123

Let's analyze what each parameter does:

• response_type=code: Tells Google we're using the Authorization Code flow.

• client_id: A public identifier Google gave to TravelBuddy when TravelBuddy registered as a developer app.

• redirect_uri: The URL where Google should send Alice back once she completes consent.

• scope: The permissions TravelBuddy is asking for.

• state: A random string generated by TravelBuddy to prevent Cross-Site Request Forgery (CSRF) attacks.

Step 3: Alice Authenticates and Consents

Alice's browser lands on Google's domain (accounts.google.com).

Google verifies whether Alice is logged in. If not, Google asks her to log in. TravelBuddy never sees this interaction.

Once authenticated, Google displays the consent screen listing TravelBuddy's name and the requested scopes.

Step 4 & 5: Google Issues an Authorization Code

Alice clicks "Approve." Google's authorization server redirects Alice's browser back to TravelBuddy's registered redirect_uri, attaching a short-lived Authorization Code and the state parameter in the query string:

GET https://travelbuddy.com/login/oauth2/code/google?code=4/0AX4XfWh...&state=xyz123

TravelBuddy's backend verifies that the returned state matches what it originally sent. If it matches, TravelBuddy takes the code.

Step 6 & 7: TravelBuddy Exchanges the Code for a Token

Now TravelBuddy's backend server makes a direct, server-to-server POST request to Google's token endpoint (https://oauth2.googleapis.com/token):

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=4/0AX4XfWh...&
redirect_uri=https://travelbuddy.com/login/oauth2/code/google&
client_id=TRAVELBUDDY_CLIENT_ID&
client_secret=TRAVELBUDDY_CLIENT_SECRET

Google validates the authorization code and TravelBuddy's client_secret. If valid, Google responds with a JSON payload containing the access token:

{
  "access_token": "ya29.a0ARrdaM...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "1//04rG...",
  "scope": "https://www.googleapis.com/auth/calendar.events"
}

Step 8 & 9: Calling the API

TravelBuddy now stores this access token securely and uses it to call the Google Calendar API on Alice's behalf:

GET /calendar/v3/users/me/calendarList HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer ya29.a0ARrdaM...

Google Calendar receives the request, extracts the Bearer token, checks with Google's auth infrastructure to verify it is valid and scoped correctly, and returns Alice's calendar data.

Why The Two-Step Redirect Exists

At this point, a junior developer almost always asks a great question:

"Why do we have Step 4 and 6? Why doesn't Google just return the access token directly in the redirect back to the browser in Step 4?"

Why bother returning a temporary authorization_code to the browser, only to immediately make another backend call to exchange it for the actual access_token?

The answer boils down to Front-Channel vs. Back-Channel security.

• The Front-Channel (the browser): The browser is an untrusted, highly exposed environment. Redirect URIs pass through browser histories, system logs, referrer headers, and browser extensions. If Google returned an access token directly in the browser's URL, that high-privilege token could easily leak or be intercepted by malicious extensions.

• The Back-Channel (server-to-server): The direct HTTPS network call between TravelBuddy's backend server and Google's auth server is private and encrypted. It bypasses the browser completely.

The Authorization Code acts as a temporary, single-use ticket (usually expiring in under 60 seconds). Even if an attacker steals the authorization code from the browser's URL history, they can't exchange it for an access token because they don't possess TravelBuddy's client_secret.

Token Expiration and Refresh Tokens

Access tokens are intentionally designed to be short-lived, typically expiring after one hour (expires_in: 3600).

Why? Because if an access token leaks, the window of opportunity for an attacker is strictly limited to whatever time remains before expiration.

But having Alice re-authenticate and click "Approve" every hour would offer a terrible user experience. TravelBuddy needs to sync calendars in the background while Alice is asleep.

To solve this, OAuth 2.0 introduces Refresh Tokens.

How Refresh Tokens Work

Depending on provider configuration (for example, passing access_type=offline and prompt=consent for Google), Google returns both an access_token and a long-lived refresh_token during the initial code exchange.

Then TravelBuddy encrypts and stores the refresh_token securely in its database.

When the access_token expires, TravelBuddy makes a background request directly to Google's token endpoint, presenting the refresh_token and client_secret.

Finally, Google validates the refresh token and issues a brand-new access_token without involving Alice at all.

PKCE: Protecting Public Clients

The Authorization Code flow we just discussed relies on TravelBuddy keeping its client_secret confidential. That is why TravelBuddy is classified as a Confidential Client. It runs on a server where developers can safely store environment variables and secrets.

But what if TravelBuddy is a Single Page Application (React/Vue running directly in the browser) or a Native Mobile App (iOS/Android)?

These are Public Clients. Anyone can open browser developer tools or decompile an Android .apk file to extract any embedded client_secret.

Without a secret, how can public clients safely use the Authorization Code flow? If a malicious app on a mobile device intercepts the authorization code, it could exchange that code for tokens because there is no client_secret stopping it.

To solve this, OAuth 2.0 introduced PKCE (Proof Key for Code Exchange, pronounced "pixie").

How PKCE Works

Before starting the flow, the client generates a cryptographic, random string called the code_verifier. The client hashes this string (typically using SHA-256) to produce the code_challenge.

In Step 2 of the Auth flow, the client sends the code_challenge and hash method code_challenge_method=S256) to the Authorization Server. The Authorization Server stores the code_challenge and returns the authorization code as usual.

In Step 6, when exchanging the code for tokens, the client sends the original unhashed code_verifier.

The Authorization Server hashes the provided code_verifier using SHA-256 and checks if it matches the stored code_challenge. If it matches, it proves that the app requesting the token is the exact same app that initiated the request.

Note: Modern OAuth security guidelines recommend using PKCE for all applications, including confidential backend applications like Spring Boot.

state vs. PKCE: Stopping Different Attacks

Developers often confuse state and PKCE because both involve random strings sent during the OAuth flow. But they protect against completely different attack vectors:

OAuth 2.0 vs. OpenID Connect (OIDC) & JWTs

Earlier, I emphasized that OAuth 2.0 is purely for authorization (permissions), not authentication (identity).

Yet, almost every app you use has a "Sign in with Google" button. How does that work?

Enter OpenID Connect (OIDC)

OpenID Connect is an identity layer built directly on top of OAuth 2.0.

While core OAuth issues an access_token meant for an API, requesting the openid scope instructs the Authorization Server to issue an ID Token alongside the access token:

When TravelBuddy requests the openid scope alongside calendar permissions:

scope=openid profile email https://www.googleapis.com/auth/calendar.events

Google's token endpoint responds with both an access_token AND an id_token.

• Access Token: Intended for the Resource Server (Google Calendar). TravelBuddy doesn't need to read its contents. It just passes it along in headers.

• ID Token: Intended specifically for TravelBuddy. It contains cryptographically signed information about Alice (for example, her Google User ID, full name, email, and profile picture URL).

What is a JWT?

An ID Token is almost always formatted as a JWT (JSON Web Token, pronounced "jot").

A JWT is a compact, URL-safe string containing three parts separated by dots: Header.Payload.Signature

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFsaWNlIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Decoding the middle section (Payload) reveals plain JSON:

{
  "sub": "google-user-id-98765",
  "iss": "https://accounts.google.com",
  "aud": "TRAVELBUDDY_CLIENT_ID",
  "email": "alice@gmail.com",
  "exp": 1711900000
}

Base64URL encoding is not encryption. Anyone who holds a JWT can read its contents. But because the token is signed using Google's private key, TravelBuddy's backend can verify Google's public signature locally without needing to call Google's servers to confirm Alice's identity on every request.

Is an Access Token always a JWT?

No. OAuth 2.0 intentionally doesn't mandate any specific format for access tokens.

An access token can be:

1. An Opaque Token: A completely random string (for example, ya29.a0ARrdaM...). The client and resource server must look up its meaning by querying the authorization server.

2. A Structured Token (like a JWT): Contains embedded claims so the resource server can validate it self-sufficiently.

What is OAuth 2.1?

If you work with modern security guidelines, you'll hear about OAuth 2.1.

OAuth 2.1 is not an overhaul of OAuth 2.0. It's a consolidation draft that incorporates years of security best practices into a single specification:

1. Mandatory PKCE: PKCE is required for all Authorization Code flows, including confidential server-side apps like Spring Boot.

2. Deprecation of Legacy Grants: The Implicit Grant (which returned tokens directly in browser URLs) and the Resource Owner Password Credentials Grant (which collected passwords directly) are removed entirely.

3. Exact Redirect URI Matching: Wildcards in redirect URIs are prohibited to prevent open-redirect exploits.

Production Security Pitfalls to Avoid

Building OAuth integrations in production requires careful attention to detail. Here are five of the most common security mistakes backend engineers make and how to avoid them:

1. Storing Tokens in Browser localStorage

If you're building a SPA client that receives access or refresh tokens, never store tokens in localStorage or sessionStorage.

Any script running on your page, including third-party analytics, chat widgets, or compromised npm dependencies, can read localStorage through a Cross-Site Scripting (XSS) vulnerability.

Fix: Store tokens inside HTTP-Only, Secure, SameSite cookies managed by your backend, or use a backend-for-frontend (BFF) architecture where tokens never reach the browser at all.

2. Leaking the Client Secret

It sounds obvious, but client_secret strings end up in public GitHub repositories constantly. Remember: any secret included in Android/iOS apps, React single-page apps, or frontend code is public.

Fix: Keep client secrets inside environment variables on server-side environments. Use PKCE for public clients where secrets can't be protected.

3. Requesting Unnecessary Scopes (Scope Creep)

Asking for full account access when you only need read permission makes users suspicious and increases your liability if a token leaks.

Fix: Follow the principle of least privilege. Request only the specific scopes your app needs immediately. If TravelBuddy later adds a feature to analyze emails, request the Gmail scope dynamically when the user activates that feature.

4. Assuming an OAuth Token Proves Identity

Just because an app receives an access_token from an API doesn't mean it can treat that token as proof of who logged in.

If an attacker passes a valid access token obtained from a different application (a confused deputy attack), your system might accept it if it only checks token validity without checking who the token was issued to aud / audience claim).

Fix: Use OpenID Connect (and validate the id_token claims including aud and iss) when authenticating users.

5. Skipping state or PKCE Validation

If you manually build OAuth flows without checking the state parameter, your application is vulnerable to Login Cross-Site Request Forgery (CSRF). An attacker could trick a user's browser into completing an OAuth flow using the attacker's authorization code, linking the victim's session to the attacker's account data.

Fix: Always generate a cryptographically strong, non-guessable state parameter bound to the user's session, or rely on established security frameworks like Spring Security that enforce this automatically.

Final Thoughts

OAuth 2.0 can feel overwhelming when viewed entirely as a web of specs, RFCs, and terminology.

When you strip away the jargon, OAuth solves one core problem: allowing a user to give an application permission to access their data without handing over their password.

Every moving part in the protocol exists to support that core mission safely:

• Scopes restrict permissions.

• Access Tokens provide temporary, revocable access.

• Authorization Codes keep tokens out of vulnerable browser URLs.

• Refresh Tokens maintain long-term access without harassing the user.

• PKCE protects public applications that can't keep secrets.

• OpenID Connect adds a standardized identity layer on top.

The next time you integrate an OAuth provider in Spring Boot or debug a token error in production, don't focus on memorizing the diagrams. Look at the HTTP request, ask which specific boundary it is crossing, and the design choices will make immediate sense.

It has no user database, no built-in login system, no password file. When you run kubectl get pods, Kubernetes receives an HTTP request and asks one question: who signed this, and do I trust that signature? Everything else — what you're allowed to do, which namespaces you can access, whether your request goes through at all — comes after that question is answered.

This surprises most engineers who are new to Kubernetes. They expect something like a database of users with passwords. Instead, they find a pluggable chain of authenticators, each one able to vouch for a request in a different way:

• Client certificates

• OIDC tokens from an external identity provider

• Cloud provider IAM tokens

• Service account tokens projected into pods.

Any of these can be active at the same time.

Understanding this model is what separates engineers who can debug authentication failures from engineers who copy kubeconfig files and hope for the best.

In this article, you'll work through how the Kubernetes authentication chain works from first principles. You'll see how x509 client certificates are used — and why they're a poor choice for human users in production. You'll configure OIDC authentication with Dex, giving your cluster a real browser-based login flow. And you'll see how AWS, GCP, and Azure each plug into the same underlying model.

Prerequisites

• A running kind cluster — a fresh one works fine, or reuse an existing one

• kubectl and helm installed

• openssl available on your machine (comes pre-installed on macOS and most Linux distros)

• Basic familiarity with what a JWT is (a signed JSON object with claims) — you don't need to be able to write one, just recognise one

All demo files are in the companion GitHub repository.

Table of Contents

• How Kubernetes Authentication Works

  • The Authenticator Chain

  • Users vs Service Accounts

  • What Happens After Authentication

• How to Use x509 Client Certificates

  • How the Certificate Maps to an Identity

  • The Cluster CA

  • The Limits of Certificate-Based Auth

• Demo 1 — Create and Use an x509 Client Certificate

• How to Set Up OIDC Authentication

  • How the OIDC Flow Works in Kubernetes

  • The API Server Configuration

  • JWT Claims Kubernetes Uses

  • How kubelogin Works

• Demo 2 — Configure OIDC Login with Dex and kubelogin

• Cloud Provider Authentication

  • AWS EKS

  • Google GKE

  • Azure AKS

• Webhook Token Authentication

• Cleanup

• Conclusion

How Kubernetes Authentication Works

Every request that reaches the Kubernetes API server — whether from kubectl, a pod, a controller, or a CI pipeline — carries a credential of some kind.

The API server passes that credential through a chain of authenticators in sequence. The first authenticator that can verify the credential wins. If none can, the request is treated as anonymous.

The Authenticator Chain

Kubernetes supports several authentication strategies simultaneously. You can have client certificate authentication and OIDC authentication active on the same cluster at the same time, which is common in production: cluster administrators use certificates, regular developers use OIDC. The strategies active on a cluster are determined by flags passed to the kube-apiserver process.

The strategies available are x509 client certificates, bearer tokens (static token files — rarely used in production), bootstrap tokens (used during node join operations), service account tokens, OIDC tokens, authenticating proxies, and webhook token authentication. A cluster doesn't have to use all of them, and most don't. But knowing they all exist helps when you're diagnosing an auth failure.

Users vs Service Accounts

There is an important distinction in how Kubernetes thinks about identity. Service accounts are Kubernetes objects — they live in a namespace, get created with kubectl create serviceaccount, and have tokens managed by the cluster itself. Every pod runs as a service account. These are machine identities for workloads.

Users, on the other hand, don't exist as Kubernetes objects at all. There is no kubectl create user command. Kubernetes doesn't manage user accounts. Instead, it trusts external systems to assert user identity — a certificate authority, an OIDC provider, or a cloud provider's IAM system. Kubernetes just verifies the assertion and extracts the username and group memberships from it.

What Happens After Authentication

Authentication only answers one question: who is this? Once the API server has a verified identity — a username and zero or more group memberships — it passes the request to the authorisation layer. By default that is RBAC, which checks the identity against Role and ClusterRole bindings to determine what the request is allowed to do.

This is why authentication and authorisation are separate concerns in Kubernetes. A valid certificate gets you past the front door. What you can do inside is RBAC's job. An authenticated user with no RBAC bindings can authenticate successfully but will be denied every API call.

If you want a deep dive into how RBAC rules, roles, and bindings work, check out this handbook on How to Secure a Kubernetes Cluster: RBAC, Pod Hardening, and Runtime Protection.

How to Use x509 Client Certificates

x509 client certificate authentication is the oldest and simplest authentication method in Kubernetes. It's how kubectl works out of the box when you create a cluster — the kubeconfig file that kind or kubeadm generates contains an embedded client certificate signed by the cluster's Certificate Authority.

How the Certificate Maps to an Identity

When the API server receives a request with a client certificate, it validates the certificate against its trusted CA, then reads two fields (The Common Name and Organization) from the certificate to construct an identity.

The Common Name (CN) field becomes the username. The Organization (O) field, which can contain multiple values, becomes the list of groups the user belongs to.

So a certificate with CN=jane and O=engineering authenticates as username jane in group engineering. If you want to give jane permissions, you create a RoleBinding that references either the username jane or the group engineering as a subject.

This is the same mechanism behind system:masters. When kind creates a cluster and writes a kubeconfig for you, it generates a certificate with O=system:masters. Kubernetes has a built-in ClusterRoleBinding that grants cluster-admin to anyone in the system:masters group. That's why your default kubeconfig has full admin access — it's not magic, it's a certificate with the right group.

The Cluster CA

Every Kubernetes cluster has a root Certificate Authority — a private key and a self-signed certificate that the API server trusts. Any client certificate signed by this CA is trusted by the cluster.

The CA certificate and key are typically stored in /etc/kubernetes/pki/ on the control plane node, or in the kube-system namespace as a secret, depending on how the cluster was created.

On kind clusters, you can copy the CA cert and key directly from the control plane container:

docker cp k8s-security-control-plane:/etc/kubernetes/pki/ca.crt ./ca.crt
docker cp k8s-security-control-plane:/etc/kubernetes/pki/ca.key ./ca.key

Whoever holds the CA key can issue certificates for any username and any group, including system:masters. This makes the CA key the most sensitive secret in a Kubernetes cluster. Guard it accordingly.

The Limits of Certificate-Based Auth

Client certificates work, but they have two fundamental problems that make them a poor choice for human users in production.

The first is that Kubernetes doesn't check certificate revocation lists (CRLs). If a developer's kubeconfig is stolen, the embedded certificate remains valid until it expires — which is typically one year in most Kubernetes setups. There's no way to immediately invalidate it. You can't "log out" a certificate. The only mitigation is to rotate the entire cluster CA, which invalidates every certificate including those belonging to other legitimate users.

The second is operational overhead. Certificates must be generated, distributed to users, and rotated before expiry. There's no self-service. In a team of ten engineers, managing certificates is annoying. In a team of a hundred, it's a full-time job.

For human access in production, OIDC is the right answer: short-lived tokens issued by a trusted identity provider, with a central revocation mechanism, and a standard browser-based login flow. Certificates are fine for service accounts and automation, where token management can be automated and rotation is handled programmatically.

That said, understanding certificates isn't optional. Your kubeconfig uses one. Your CI system probably does too. And cert-based auth is what you fall back to when everything else breaks.

Demo 1 — Create and Use an x509 Client Certificate

In this section, you'll generate a user certificate signed by the cluster CA, bind it to an RBAC role, and use it to authenticate to the cluster as a different user.

This guide is for local development and learning only. Manually signing certificates with the cluster CA and storing keys on disk is done here for simplicity.

In production, you should use the Kubernetes CertificateSigningRequest API or cert-manager for certificate issuance, enforce short-lived certificates with automatic rotation, and store private keys in a secrets manager (HashiCorp Vault, AWS Secrets Manager) or hardware security module (HSM) — never distribute the cluster CA key.

Step 1: Copy the CA cert and key from the kind control plane

docker cp k8s-security-control-plane:/etc/kubernetes/pki/ca.crt ./ca.crt
docker cp k8s-security-control-plane:/etc/kubernetes/pki/ca.key ./ca.key

This will create two files in your current directory called ca.crt and ca.key

Step 2: Generate a private key and CSR for a new user

You're creating a certificate for a user named jane in the engineering group:

# Generate the private key
openssl genrsa -out jane.key 2048

# Generate a Certificate Signing Request
# CN = username, O = group
openssl req -new \
  -key jane.key \
  -out jane.csr \
  -subj "/CN=jane/O=engineering"

Step 3: Sign the CSR with the cluster CA

openssl x509 -req \
  -in jane.csr \
  -CA ca.crt \
  -CAkey ca.key \
  -CAcreateserial \
  -out jane.crt \
  -days 365

Expected output:

Certificate request self-signature ok
subject=CN=jane, O=engineering

Step 4: Inspect the certificate

Before using it, confirm the identity it carries:

openssl x509 -in jane.crt -noout -subject -dates

subject=CN=jane, O=engineering
notBefore=Mar 20 10:00:00 2024 GMT
notAfter=Mar 20 10:00:00 2025 GMT

One year from now, this certificate becomes invalid and must be replaced. There's no way to extend it — you have to issue a new one.

Step 5: Build a kubeconfig entry for jane

# Get the cluster API server address from the current context
APISERVER=$(kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}')

# Create a kubeconfig for jane
kubectl config set-cluster k8s-security \
  --server=$APISERVER \
  --certificate-authority=ca.crt \
  --embed-certs=true \
  --kubeconfig=jane.kubeconfig

kubectl config set-credentials jane \
  --client-certificate=jane.crt \
  --client-key=jane.key \
  --embed-certs=true \
  --kubeconfig=jane.kubeconfig

kubectl config set-context jane@k8s-security \
  --cluster=k8s-security \
  --user=jane \
  --kubeconfig=jane.kubeconfig

kubectl config use-context jane@k8s-security \
  --kubeconfig=jane.kubeconfig

Step 6: Test authentication — before RBAC

Try to list pods using jane's kubeconfig:

kubectl get pods -n staging --kubeconfig=jane.kubeconfig

Error from server (Forbidden): pods is forbidden: User "jane" cannot list
resource "pods" in API group "" in the namespace "staging"

This is correct. Jane authenticated successfully — Kubernetes knows who she is. But she has no RBAC bindings, so every API call is denied. Authentication passed, but authorisation failed.

Step 7: Grant jane access with RBAC

RBAC bindings use the username exactly as it appears in the certificate's CN field. If you need a refresher on how Roles, ClusterRoles, and RoleBindings work, this handbook How to Secure a Kubernetes Cluster: RBAC, Pod Hardening, and Runtime Protection covers the full RBAC model. For now, a simple RoleBinding using the built-in view ClusterRole is enough:

# jane-rolebinding.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: jane-reader
  namespace: staging
subjects:
  - kind: User
    name: jane          # matches the CN in the certificate
    apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: view
  apiGroup: rbac.authorization.k8s.io

kubectl apply -f jane-rolebinding.yaml
kubectl get pods -n staging --kubeconfig=jane.kubeconfig

No resources found in staging namespace.

No error — jane can now list pods in staging. She can't delete them, create them, or access other namespaces. The certificate got her in. RBAC determines what she can do.

How to Set Up OIDC Authentication

OpenID Connect is an identity layer on top of OAuth 2.0. It's how Kubernetes integrates with enterprise identity providers — Active Directory, Okta, Google Workspace, Keycloak, and any other provider that speaks OIDC. Understanding how Kubernetes uses it requires following the token from the user's browser to the API server's decision.

How the OIDC Flow Works in Kubernetes

When a developer runs kubectl get pods with OIDC configured, the following happens:

1. kubectl checks whether the current credential in the kubeconfig is a valid, unexpired OIDC token

2. If not, it launches kubelogin, a kubectl plugin that opens a browser window

3. The browser redirects to the OIDC provider (Dex, Okta, your corporate IdP)

4. The user logs in with their corporate credentials

5. The OIDC provider issues a signed JWT and returns it to kubelogin

6. kubelogin caches the token locally (under ~/.kube/cache/oidc-login/) and returns it to kubectl

7. kubectl sends the token to the API server as a Bearer header

8. The API server fetches the provider's public keys from its JWKS endpoint and verifies the token signature

9. If valid, the API server extracts the username and group claims from the token

10. RBAC takes over from there

The Kubernetes API server never contacts the OIDC provider for each request. It only fetches the provider's public keys periodically to verify signatures locally. This makes OIDC authentication stateless and scalable.

The API Server Configuration

For OIDC to work, the API server needs to know where to find the identity provider and how to interpret the tokens it issues.

In Kubernetes v1.30+, this is configured through an AuthenticationConfiguration file passed via the --authentication-config flag. (In older versions, individual --oidc-* flags were used instead, but these were removed in v1.35.)

The AuthenticationConfiguration defines OIDC providers under the jwt key:

On a kind cluster, the --authentication-config flag is set in the cluster configuration before creation, not after. You'll see this in the next demo.

JWT Claims Kubernetes Uses

A JWT is a signed JSON object with three sections: a header, a payload, and a signature. The payload is a set of claims – key-value pairs that assert facts about the token. Kubernetes reads specific claims from the payload to build an identity.

The required claims are iss (the issuer URL, must match issuer.url in the AuthenticationConfiguration), sub (the subject, a unique identifier for the user), and aud (the audience, must match the issuer.audiences list). The exp claim (expiry time) is also required as the API server rejects expired tokens.

The most useful optional claim is groups (or whatever you configure via claimMappings.groups.claim). When this claim is present, Kubernetes can map OIDC group memberships directly to RBAC group bindings. A user in the platform-engineers group in your identity provider automatically gets the RBAC permissions you've bound to that group in Kubernetes — no manual user management required.

How kubelogin Works

kubelogin (also distributed as kubectl oidc-login) is a kubectl credential plugin. Instead of embedding a static certificate or token in your kubeconfig, you configure a credential plugin that runs a helper binary when kubectl needs a token.

When kubelogin is invoked, it checks its local token cache. If the cached token is still valid, it returns it immediately. If the token has expired, it initiates the OIDC authorization code flow — opens a browser, redirects to the identity provider, receives the token after login, caches it locally, and returns it to kubectl. The whole flow takes about five seconds when it triggers.

This means tokens are short-lived (typically an hour) and rotate automatically. If a developer's machine is compromised, the token expires on its own. There is no long-lived credential sitting in a file somewhere.

Demo 2 — Configure OIDC Login with Dex and kubelogin

In this section, you'll deploy Dex as a self-hosted OIDC provider, configure a kind cluster to trust it, and log in with a browser. Dex is a good demo vehicle because it runs inside the cluster and doesn't require a cloud account or an external service.

This guide is for local development and learning only. Self-signed certificates, static passwords, and certs stored on disk are used here for simplicity.

In production, use a managed identity provider (Azure Entra ID, Google Workspace, Okta), automate certificate lifecycle with cert-manager, and store secrets in a secrets manager (HashiCorp Vault, AWS Secrets Manager) or inject them via CSI driver — never commit or store certs as local files.

Step 1: Create a kind cluster with OIDC authentication

OIDC authentication for the API server must be configured at cluster creation time on Kind because the API server needs to know which identity provider to trust before it starts accepting requests.

Note: Kubernetes v1.30+ deprecated the --oidc-* API server flags in favor of the structured AuthenticationConfiguration API (via --authentication-config). In v1.35+ the old flags are removed entirely. This guide uses the new approach.

nip.io is a wildcard DNS service — dex.127.0.0.1.nip.io resolves to 127.0.0.1. This lets us use a real hostname for TLS without editing /etc/hosts.

First, generate a self-signed CA and TLS certificate for Dex:

# Generate a CA for Dex
openssl req -x509 -newkey rsa:4096 -keyout dex-ca.key \
  -out dex-ca.crt -days 365 -nodes \
  -subj "/CN=dex-ca"

# Generate a certificate for Dex signed by that CA
openssl req -newkey rsa:2048 -keyout dex.key \
  -out dex.csr -nodes \
  -subj "/CN=dex.127.0.0.1.nip.io"

openssl x509 -req -in dex.csr \
  -CA dex-ca.crt -CAkey dex-ca.key \
  -CAcreateserial -out dex.crt -days 365 \
  -extfile <(printf "subjectAltName=DNS:dex.127.0.0.1.nip.io")

Next, generate the AuthenticationConfiguration file. This tells the API server how to validate JWTs — which issuer to trust (url), which audience to expect (audiences), and which JWT claims map to Kubernetes usernames and groups (claimMappings). The CA cert is inlined so the API server can verify Dex's TLS certificate when fetching signing keys:

cat > auth-config.yaml <<EOF
apiVersion: apiserver.config.k8s.io/v1beta1
kind: AuthenticationConfiguration
jwt:
  - issuer:
      url: https://dex.127.0.0.1.nip.io:32000
      audiences:
        - kubernetes
      certificateAuthority: |
$(sed 's/^/        /' dex-ca.crt)
    claimMappings:
      username:
        claim: email
        prefix: ""
      groups:
        claim: groups
        prefix: ""
EOF

The kind-oidc.yaml config uses extraPortMappings to expose Dex's port to your browser, extraMounts to copy files into the Kind node, and a kubeadmConfigPatch to pass --authentication-config to the API server:

# kind-oidc.yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
  - role: control-plane
    extraPortMappings:
      # Forward port 32000 from the Docker container to localhost,
      # so your browser can reach Dex's login page
      - containerPort: 32000
        hostPort: 32000
        protocol: TCP
    extraMounts:
      # Copy files from your machine into the Kind node's filesystem
      - hostPath: ./dex-ca.crt
        containerPath: /etc/ca-certificates/dex-ca.crt
        readOnly: true
      - hostPath: ./auth-config.yaml
        containerPath: /etc/kubernetes/auth-config.yaml
        readOnly: true
    kubeadmConfigPatches:
      # Patch the API server to enable OIDC authentication
      - |
        kind: ClusterConfiguration
        apiServer:
          extraArgs:
            # Tell the API server to load our AuthenticationConfiguration
            authentication-config: /etc/kubernetes/auth-config.yaml
          extraVolumes:
            # Mount files into the API server pod (it runs as a static pod,
            # so it needs explicit volume mounts even though files are on the node)
            - name: dex-ca
              hostPath: /etc/ca-certificates/dex-ca.crt
              mountPath: /etc/ca-certificates/dex-ca.crt
              readOnly: true
              pathType: File
            - name: auth-config
              hostPath: /etc/kubernetes/auth-config.yaml
              mountPath: /etc/kubernetes/auth-config.yaml
              readOnly: true
              pathType: File

Create the cluster:

kind create cluster --name k8s-auth --config kind-oidc.yaml

Step 2: Deploy Dex

Dex is an OIDC-compliant identity provider that acts as a bridge between Kubernetes and upstream identity sources (LDAP, SAML, GitHub, and so on). In this demo it runs inside the cluster with a static password database — two hardcoded users you can log in as.

The API server doesn't talk to Dex directly on every request. It only needs Dex's CA certificate (which you inlined in the AuthenticationConfiguration) to verify the JWT signatures on tokens that Dex issues.

The deployment has four parts: a ConfigMap with Dex's configuration, a Deployment to run Dex, a NodePort Service to expose it on port 32000 (matching the issuer URL), and RBAC resources so Dex can store state using Kubernetes CRDs.

First, create the namespace and load the TLS certificate as a Kubernetes Secret. Dex needs this to serve HTTPS. Without it, your browser and the API server would refuse to connect:

kubectl create namespace dex

kubectl create secret tls dex-tls \
  --cert=dex.crt \
  --key=dex.key \
  -n dex

Save the following as dex-config.yaml. This configures Dex with a static password connector — two hardcoded users for the demo:

# dex-config.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: dex-config
  namespace: dex
data:
  config.yaml: |
    # issuer must exactly match the URL in your AuthenticationConfiguration
    issuer: https://dex.127.0.0.1.nip.io:32000

    # Dex stores refresh tokens and auth codes — here it uses Kubernetes CRDs
    storage:
      type: kubernetes
      config:
        inCluster: true

    # Dex's HTTPS listener — serves the login page and token endpoints
    web:
      https: 0.0.0.0:5556
      tlsCert: /etc/dex/tls/tls.crt
      tlsKey: /etc/dex/tls/tls.key

    # staticClients defines which applications can request tokens.
    # "kubernetes" is the client ID that kubelogin uses when authenticating
    staticClients:
      - id: kubernetes
        redirectURIs:
          - http://localhost:8000     # kubelogin listens here to receive the callback
        name: Kubernetes
        secret: kubernetes-secret     # shared secret between kubelogin and Dex

    # Two demo users with the password "password" (bcrypt-hashed).
    # In production, you'd connect Dex to LDAP, SAML, or a social login instead
    enablePasswordDB: true
    staticPasswords:
      - email: "jane@example.com"
        # bcrypt hash of "password" — generate your own with: htpasswd -bnBC 10 "" password
        hash: "\(2a\)10$2b2cU8CPhOTaGrs1HRQuAueS7JTT5ZHsHSzYiFPm1leZck7Mc8T4W"
        username: "jane"
        userID: "08a8684b-db88-4b73-90a9-3cd1661f5466"
      - email: "admin@example.com"
        hash: "\(2a\)10$2b2cU8CPhOTaGrs1HRQuAueS7JTT5ZHsHSzYiFPm1leZck7Mc8T4W"
        username: "admin"
        userID: "a8b53e13-7e8c-4f7b-9a33-6c2f4d8c6a1b"
        groups:
          - platform-engineers

Save the following as dex-deployment.yaml. This creates the Deployment, Service, ServiceAccount, and RBAC that Dex needs to run:

# dex-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: dex
  namespace: dex
spec:
  replicas: 1
  selector:
    matchLabels:
      app: dex
  template:
    metadata:
      labels:
        app: dex
    spec:
      serviceAccountName: dex
      containers:
        - name: dex
          # v2.45.0+ required — earlier versions don't include groups from staticPasswords in tokens
          image: ghcr.io/dexidp/dex:v2.45.0
          command: ["dex", "serve", "/etc/dex/cfg/config.yaml"]
          ports:
            - name: https
              containerPort: 5556
          volumeMounts:
            - name: config
              mountPath: /etc/dex/cfg
            - name: tls
              mountPath: /etc/dex/tls
      volumes:
        - name: config
          configMap:
            name: dex-config
        - name: tls
          secret:
            secretName: dex-tls
---
# NodePort Service — exposes Dex on port 32000 on the Kind node.
# Combined with extraPortMappings, this makes Dex reachable from your browser
apiVersion: v1
kind: Service
metadata:
  name: dex
  namespace: dex
spec:
  type: NodePort
  ports:
    - name: https
      port: 5556
      targetPort: 5556
      nodePort: 32000
  selector:
    app: dex
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: dex
  namespace: dex
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: dex
rules:
  - apiGroups: ["dex.coreos.com"]
    resources: ["*"]
    verbs: ["*"]
  - apiGroups: ["apiextensions.k8s.io"]
    resources: ["customresourcedefinitions"]
    verbs: ["create"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: dex
subjects:
  - kind: ServiceAccount
    name: dex
    namespace: dex
roleRef:
  kind: ClusterRole
  name: dex
  apiGroup: rbac.authorization.k8s.io

kubectl apply -f dex-config.yaml
kubectl apply -f dex-deployment.yaml
kubectl rollout status deployment/dex -n dex

Step 3: Install kubelogin

# macOS
brew install int128/kubelogin/kubelogin

# Linux
curl -LO https://github.com/int128/kubelogin/releases/latest/download/kubelogin_linux_amd64.zip
unzip -j kubelogin_linux_amd64.zip kubelogin -d /tmp
sudo mv /tmp/kubelogin /usr/local/bin/kubectl-oidc_login
rm kubelogin_linux_amd64.zip

Confirm it's installed:

kubectl oidc-login --version

Step 4: Configure a kubeconfig entry for OIDC

This creates a new user and context in your kubeconfig. Instead of using a client certificate (like the default Kind admin), it tells kubectl to use kubelogin to get a token from Dex.

The --oidc-extra-scope flags are important: without email and groups, Dex won't include those claims in the JWT, and the API server won't know who you are or what groups you belong to.

kubectl config set-credentials oidc-user \
  --exec-api-version=client.authentication.k8s.io/v1beta1 \
  --exec-command=kubectl \
  --exec-arg=oidc-login \
  --exec-arg=get-token \
  --exec-arg=--oidc-issuer-url=https://dex.127.0.0.1.nip.io:32000 \
  --exec-arg=--oidc-client-id=kubernetes \
  --exec-arg=--oidc-client-secret=kubernetes-secret \
  --exec-arg=--oidc-extra-scope=email \
  --exec-arg=--oidc-extra-scope=groups \
  --exec-arg=--certificate-authority=$(pwd)/dex-ca.crt

kubectl config set-context oidc@k8s-auth \
  --cluster=kind-k8s-auth \
  --user=oidc-user

kubectl config use-context oidc@k8s-auth

Step 5: Trigger the login flow

Jane has no RBAC permissions yet, so first grant her read access from the admin context:

kubectl --context kind-k8s-auth create clusterrolebinding jane-view \
  --clusterrole=view --user=jane@example.com

Now switch to the OIDC context and trigger a login:

kubectl get pods -n default

Your browser opens and redirects to the Dex login page. Log in as jane@example.com with password password.

After login, the terminal completes:

No resources found in default namespace.

The browser-based authentication worked. kubectl received the token from Dex, sent it to the API server, the API server validated the JWT signature using the CA certificate from the AuthenticationConfiguration, extracted jane@example.com from the email claim, matched it against the RBAC binding, and authorized the request.

Without the clusterrolebinding, you would see Error from server (Forbidden) — authentication succeeds (the API server knows who you are) but authorization fails (jane has no permissions). This is the distinction between 401 Unauthorized and 403 Forbidden.

Step 6: Inspect the JWT

A JWT (JSON Web Token) is a signed JSON payload that contains claims about the user. kubelogin caches the token locally under ~/.kube/cache/oidc-login/ so you don't have to log in on every kubectl command.

List the directory to find the cached file:

ls ~/.kube/cache/oidc-login/

Decode the JWT payload directly from the cache:

cat ~/.kube/cache/oidc-login/$(ls ~/.kube/cache/oidc-login/ | grep -v lock | head -1) | \
  python3 -c "
import json, sys, base64
token = json.load(sys.stdin)['id_token'].split('.')[1]
token += '=' * (4 - len(token) % 4)
print(json.dumps(json.loads(base64.urlsafe_b64decode(token)), indent=2))
"

You'll see something like:

{
  "iss": "https://dex.127.0.0.1.nip.io:32000",
  "sub": "CiQwOGE4Njg0Yi1kYjg4LTRiNzMtOTBhOS0zY2QxNjYxZjU0NjYSBWxvY2Fs",
  "aud": "kubernetes",
  "exp": 1775307910,
  "iat": 1775221510,
  "email": "jane@example.com",
  "email_verified": true
}

The email claim becomes jane's Kubernetes username because the AuthenticationConfiguration maps username.claim: email. The aud matches the configured audiences. The iss matches the issuer url. This is how the API server validates the token without contacting Dex on every request — it only needs the CA certificate to verify the JWT signature.

Step 7: Map OIDC groups to RBAC

The admin@example.com user has a groups claim in the Dex config containing platform-engineers. Instead of creating individual RBAC bindings per user, you can bind permissions to a group — anyone whose JWT contains that group gets the permissions automatically:

# platform-engineers-binding.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: platform-engineers-admin
subjects:
  - kind: Group
    name: platform-engineers     # matches the groups claim in the JWT
    apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: cluster-admin
  apiGroup: rbac.authorization.k8s.io

You're currently logged in as jane@example.com via the OIDC context, but jane only has view permissions — she can't create cluster-wide RBAC bindings. Switch back to the admin context to apply this:

kubectl config use-context kind-k8s-auth
kubectl apply -f platform-engineers-binding.yaml
kubectl config use-context oidc@k8s-auth

Now clear the cached token to log out of jane's session, then trigger a new login as admin@example.com:

# Clear the cached token — this is how you "log out" with kubelogin
rm -rf ~/.kube/cache/oidc-login/

# This will open the browser again for a fresh login
kubectl get pods -n default

Log in as admin@example.com with password password. This time the JWT will contain "groups": ["platform-engineers"], which matches the ClusterRoleBinding you just created. The admin user gets full cluster access — without ever being added to a kubeconfig by name.

You can verify by decoding the new token (Step 6) — the groups claim will be present:

{
  "email": "admin@example.com",
  "groups": ["platform-engineers"]
}

This is the real power of OIDC group claims: you manage group membership in your identity provider, and Kubernetes permissions follow automatically. Add someone to the platform-engineers group in Dex (or any upstream IdP), and they get cluster-admin access on their next login — no kubeconfig or RBAC changes needed.

Cloud Provider Authentication

AWS, GCP, and Azure each give Kubernetes clusters a native authentication mechanism that ties into their IAM systems.

The implementations differ in API surface, but they all use the same underlying mechanism: OIDC token projection. Once you understand how Dex works above, these are all variations on the same theme.

AWS EKS

EKS uses the aws-iam-authenticator to translate AWS IAM identities into Kubernetes identities. When you run kubectl against an EKS cluster, the AWS CLI generates a short-lived token signed with your IAM credentials. The API server passes this token to the aws-iam-authenticator webhook, which verifies it against AWS STS and returns the corresponding username and groups.

User access is controlled via the aws-auth ConfigMap in kube-system, which maps IAM role ARNs and IAM user ARNs to Kubernetes usernames and groups. A typical entry looks like this:

# In kube-system/aws-auth ConfigMap
mapRoles:
  - rolearn: arn:aws:iam::123456789:role/platform-engineers
    username: platform-engineer:{{SessionName}}
    groups:
      - platform-engineers

AWS is migrating from the aws-auth ConfigMap to a newer Access Entries API, which manages the same mapping through the EKS API rather than a ConfigMap. The underlying authentication mechanism is the same.

Google GKE

GKE integrates with Google Cloud IAM using two different mechanisms, depending on whether you're authenticating as a human user or as a workload.

For human users, GKE accepts standard Google OAuth2 tokens. Running gcloud container clusters get-credentials writes a kubeconfig that uses the gcloud CLI as a credential plugin, generating short-lived tokens from your Google account automatically.

For pod-level identity — letting a pod assume a Google Cloud IAM role — GKE uses Workload Identity. You annotate a Kubernetes service account to bind it to a Google Service Account, and pods running as that service account can call Google Cloud APIs using the GSA's permissions:

# Bind a Kubernetes SA to a Google Service Account
kubectl annotate serviceaccount my-app \
  --namespace production \
  iam.gke.io/gcp-service-account=my-app@my-project.iam.gserviceaccount.com

Azure AKS

AKS integrates with Azure Active Directory. When Azure AD integration is enabled, kubectl requests an Azure AD token on behalf of the user via the Azure CLI, and the AKS API server validates it against Azure AD.

For pod-level identity, AKS uses Azure Workload Identity, which follows the same OIDC federation pattern as GKE Workload Identity. A Kubernetes service account is annotated with an Azure Managed Identity client ID, and pods can request Azure AD tokens without storing any credentials:

# Annotate a service account with the Azure Managed Identity client ID
kubectl annotate serviceaccount my-app \
  --namespace production \
  azure.workload.identity/client-id=<MANAGED_IDENTITY_CLIENT_ID>

The underlying pattern across all three providers is the same: a trusted OIDC token is issued by the cloud provider, verified by the Kubernetes API server, and mapped to an identity through a binding (the aws-auth ConfigMap, a GKE Workload Identity binding, or an AKS federated identity credential). The OIDC section in this article is the conceptual foundation for all of them.

Webhook Token Authentication

Webhook token authentication is worth knowing about because it appears in several common Kubernetes setups, even if you never configure it yourself.

When a request arrives with a bearer token that no other authenticator recognises, Kubernetes can send that token to an external HTTP endpoint for validation. The endpoint returns a response indicating who the token belongs to.

This is how EKS authentication worked before the aws-iam-authenticator was built into the API server. It's also how bootstrap tokens work during node join operations: a token is generated, embedded in the kubeadm join command, and validated by the bootstrap webhook when the new node contacts the API server for the first time.

For most clusters, you'll encounter webhook auth as something already running rather than something you configure. The main thing to know is that it exists and what it looks like when it appears in logs or configuration.

Cleanup

To remove everything created in this article:

# Delete the OIDC demo cluster
kind delete cluster --name k8s-auth

# Remove generated certificate files
rm -f ca.crt ca.key jane.key jane.csr jane.crt jane.kubeconfig
rm -f dex-ca.crt dex-ca.key dex.crt dex.key dex.csr dex-ca.srl auth-config.yaml

# Remove the kubelogin token cache
rm -rf ~/.kube/cache/oidc-login/

Conclusion

Kubernetes authentication is not a single mechanism — it's a chain of pluggable strategies, each one suited to different use cases. In this article you worked through the most important ones.

x509 client certificates are how Kubernetes works out of the box. The CN field becomes the username, the O field becomes the group, and the cluster CA is the trust anchor. You created a certificate for a new user, bound it to RBAC, and saw exactly how authentication and authorisation interact — authentication gets you in, RBAC determines what you can do.

You also saw the fundamental limitation: Kubernetes doesn't check certificate revocation lists, so a compromised certificate remains valid until it expires. This makes certificates a poor fit for human users in production environments.

OIDC is the production-grade answer. Tokens are short-lived, issued by a trusted identity provider, and map directly to Kubernetes groups through JWT claims. You deployed Dex as a self-hosted OIDC provider, configured the API server to trust it, and set up kubelogin for browser-based authentication.

You then decoded a JWT to see exactly what the API server reads from it, and mapped an OIDC group claim to a Kubernetes ClusterRoleBinding.

Cloud provider authentication — EKS, GKE, AKS — uses the same OIDC foundation with provider-specific wrappers. Understanding how Dex works makes each of those systems immediately readable.

All YAML, certificates, and configuration files from this article are in the companion GitHub repository.

Why does this happen? The authentication worked, the session is valid, the user is authenticated, but the authorization failed.

This specific issue is called IDOR (Insecure Direct Object Reference). It’s one of the most common security bugs and is categorized under Broken Object Level Authorization (BOLA) in the OWASP API Security Top 10.

In this tutorial, you’ll learn:

• Why IDOR happens

• Why authentication alone is not enough

• How object-level authorization works

• How to fix IDOR properly in Next.js API routes

• How to design safer APIs from the start

Table of Content

• Table of Content

• Authentication vs. Authorization

• What is an IDOR Vulnerability?

• The Vulnerable Pattern in Next.js

• How to Handle IDOR in Next.js

  • Object-Level Authorization

• How to Design Safer Endpoints (/api/me)

• Mental Model for API Design

• Conclusion

Authentication vs. Authorization

Before writing further, let’s clarify something critical.

• Authentication answers: Who are you?

• Authorization answers: What are you allowed to access?

In IDOR scenarios, authentication works (the user is logged in), while authorization is missing or incomplete. That distinction is the core lesson of this article.

What is an IDOR Vulnerability?

An IDOR vulnerability happens when your API fetches a resource by an identifier (like a user ID), and then you do not verify that the requester owns or is allowed to access that resource.

Example of such a request:

GET /api/users/123

The code above is an HTTP GET request to the /api/users/123 route. The GET method is used to request data from the server. This indicates that the client is requesting a specific user with the ID 123 and this request returns the user data in a response (often in JSON format).

If your backend makes the request using a similar structure to the code snippet below without checking who is making the request, you have an IDOR vulnerability, even if the user is logged in.

db.user.findUnique({ where: { id: "123" } })

What the code does is to query the database for a single user record. The db.user part refers to the user model/table and findUnique() is a method that returns only one record based on a unique field. Inside the method, the where clause specifies the filter condition and { id: "123" } tells the database to find the user whose unique id equals "123". If a matching record exists, it returns that user object; otherwise, it returns null.

The Vulnerable Pattern in Next.js

Looking at this Next.js App Router API route:

// app/api/users/[id]/route.ts
import { NextResponse } from "next/server";
import { db } from "@/lib/db";

export async function GET(
  req: Request,
  { params }: { params: { id: string } }
) {
  const user = await db.user.findUnique({
    where: { id: params.id },
    select: { id: true, email: true, name: true },
  });

  return NextResponse.json({ user });
}

Before going to the implication of this code snippet, let's understand what the code does. It defines a dynamic API route for /api/users/[id]. The exported GET function is an async route handler that runs when a GET request is made to this endpoint. It receives the request object and a params object, where params.id contains the dynamic [id] in the URL segment. The db.user.findUnique() method queries the database for a user whose id matches params.id, and the select option limits the returned fields to id, email, and name. Finally, NextResponse.json() sends the retrieved user data back to the client as a JSON response.

Now, to the implication, the code is a bad approach because the route accepts a user ID from the URL, fetches that user directly from the database, and returns the result. There is no session validation, no ownership check, and no role check.

If a logged-in user changes the id in the URL, they may access other users’ data. This is simply IDOR.

How to Handle IDOR in Next.js

The first element of defense is verifying identity. We’ll use getServerSession from NextAuth (adjust if using another auth provider). This change ensures that you read the session from the cookies, verify it on the server side, and ensure the user has a valid ID. This prevents unauthenticated access.

// lib/auth.ts
import { getServerSession } from "next-auth";
import { authOptions } from "@/lib/authOptions";

export async function requireSession() {
  const session = await getServerSession(authOptions);

  if (!session?.user?.id) {
    return null;
  }

  return session;
}

The code above defines an authentication helper function called requireSession. The getServerSession(authOptions) function retrieves the current user session on the server using the provided authentication configuration. The optional chaining (session?.user?.id) in the if block that follows safely checks whether a logged-in user and their id exist. If no valid session or user ID is found, the function returns null, indicating the request is unauthenticated. Otherwise, it returns the full session object so it can be used in protected routes or server logic.

You have successfully confirmed that the user and session exist; now, update the route:

export async function GET(
  req: Request,
  { params }: { params: { id: string } }
) {
  const session = await requireSession();

  if (!session) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const user = await db.user.findUnique({
    where: { id: params.id },
    select: { id: true, email: true, name: true },
  });

  return NextResponse.json({ user });
}

The fix is incomplete yet, but in the above code, you’ve prevented anonymous access. The GET handler calls the requireSession() that was created earlier to verify that the request is authenticated. If no valid session is returned, it immediately responds with a JSON error message and a 401 Unauthorized HTTP status. If the user is authenticated, it proceeds to call db.user.findUnique() to fetch the user whose id matches params.id, selecting only the id, email, and name fields. Finally, it returns the retrieved user data as a JSON response using NextResponse.json().

Something is still missing. Can you guess? Any authenticated user can still request any resource by changing the URL path to the request they want. How? This leads us to object-level authorization.

Object-Level Authorization

An object-level authorization ensures that a user can only access their own data (unless explicitly permitted).

The improvement to the code would be to add an ownership check. The adjustment ensures the API request checks if the requester is authenticated and owns the requested object. If either fails, access is denied.

export async function GET(
  req: Request,
  { params }: { params: { id: string } }
) {
  const session = await requireSession();

  if (!session) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  if (session.user.id !== params.id) {
    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
  }

  const user = await db.user.findUnique({
    where: { id: params.id },
    select: { id: true, email: true, name: true },
  });

  return NextResponse.json({ user });
}

Let's take a look at what happened in the code, the GET handler first authenticates the request using requireSession(), returning a 401 response if no valid session exists. It then performs an authorization check by comparing session.user.id with params.id. If they do not match, it returns a 403 Forbidden response, preventing users from accessing other users’ data. If both checks pass, it queries the database using db.user.findUnique() to retrieve the specified user and limits the result to selected fields. Finally, it sends the user data back as a JSON response. With this, you’ve enforced an object-level authorization.

How to Design Safer Endpoints (/api/me)

The safest approach in designing your endpoint is to eliminate the risk entirely. Instead of allowing users to specify IDs (/api/users/:id), use /api/me, because the server already knows the user’s identity from the session.

// app/api/me/route.ts
export async function GET() {
  const session = await requireSession();

  if (!session) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const user = await db.user.findUnique({
    where: { id: session.user.id },
    select: { id: true, email: true, name: true },
  });

  return NextResponse.json({ user });
}

This approach makes sure that your API only returns data for the currently authenticated user. It first calls requireSession() to ensure the request is authenticated, returning a 401 response if no session exists. Instead of using a URL parameter, it reads the user’s ID directly from session.user.id, ensuring the user can only access their own data. It then calls db.user.findUnique() to retrieve that user from the database, selecting only specific fields, and returns the result as a JSON response.

You can be confident with this approach because the client cannot manipulate user IDs. The server gets the user identity from a trusted source, and the attack surface is reduced. This is called secure-by-design API model.

Now, you should clearly understand that authentication does not imply authorization. Hence,

• IDOR occurs when object ownership is not verified

• Every API route that accepts an ID must validate access

• Safer API design reduces vulnerability surface

• Authorization must always run on the server

Mental Model for API Design

When writing any API route, answer these questions:

1. Who is making this request?

2. What object are they requesting?

3. Does policy allow them to access it?

If you cannot clearly answer all three, your route may be vulnerable.

Conclusion

IDOR vulnerabilities happen when APIs trust user-supplied identifiers without verifying ownership or permission.

To prevent them in Next.js, authenticate every private route, enforce object-level authorization, centralize authorization logic, and write tests for forbidden access.

Security is not about adding logins, it’s about enforcing security policy on every object access.

Traditional methods often rely on server sessions and cookies. Those work, but they don’t always scale well, especially when you’re building APIs or mobile apps that talk to multiple services. This is why JWTs, or JSON Web Tokens, are useful. They’re small, self-contained tokens that can carry user data safely between a client and a server.

JWTs make it easy to verify users without constantly checking a database – but they also expire fast to reduce risk. To keep users logged in without forcing them to sign in again every few minutes, we use something called a refresh token. It’s a separate, long-lived token that can request new access tokens when the old ones expire.

In this guide, we’ll walk through how to build a secure authentication system using JWTs and refresh tokens. You’ll learn how to generate tokens, validate them, handle expiry, and keep everything safe from common security threats.

Table of Contents

1. Understanding JWTs (JSON Web Tokens)

2. Setting Up the Project

3. How to Implement JWT Authentication

4. How to Verify JWTs and Protect Routes

5. Refresh Tokens and Rotation

6. Conclusion

Understanding JWTs (JSON Web Tokens)

A JWT, short for JSON Web Token, is a compact way to share information between a client and a server. It’s often used to prove that a user is who they say they are. The token is created on the server after a user logs in and is then sent back to the client. The client then includes this token with each request, so the server knows who is making the call.

A JWT has three parts: a header, a payload, and a signature.

• The header usually tells the system which algorithm was used to sign the token.

• The payload contains the data, such as the user’s ID or role.

• The signature is the part that keeps everything secure. It’s created by hashing the header and payload with a secret key.

Once created, a JWT looks like a long string of random characters separated by dots. When the client sends it back to the server, the server verifies the signature using the same secret key. If it matches, the request is trusted.

One of the main benefits of JWTs is that they are stateless. The server doesn’t need to store session data. Everything needed to verify the user is already inside the token. This makes them fast and easy to use in modern APIs and microservices.

JWTs do have a downside: they cannot be revoked easily once issued. If a token is stolen, the attacker can use it until it expires. This is why short token lifetimes matter. It’s also why refresh tokens exist.

In the next section, we’ll finish the basic JWT setup. After that, we’ll add refresh tokens in “Refresh Tokens and Rotation.” That part shows how to handle expiry without making users log in again.

Setting Up the Project

Before writing any code, let’s set up a simple backend where we can build and test our authentication system. For this guide, we’ll use Node.js with Express, since it’s lightweight and easy to follow. You can use any stack later once you understand the flow.

Prerequisites

Make sure you have:

• Node.js and npm installed

• A text editor (VS Code works great)

• Basic knowledge of JavaScript and APIs

1. Initialize the Project

Create a new folder and open it in your terminal.

mkdir jwt-auth-demo
cd jwt-auth-demo
npm init -y

This creates a package.json file that will track your dependencies.

2. Install Dependencies

You’ll need a few packages to get started:

• express: the web framework

• jsonwebtoken: to create and verify tokens

• bcryptjs: to hash passwords

• dotenv: to manage environment variables

Install them all at once like this:

npm install express jsonwebtoken bcryptjs dotenv

If you want auto-reloading while developing, install nodemon as a dev dependency:

npm install --save-dev nodemon

3. Project Structure

Here’s a clean structure to keep things organized:

jwt-auth-demo/
│
├── server.js
├── .env
├── package.json
│
├── config/
│   └── db.js
│
├── middleware/
│   └── auth.js
│
├── routes/
│   └── auth.js
│
└── models/
    └── user.js

4. Basic Express Setup

In server.js, start with a minimal Express server.

require('dotenv').config();
const express = require('express');
const app = express();

app.use(express.json());

app.get('/', (req, res) => {
  res.send('JWT Auth API running');
});

const PORT = process.env.PORT || 5000;
app.listen(PORT, () => console.log(`Server running on port ${PORT}`));

You can now run it using:

node server.js

or, if you’re using nodemon:

npx nodemon server.js

If everything is set up correctly, visiting http://localhost:5000 should display “JWT Auth API running”:

How to Implement JWT Authentication

Now that your server is up, let’s add real authentication. We’ll start with user registration, password hashing, and login. Each user will get a token after logging in, which they can use to access protected routes.

1. Set Up the User Model

We’ll store users in a simple database. For this demo, let’s use MongoDB with Mongoose, since it’s quick to set up and easy to scale later.

Install the required packages:

npm install mongoose

Then create models/user.js:

const mongoose = require('mongoose');

const userSchema = new mongoose.Schema({
  username: { type: String, required: true, unique: true },
  email: { type: String, required: true, unique: true },
  password: { type: String, required: true }
});

module.exports = mongoose.model('User', userSchema);

We store users with a unique email and a hashed password. The database never sees the raw password. Hashing makes stolen data harder to use.

2. Connect to MongoDB

Inside config/db.js:

const mongoose = require('mongoose');

const connectDB = async () => {
  try {
    await mongoose.connect(process.env.MONGO_URI);
    console.log('MongoDB connected');
  } catch (err) {
    console.error(err.message);
    process.exit(1);
  }
};

module.exports = connectDB;

mongoose.connect reads the connection string from .env. If the connection fails, we exit the process so we don’t continue in a broken state.

Update your server.js to include the connection:

const connectDB = require('./config/db');
connectDB();

And don’t forget to add your MongoDB URI in the .env file:

MONGO_URI=mongodb+srv://yourusername:yourpassword@cluster.mongodb.net/auth
JWT_SECRET=your_jwt_secret_key

3. Create Registration and Login Routes

In routes/auth.js:

const express = require('express');
const bcrypt = require('bcryptjs');
const jwt = require('jsonwebtoken');
const User = require('../models/user');

const router = express.Router();

// Register a new user
router.post('/register', async (req, res) => {
  try {
    const { username, email, password } = req.body;

    const existingUser = await User.findOne({ email });
    if (existingUser) return res.status(400).json({ message: 'User already exists' });

    const hashedPassword = await bcrypt.hash(password, 10);

    const newUser = new User({ username, email, password: hashedPassword });
    await newUser.save();

    res.status(201).json({ message: 'User created successfully' });
  } catch (err) {
    res.status(500).json({ message: 'Server error' });
  }
});

// Login and issue JWT
router.post('/login', async (req, res) => {
  try {
    const { email, password } = req.body;

    const user = await User.findOne({ email });
    if (!user) return res.status(400).json({ message: 'Invalid credentials' });

    const isMatch = await bcrypt.compare(password, user.password);
    if (!isMatch) return res.status(400).json({ message: 'Invalid credentials' });

    const payload = { id: user._id, email: user.email };

    const token = jwt.sign(payload, process.env.JWT_SECRET, { expiresIn: '15m' });

    res.json({ token });
  } catch (err) {
    res.status(500).json({ message: 'Server error' });
  }
});

module.exports = router;

Add it to your server in server.js:

const authRoutes = require('./routes/auth');
app.use('/api/auth', authRoutes);

4. Test It Out

You can now test these routes using Postman or Insomnia.

Send a POST request to /api/auth/register with a JSON body:

{
  "username": "demoUser",
  "email": "demo@email.com",
  "password": "mypassword"
}

The register route checks for an existing user by email. It hashes the password with a cost factor of 10 and then returns a 201 on success. We don’t log the password or include it in the response.

Then log in at /api/auth/login to receive a JWT.

The login route finds the user by email and compares the password with bcrypt.compare. If it matches, we sign a token with a small payload: the user ID and email. The JWT_SECRET signs the token so the server can verify it later. The expiresIn: '15m' setting keeps the token short-lived to limit risk. The response only includes the token. User data can be fetched from a protected route.

Once you get the token, copy it, you’ll use it to access protected routes later.

How to Verify JWTs and Protect Routes

Now that login returns a token, we should verify it on each request that needs auth. We will write a small middleware that checks the Authorization header, validates the token, and adds the user info to the request.

1. Create the Auth Middleware

Create middleware/auth.js:

const jwt = require('jsonwebtoken');

function auth(req, res, next) {
  const authHeader = req.headers.authorization || '';
  const [scheme, token] = authHeader.split(' ');

  if (scheme !== 'Bearer' || !token) {
    return res.status(401).json({ message: 'Missing or invalid Authorization header' });
  }

  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    req.user = { id: decoded.id, email: decoded.email };
    next();
  } catch (err) {
    if (err.name === 'TokenExpiredError') {
      return res.status(401).json({ message: 'Access token expired' });
    }
    return res.status(401).json({ message: 'Invalid token' });
  }
}

module.exports = auth;

What it does:

• Reads the Authorization header.

• Checks for the Bearer <token> format.

• Verifies the token with the secret.

• Attaches a simple user object to req for later use.

2. Create the Protected Route

Create a small profile route that returns the current user. Add routes/profile.js:

const express = require('express');
const auth = require('../middleware/auth');
const User = require('../models/user');

const router = express.Router();

router.get('/me', auth, async (req, res) => {
  try {
    const user = await User.findById(req.user.id).select('-password');
    if (!user) {
      return res.status(404).json({ message: 'User not found' });
    }
    res.json({ user });
  } catch (err) {
    res.status(500).json({ message: 'Server error' });
  }
});

module.exports = router;

Wire it in server.js:

const profileRoutes = require('./routes/profile');
app.use('/api/profile', profileRoutes);

Now a GET /api/profile/me call will only work with a valid token.

3. Handle Token Expiry Clearly

Short access tokens reduce damage if they leak. We set expiresIn: '15m' during login. When a token expires, the middleware returns a 401 with Access token expired.

We won’t refresh the token here because refresh requires its own endpoint, storage, and rotation rules. You’ll add that in “Refresh Tokens and Rotation.” For now, the 401 proves that the expiry is enforced.

4. Testing the Flow

In this section, we’ll test that the server blocks requests without a valid token and allows requests with a valid token.

Log in at /api/auth/login and copy the token. Then call /api/profile/me with:

Authorization: Bearer <paste_token_here>

You should see the current user without the password field.

Then remove the header or change the token and call again. You should get a 401.

Next, wait for the token to expire or change expiresIn to a very short value for a quick test. Call again and confirm you get Access token expired.

Tips for debugging

• 401 with “Missing or invalid Authorization header” means the header format is wrong. Use Authorization: Bearer <token>.

• 401 with “Invalid token” means the token string is wrong, signed with the wrong secret, or corrupted.

• 401 with “Access token expired” means the expiry check works. You will fix the client experience with the refresh endpoint later.

• If all calls fail, confirm your JWT_SECRET is set in .env and that the server was restarted after changes.

5. Optional Cookie Support

You can store tokens in HTTP-only cookies. The browser sends them automatically. Scripts cannot read HTTP-only cookies, which reduces the risk from XSS.

Install and enable cookies:

npm install cookie-parser

// server.js
const cookieParser = require('cookie-parser');
app.use(cookieParser());

Read the access token from a cookie as a fallback:

// middleware/auth.js
const jwt = require('jsonwebtoken');

function auth(req, res, next) {
  const header = req.headers.authorization || '';
  const [scheme, tokenFromHeader] = header.split(' ');
  const tokenFromCookie = req.cookies?.access_token;

  const token = scheme === 'Bearer' && tokenFromHeader ? tokenFromHeader : tokenFromCookie;

  if (!token) return res.status(401).json({ message: 'No token provided' });

  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    req.user = { id: decoded.id, email: decoded.email };
    next();
  } catch (err) {
    const msg = err.name === 'TokenExpiredError' ? 'Access token expired' : 'Invalid token';
    return res.status(401).json({ message: msg });
  }
}

module.exports = auth;

How this works:

• The access token can live in a cookie named access_token.

• Mark the cookie as httpOnly and secure in production.

• Set sameSite: 'strict' to reduce CSRF risk.

• For APIs used by browsers, cookies simplify sending tokens. For SPAs that call many domains, an Authorization header may be simpler.

In the next section, we’ll use the same cookie approach for the refresh token. That section explains why refresh belongs in a cookie and how rotation blocks replay.

Refresh Tokens and Rotation

Access tokens are short-lived and used on every request. They prove the user identity quickly. Refresh tokens live longer and are used only to get new access tokens when the old ones expire. This split keeps day-to-day requests fast and limits the damage if a token leaks.

We will store the refresh token in an HTTP-only cookie. This reduces exposure to scripts and keeps the flow smooth.

1. Install and Setup

We already have cookie-parser. We won’t add anything new for now, but we will use Node’s built-in crypto module to hash the refresh token before storing it. As a reminder, hashing means the raw token is never saved. If the database leaks, attackers cannot use the hashes to log in.

Create models/refreshToken.js:

const mongoose = require('mongoose');

const refreshTokenSchema = new mongoose.Schema({
  user: { type: mongoose.Schema.Types.ObjectId, ref: 'User', index: true },
  tokenHash: { type: String, required: true, unique: true },
  jti: { type: String, required: true, index: true },
  expiresAt: { type: Date, required: true, index: true },
  revokedAt: { type: Date, default: null },
  replacedBy: { type: String, default: null }, // new jti when rotated
  createdAt: { type: Date, default: Date.now },
  ip: String,
  userAgent: String
});

module.exports = mongoose.model('RefreshToken', refreshTokenSchema);

2. Token Helpers

Create utils/tokens.js for clean, reusable logic.

const jwt = require('jsonwebtoken');
const crypto = require('crypto');
const RefreshToken = require('../models/refreshToken');

const ACCESS_TTL = '15m';
const REFRESH_TTL_SEC = 60 * 60 * 24 * 7; // 7 days

function hashToken(token) {
  return crypto.createHash('sha256').update(token).digest('hex');
}

function createJti() {
  return crypto.randomBytes(16).toString('hex');
}

function signAccessToken(user) {
  const payload = { id: user._id.toString(), email: user.email };
  return jwt.sign(payload, process.env.JWT_SECRET, { expiresIn: ACCESS_TTL });
}

function signRefreshToken(user, jti) {
  const payload = { id: user._id.toString(), jti };
  const token = jwt.sign(payload, process.env.REFRESH_TOKEN_SECRET, { expiresIn: REFRESH_TTL_SEC });
  return token;
}

async function persistRefreshToken({ user, refreshToken, jti, ip, userAgent }) {
  const tokenHash = hashToken(refreshToken);
  const expiresAt = new Date(Date.now() + REFRESH_TTL_SEC * 1000);
  await RefreshToken.create({ user: user._id, tokenHash, jti, expiresAt, ip, userAgent });
}

function setRefreshCookie(res, refreshToken) {
  const isProd = process.env.NODE_ENV === 'production';
  res.cookie('refresh_token', refreshToken, {
    httpOnly: true,
    secure: isProd,
    sameSite: 'strict',
    path: '/api/auth/refresh',
    maxAge: REFRESH_TTL_SEC * 1000
  });
}

async function rotateRefreshToken(oldDoc, user, req, res) {
  // revoke old
  oldDoc.revokedAt = new Date();
  const newJti = createJti();
  oldDoc.replacedBy = newJti;
  await oldDoc.save();

  // issue new
  const newAccess = signAccessToken(user);
  const newRefresh = signRefreshToken(user, newJti);
  await persistRefreshToken({
    user,
    refreshToken: newRefresh,
    jti: newJti,
    ip: req.ip,
    userAgent: req.headers['user-agent'] || ''
  });
  setRefreshCookie(res, newRefresh);
  return { accessToken: newAccess };
}

module.exports = {
  hashToken,
  createJti,
  signAccessToken,
  signRefreshToken,
  persistRefreshToken,
  setRefreshCookie,
  rotateRefreshToken
};

In this code,

• signAccessToken creates a short token with the user ID and email.

• signRefreshToken creates a long-lived token with a jti value. The jti lets us rotate and track tokens.

• persistRefreshToken hashes the refresh token and stores metadata like expiry and device info.

• setRefreshCookie writes the HTTP-only cookie so the browser sends it to the refresh endpoint automatically.

• rotateRefreshToken revokes the old token, issues a new pair, and saves the new record. Rotation blocks replay if an old refresh token is stolen.

3. Issue Refresh Token on Login

Update your routes/auth.js login handler to create and store a refresh token, then set the cookie.

const express = require('express');
const bcrypt = require('bcryptjs');
const jwt = require('jsonwebtoken');
const User = require('../models/user');
const RefreshToken = require('../models/refreshToken');
const {
  createJti,
  signAccessToken,
  signRefreshToken,
  persistRefreshToken,
  setRefreshCookie
} = require('../utils/tokens');

const router = express.Router();

router.post('/login', async (req, res) => {
  try {
    const { email, password } = req.body;

    const user = await User.findOne({ email });
    if (!user) return res.status(400).json({ message: 'Invalid credentials' });

    const isMatch = await bcrypt.compare(password, user.password);
    if (!isMatch) return res.status(400).json({ message: 'Invalid credentials' });

    const accessToken = signAccessToken(user);

    const jti = createJti();
    const refreshToken = signRefreshToken(user, jti);

    await persistRefreshToken({
      user,
      refreshToken,
      jti,
      ip: req.ip,
      userAgent: req.headers['user-agent'] || ''
    });

    setRefreshCookie(res, refreshToken);

    res.json({ accessToken });
  } catch (err) {
    res.status(500).json({ message: 'Server error' });
  }
});

module.exports = router;

On login, we issue both tokens. The access token goes to the JSON response. The refresh token goes to an HTTP-only cookie scoped to /api/auth/refresh. This keeps the refresh token away from frontend code while still letting the browser send it to the refresh endpoint.

4. The Refresh Endpoint

Create an endpoint that reads the refresh cookie, verifies it, checks the database entry, and rotates it. If all checks pass, it returns a new access token and sets a new refresh cookie.

Add to routes/auth.js:

const { hashToken, rotateRefreshToken } = require('../utils/tokens');

router.post('/refresh', async (req, res) => {
  try {
    const token = req.cookies?.refresh_token;
    if (!token) return res.status(401).json({ message: 'No refresh token' });

    let decoded;
    try {
      decoded = jwt.verify(token, process.env.REFRESH_TOKEN_SECRET);
    } catch (err) {
      return res.status(401).json({ message: 'Invalid or expired refresh token' });
    }

    const tokenHash = hashToken(token);
    const doc = await RefreshToken.findOne({ tokenHash, jti: decoded.jti }).populate('user');

    if (!doc) {
      return res.status(401).json({ message: 'Refresh token not recognized' });
    }
    if (doc.revokedAt) {
      return res.status(401).json({ message: 'Refresh token revoked' });
    }
    if (doc.expiresAt < new Date()) {
      return res.status(401).json({ message: 'Refresh token expired' });
    }

    const result = await rotateRefreshToken(doc, doc.user, req, res);
    return res.json({ accessToken: result.accessToken });
  } catch (err) {
    res.status(500).json({ message: 'Server error' });
  }
});

The refresh endpoint verifies the cookie, checks the database record, confirms it is not expired or revoked, then rotates it. Rotation sets revokedAt on the old record and creates a new one with a fresh jti. The response returns a new access token and sets a new refresh cookie.

5. Logout and Revoke

On logout, revoke the current refresh token and clear the cookie.

router.post('/logout', async (req, res) => {
  try {
    const token = req.cookies?.refresh_token;
    if (token) {
      const tokenHash = hashToken(token);
      const doc = await RefreshToken.findOne({ tokenHash });
      if (doc && !doc.revokedAt) {
        doc.revokedAt = new Date();
        await doc.save();
      }
    }
    res.clearCookie('refresh_token', { path: '/api/auth/refresh' });
    res.json({ message: 'Logged out' });
  } catch (err) {
    res.status(500).json({ message: 'Server error' });
  }
});

Logout revokes the matching refresh token if present and clears the cookie. This ends the session cleanly on the server side and the client side.

6. Client Flow

Here is how the browser app should behave:

• Keep the access token in memory. Do not put it in localStorage.

• Call protected APIs with the Authorization header or let cookies handle it if you chose the cookie approach for access.

• If a call fails with Access token expired, call /api/auth/refresh. The browser sends the refresh cookie automatically.

• Replace the in-memory access token with the new one.

• Retry the original request.

• On logout, call /api/auth/logout and clear any local state.

7. Security Notes

There are some key steps you can take to make sure everything is secure:

Separate secrets

Use a different secret for access and refresh tokens. If the access secret leaks, refresh tokens still use a different key. Set JWT_SECRET and REFRESH_TOKEN_SECRET in .env.

HTTPS only

Serve production traffic over HTTPS. Cookies marked secure: true only travel over HTTPS. This protects tokens in transit.

Rotate on every refresh

Issue a new refresh token and revoke the old one each time you refresh. Rotation makes a stolen old token useless after the next refresh.

Hash refresh tokens in the database

Store a SHA-256 hash, not the raw token. This way a database leak does not give attackers the actual token string.

Scope and flags for cookies

Use httpOnly: true, secure: true in production, sameSite: 'strict', and a narrow path such as /api/auth/refresh. These flags reduce XSS and CSRF risk and limit where the cookie is sent.

Short access TTL and moderate refresh TTL

Keep access tokens short, such as 15 minutes. Use a refresh lifetime like 7 days. This keeps risk low without annoying users.

Device awareness

Store ip and userAgent. If patterns change in a suspicious way, you can revoke or challenge the session.

Auditing and limits

Log refresh events and consider rate limits on the refresh endpoint. This helps detect abuse.’

Add to .env:

REFRESH_TOKEN_SECRET=your_refresh_secret_key

Conclusion

You now have a working authentication system that uses JWTs and refresh tokens to keep users logged in safely. The access token handles quick verification. The refresh token quietly renews access when it expires. Together, they strike a balance between security and convenience.

You built user registration, login, protected routes, and a full refresh flow. You also learned how to rotate refresh tokens, store them securely, and handle logout cleanly. Each step adds another layer of safety that keeps your app and users protected.

From here, you can expand this setup to match your real project. You can add role-based permissions, track user sessions by device, or move the logic into a dedicated authentication service. What matters most is understanding the flow and keeping tokens short-lived and well-guarded.

At its core, a JWT is a JSON-based open standard format that allows you to represent specific claims securely between two parties. The exciting part is how widely JWT is used, especially in microservice architectures and modern authentication systems.

In this article, we’ll break down what JWTs really are, explore their structure, and see exactly how they help secure web applications. By the end, you’ll understand why developers rely on JWTs every single day.

Here’s What We’ll Cover

1. Prerequisites

2. What is a JWT?

3. Why Do We Need Tokens?

   • Session Tokens: The Classic Approach

   • JWT: The Modern Solution

4. JWT Structure: Header, Payload & Signature

5. Example: Decoding a JWT

6. How JWTs Ensure Security: The Signature

7. Security Considerations and Token Management

8. How to Create JWTs in Different Languages

9. Practical Implementation: JWT Authentication with Express + MongoDB

   • 1. Project Setup & Dependencies

   • 2. Project Folder Structure

   • 3. Step-by-Step Implementation

   • 4. How to Test Your API

10. Summary

11. Final Words

Prerequisites

To follow along and get the most out of this guide, you should have:

1. Basic familiarity with JavaScript / Node.js

2. Node.js and npm installed on your local machine

3. Basic understanding of HTTP and REST APIs

4. Understanding of JSON and how to parse/serialize it

5. Basic knowledge of Express (or ability to follow along)

6. A running instance of MongoDB (local or remote)

7. Experience with asynchronous code / Promises / async-await

8. Familiarity with environment variables / .env setup

I’ve also created a video to go along with this article. If you’re the type who likes to learn from video as well as text, you can check it out here:

What is a JWT?

JWTs are most commonly used for authentication today, but that wasn’t actually their original purpose. They were created to provide a standard way for two parties to securely exchange information. In fact, there’s even an industry standard specification (RFC 7519) that lays out exactly how JWTs should be structured and how they’re meant to be used for data exchange. Think of it like ECMAScript, or ES, which defines the standard for JavaScript.

In real-world applications, JWTs are primarily used for authentication, and that’s the angle we’ll focus on in this article.

But remember that JWTs weren’t designed only for authentication. There are other ways to handle authentication too, and one of the most popular alternatives is session tokens.

Why Do We Need Tokens?

Whatever authentication strategy we use, whether it’s a session token or a JWT, the underlying reason is the same: the stateless nature of the HTTP protocol.

When we exchange requests and responses from a browser to a server or between servers using HTTP, the protocol itself does not retain any information.

Stateless means that during interactions between the client and the server, HTTP doesn’t remember any previous requests or data. In other words, every request must carry all the necessary information separately. HTTP doesn’t store any data on its own. Once it receives information, it forgets it. That’s why we say HTTP is stateless, as it has no inherent state or persistent information.

Think of it this way: when we access a webpage from a server, what information do we actually send to the server? If it’s a simple static website, we don’t need to send much. We just send the URL of the page to the server, and the server responds by delivering the corresponding HTML page. This means the server doesn’t need to remember any information or maintain any state, which is exactly how HTTP is designed to work, because HTTP itself is stateless.

But if the web application provides different responses for each user – in other words, if the website is dynamic – then sending only the URL is not sufficient. The user must also send their identity along with the URL to the server.

For example, if a user wants to access page-1, they must tell the server: “I am User A, please give me page-1.” The server will then respond with page-1 accordingly. But next time, if the user requests, “Now give me page-2”, what will the server do? Since HTTP is stateless, if the request doesn’t include the user’s identity, the server won’t know which response to provide. This means that with every request, the user must provide their identity, right?

But if we look at the websites around us, do we really have to provide our identity every single time? Take Facebook as an example. Once we authenticate and log in, the server shows us the homepage when we request it, or our profile page when we request that, without requiring us to authenticate with every single request.

So the question is, if HTTP is stateless, how is this possible? How does the web application remember our browsing session? The answer is that, web applications can maintain sessions in different ways, and one of the most common methods is by using tokens.

Session Tokens: The Classic Approach

There are two popular options for this. One is a Session Token, and the other is a JSON Web Token (JWT). Let’s understand both so that it becomes clear what JWTs are and why they’re used.

Imagine a scenario in a company’s customer care department. A customer calls in with a complaint. The customer support representative listens to the issue and tries various troubleshooting steps but is unable to resolve the problem.

At this point, they forward the case to their higher management team and create a case file for the customer. This file contains all conversations with the customer and details of the troubleshooting attempts. The customer is then given a case ID or ticket ID, so that the next time they call, they don’t have to go through the same steps all over again.

The next day, when the customer calls again, they give their ticket ID to the customer care representative. The representative searches the system using that ticket ID, retrieves the details, and is able to respond accurately to the customer.

This scenario illustrates how authentication works in a web application using a session token. When a user authenticates, the server creates a session and keeps track of it. A session ID is generated for that session and sent back to the user, similar to the support ticket in the earlier example. From then on, whenever the user sends a request to the server, they include this session ID or token. The server looks up the session using that ID and identifies the client. Since the server has to handle multiple clients, this session token method has become an effective and widely used strategy for authentication.

And how the client sends the session ID to the server can vary depending on the implementation. The most common method is to store the session ID in the browser’s cookies. The advantage of this approach is that whenever the browser sends a request to the same server, it automatically adds the cookie information to the request header. This is a built-in behaviour of browsers, so no extra steps are needed.

When the user authenticates, the server saves data in the browser’s cookie, and from then on, that cookie information is sent automatically with every request, allowing the server to recognize the user. This was a very popular method, although in modern applications it has become a bit outdated.

But this mechanism has some issues. The biggest problem is that it assumes there is only a single server. In modern web applications, there are usually multiple servers. In such cases, a load balancer sits in front and decides which server will handle the user’s request.

Let’s say the session token method is being used. When the user sends the first request, the load balancer forwards it to Server-1. Server-1 creates a session ID and sends it back to the client. Later, when the user sends another request, the load balancer routes it to Server-2. But Server-2 doesn’t have that session ID stored, so how will it know which user the request belongs to?

The common solution to this is to store session IDs not on a specific server but in a shared Redis database, so that any server can verify the session ID from there. This is what’s called a Redis cache. But in a microservice architecture, this approach has a weakness. If for some reason the Redis cache goes down, the servers may still be running, but the authentication mechanism will fail. This is exactly where JSON Web Tokens come in, offering a slightly different approach.

JWT: The Modern Solution

Let’s revisit the customer care department example. This time, imagine there’s no phone or system. The customer comes directly to the office and meets the support agent in person. Since the agent doesn’t have any system this time, they can’t store all the information like before. Instead, they write everything down on a piece of paper and tell the customer, “Next time you come, bring this with you.”

This means the method is a bit different from the previous concept, right? But there’s still a problem: “validity”. If the customer isn’t legitimate and acts maliciously, how can the support representative trust them? The next day, if the customer comes in with the same information written on a blank sheet of paper, how can the agent verify the validity of their identity?

In this case, a possible solution is for the customer care executive to sign the paper when giving it to the customer. Then, when the customer brings the paper back, the support representative can verify the signature and confidently provide the service.

JSON Web Tokens work in a similar way. Here, when the client authenticates, instead of the server saving all the information, it sends all the user’s information as a JSON token along with a signature. Later, with each subsequent request, the client sends the entire token along with the request, which contains information like which user it is, their name, and other necessary details.

In this case, the server doesn’t save anything, and all the information stays with the client. Each time the client sends a request with this token, the server can read it, identify which user made the request, and provide the necessary data.

This token is not just a simple ID. It’s a JSON object containing all the information, and this is what we call a JSON Web Token. How the client stores this JWT is entirely up to the client. The most common methods are storing it in the browser’s cookies or local storage.

JWT Structure: Header, Payload, & Signature

As mentioned, the server receives a JSON object, but a JWT doesn’t look like a regular JSON.

In the image above, it may seem a bit unusual. In fact, it’s an encoded version of the JSON object, a kind of scrambled or compact representation. If you look closely, you’ll see that a JWT is divided into three parts, separated by dots. The first part is the header, the second part is the JSON payload, which essentially holds our data, and the third part is the signature.

If we examine each part individually:

• The header is a separate JSON object.

• The payload is also a separate JSON object containing our data.

• The third part is the signature.

But what does the signature mean here? Simply put, the signature is a hash value. Our data is hashed using a secret key to create the signature. This secret key is kept on the server. So, when this JSON Web Token is sent to the server, the server can use that secret key to verify the signature. This ensures that the token is valid and has not been tampered with.

Example: Decoding a JWT

Let’s look at an example. The best website for working with JWTs and understanding their structure is jwt.io. If you paste a JWT into the site, three sections appear: the header, payload, and signature. The payload is shown in the “Decoded Payload” section, which contains content and data. You’ll see there’s an ID, a JSON object with a name, and an expiration time.

The header is also a completely valid JSON object, which specifies an algorithm and shows the type –essentially indicating which algorithm will be used to create or verify this JWT.

So, the main data is in the “Decoded Payload” section, and the third part is the signature. Now there’s an important point to note: you might wonder where this scrambled-looking token comes from. It’s actually very simple. The data in the “Decoded Payload” is Base64 encoded, and that’s what forms the appearance of this scrambled token.

If you copy this part of the JWT and paste it into any online Base64 decoder, you’ll immediately see the data.

What does this mean? It means that if this data is encoded again using Base64, the same token will be generated. The header works the same way as well.

And the final point: the scrambled or encoded part. Is it done for security? No, it’s not for security. It’s done purely for convenience. JSON objects can be quite large, and not all programming languages handle them in the same way. In JavaScript it’s easy, but in other languages, it can sometimes cause issues. So to make it easier to handle, the data is Base64 encoded. This is not for security, as encoding it like this doesn’t make the data secure, because the information can still be viewed publicly.

As you can see in the diagram above, the moment you enter it on this site, your data is immediately visible. This means that no sensitive information should be stored here, only user identification details, like a user ID or other public information. Passwords or any secret keys should never be stored in the token, because they can be easily read. Even though it looks scrambled or encoded, it is actually public.

How JWTs Ensure Security: The Signature

Now let’s move to the security part, which is ensured by the signature. In our earlier paper example, a person could simply add a signature by hand.

But for data, the process of creating a signature is different. For data, the signature is created cryptographically using a secret key, which is the actual signature. The process of creating the signature is as follows:

1. The data is Base64 encoded.

2. It is concatenated with the secret key.

3. It is encoded again in Base64.

The configuration specifies an algorithm. This algorithm can be changed, but the same algorithm used to create the token must be used to verify it. In other words, the algorithm for generating and verifying the token must always be the same.

Finally, the data is hashed using a secret key. This secret key is not available to the public. Instead, it’s kept only on the server, usually stored securely in a server vault. When this JWT reaches the server, the server uses the secret key to verify whether the token is valid. If it doesn’t match correctly, it will display “invalid signature.” This ensures that the server can confirm whether the token has been tampered with and that its integrity is intact.

For example, if you use love-you-all-from-logicbaselabs as the signature, and the server verifies it, it will show “signature verified”. This demonstrates that the secret key exists only on the server. This ensures that even though public information is displayed, the token’s validity can be confirmed.

JSON Web Tokens aren’t like a password, though. They primarily serve to identify the user. The server can check the JWT to determine whether it belongs to a valid user. In other words, the JWT represents the user’s identity. It’s a very important token, containing secure content along with the signature.

Security Considerations and Token Management

One important thing to remember: if someone gets hold of your JWT, meaning they have the exact same token, they can easily log in as that user. They just need to send requests with that token to gain the necessary access.

You could think of it like this: if someone gets hold of your Facebook password, they can log in to your Facebook account. Similarly, if someone obtains your PayPal account PIN, they can easily access your account. In other words, if someone gets hold of your most secure information, there’s no way to protect it.

The same applies to JWTs: keeping the token safely on the client side is absolutely crucial. In this regard, we are somewhat vulnerable.

There is, though, one key difference. In the case of session tokens, if we assume an account has been compromised, the server can invalidate that session. In other words, no one can log in using that session ID anymore.

But with a JWT, the token remains valid until its expiration time. So there’s no direct way to invalidate it. Since the token is cryptographically self-contained and signed with the server’s secret key, once it’s created, it cannot be directly revoked by the server.

The only way to handle this is what’s done on the web: denylisting the token. In other words, the server maintains a separate database listing all JWT tokens that are denylisted. Whenever a request comes in, the server first verifies whether the token is valid. Then, through middleware, it checks whether the token is on the denylist. Only if it’s not on that list is the user allowed access.

So, these are the rules for using JSON Web Tokens. JWTs can be used in any programming language, especially in the context of REST APIs. They are extremely popular and widely used in microservice architectures.

How to Create JWTs in Different Languages

How you create a JWT depends on the programming language you’re using. For example, in Node.js, there are specialized libraries available, like jsonwebtoken, so it’s straightforward. And in PHP, there are easy-to-use options for creating JWTs as well. So, JWTs are a universal tool, not limited to any specific programming language. Many people think they’re only for JavaScript, but that’s not true.

And remember that JWTs aren’t just used for authentication purposes. You can use them to represent any kind of identity. For example, if you’re going to a concert, access could be granted using a JWT instead of a regular ticket. When your client uses that JWT, the gateway or server can read the token, provide access to the information, and verify it using the signature.

Practical Implementation: JWT Authentication with Express + MongoDB

In this section, we will put into practice all the concepts we have learned so far. Using Express.js and MongoDB, we will build a complete JWT authentication system step by step.

Don’t worry if it feels overwhelming at first. We will go carefully, one step at a time, and by the end, you will have a fully working project. Think of it as entering a building floor by floor: we’ll explore each section thoroughly and come out with a solid understanding.

1. Project Setup & Dependencies

Before writing any code, we need to set up our Node.js project and install the required dependencies.

Initialize the Node.js Project

Open your terminal and run:

mkdir jwt-auth-demo
cd jwt-auth-demo
npm init -y

This will create a package.json file with default settings.

Install Dependencies

We need some packages to build our JWT authentication system:

npm install express mongoose bcryptjs jsonwebtoken dotenv

• express: Fast and minimal Node.js web framework to create API routes.

• mongoose: ODM (Object Data Modeling) library to interact with MongoDB easily.

• bcryptjs: Library to hash and compare passwords securely.

• jsonwebtoken: Library to generate and verify JWT tokens.

• dotenv: Loads environment variables from a .env file to keep secrets secure.

Install Dev Dependencies (Optional)

For development convenience, install nodemon to auto-restart the server on file changes:

npm install --save-dev nodemon

Update package.json scripts:

"scripts": {
  "start": "node server.js",
  "dev": "nodemon server.js"
}

• npm start runs the server normally.

• npm run dev runs the server with auto-restart using nodemon.

2. Project Folder Structure

jwt-auth-demo/
│
├── config/
│   └── db.js
│
├── controllers/
│   └── authController.js
│
├── middlewares/
│   └── authMiddleware.js
│
├── models/
│   └── User.js
│
├── routes/
│   └── auth.js
│
├── services/
│   ├── hashService.js
│   └── jwtService.js
│
├── .env
├── server.js
├── package.json

What goes where?

• config/: Database connection and environment config.

• controllers/: Main logic for each endpoint.

• middlewares/: Functions that run before controllers (for example, auth checks).

• models/: Mongoose schemas.

• routes/: API endpoint definitions.

• services/: Reusable logic (hashing, JWT).

• .env: Secrets and config variables.

• server.js: Entry point of the app.

3. Step-by-Step Implementation

Initialize the Express Server

Before doing anything complex, we need to set up a simple server using Express. Think of this as the heart of our application. This server will be responsible for listening to incoming requests (like user login or register) and sending back responses.

File: server.js

// server.js

// Import the express library to build our server
const express = require("express");

// Create an instance of express
const app = express();

// Middleware to parse JSON request bodies (important for APIs)
app.use(express.json());

// Default route to test server
app.get("/", (req, res) => {
  res.send("Hello World! Your server is working 🚀");
});

// Start the server on port 5000
const PORT = process.env.PORT || 5000;
app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
});

• We import Express and create an app instance.

• We use middleware to parse JSON requests (important for APIs).

• We define a simple route / to test if our server works.

• We start the server on port 5000 and log a message when it's running.

Now, let’s test it:

• Run node server.js or npm run dev.

• Open your browser at http://localhost:5000.

• You should see: Hello World! Your server is working 🚀

Connect MongoDB with Mongoose

In this step, we want to store users in a database. For that, we will use MongoDB. To interact with MongoDB in Node.js easily, we use Mongoose, which is an ODM library.

File: config/db.js

// config/db.js

// Import mongoose
const mongoose = require("mongoose");

// Connect to MongoDB using environment variable
const connectDB = async () => {
  try {
    await mongoose.connect(process.env.MONGO_URI, {
      useNewUrlParser: true,
      useUnifiedTopology: true,
    });
    console.log("✅ MongoDB Connected");
  } catch (err) {
    console.error("❌ MongoDB Connection Error:", err.message);
    process.exit(1); // Stop server if DB fails
  }
};

module.exports = connectDB;

Now our server is connected to MongoDB. Whenever we insert, update, or query data, it will go into this database.

File: .env

PORT=5000
MONGO_URI=mongodb://127.0.0.1:27017/jwt-auth-demo
JWT_SECRET=your_super_secret_key

The .env file stores sensitive information like your database URI, JWT secret, and server port. By using environment variables, you can keep secrets out of your code and easily change configuration without modifying your source files. Never commit .env to public repositories to protect your credentials.

Create User Model

In this step, we need to define how a User looks in our database. Each user will have a name, email, and password.

File: models/User.js

// models/User.js
const mongoose = require("mongoose");

// Define a schema (blueprint of user data)
const userSchema = new mongoose.Schema({
  name: { type: String, required: true },
  email: { type: String, required: true, unique: true },
  password: { type: String, required: true },
});

// Create and export the model
module.exports = mongoose.model("User", userSchema);

As you can see, each user now has a name, email, and hashed password. This ensures that every user we save has these three fields.

Hashing & JWT Services

In this step, we will handle password hashing and JWT management using separate services. This keeps our code organized and reusable.

File: services/hashService.js

//services/hashService.js

const bcrypt = require("bcryptjs");

// Function to hash a plain password
exports.hashPassword = async (plainPassword) => {
  // bcrypt.hash generates a hashed version of the password
  // The number 10 is the salt rounds, which affects the hashing complexity
  return await bcrypt.hash(plainPassword, 10);
};

// Function to compare a plain password with a hashed password
exports.comparePassword = async (plainPassword, hashedPassword) => {
  // bcrypt.compare checks if the plain password matches the hashed one
  return await bcrypt.compare(plainPassword, hashedPassword);
};

• hashPassword(plainPassword): Takes a plain text password and returns a hashed version using bcrypt. Never store plain passwords directly.

• comparePassword(plainPassword, hashedPassword): Compares a user-entered password with the hashed password stored in the database. Returns true if they match.

File: services/jwtService.js

// services/jwtService.js

const jwt = require("jsonwebtoken");

// Function to generate a JWT
exports.generateToken = (payload) => {
  // jwt.sign creates a signed token using our secret key from environment variables
  // expiresIn defines how long the token is valid (1 hour here)
  return jwt.sign(payload, process.env.JWT_SECRET, { expiresIn: "1h" });
};

// Function to verify a JWT
exports.verifyToken = (token) => {
  // jwt.verify checks if the token is valid and not expired
  return jwt.verify(token, process.env.JWT_SECRET);
};

• generateToken(payload): Generates a JWT for a user. The payload typically contains user ID and email.

• verifyToken(token): Verifies that the JWT is valid and returns the decoded payload if successful.

• Using a separate JWT service keeps token logic centralized and easy to manage.

Auth Controller

In this step, we will handle all authentication-related logic in a separate controller. This keeps routes clean and separates business logic from endpoint definitions.

File: controllers/authController.js

// controllers/authController.js

const User = require("../models/User");
const { hashPassword, comparePassword } = require("../services/hashService");
const { generateToken } = require("../services/jwtService");

// Register new user
exports.register = async (req, res) => {
  try {
    const { name, email, password } = req.body; // Get user input

    // Step 1: Check if user already exists
    const existingUser = await User.findOne({ email });
    if (existingUser)
      return res.status(400).json({ message: "User already exists!" });

    // Step 2: Hash password using hashService
    const hashedPassword = await hashPassword(password);

    // Step 3: Save user to database
    const user = new User({ name, email, password: hashedPassword });
    await user.save();

    // Step 4: Send success response
    res.status(201).json({ message: "User registered successfully!" });
  } catch (err) {
    // Handle errors gracefully
    res.status(500).json({ error: err.message });
  }
};

// Login user
exports.login = async (req, res) => {
  try {
    const { email, password } = req.body; // Get user input

    // Step 1: Find user by email
    const user = await User.findOne({ email });
    if (!user)
      return res.status(400).json({ message: "Invalid email or password" });

    // Step 2: Compare provided password with hashed password
    const isMatch = await comparePassword(password, user.password);
    if (!isMatch)
      return res.status(400).json({ message: "Invalid email or password" });

    // Step 3: Generate JWT using jwtService
    const token = generateToken({ id: user._id, email: user.email });

    // Step 4: Send success response with token
    res.json({ message: "Login successful!", token });
  } catch (err) {
    res.status(500).json({ error: err.message });
  }
};

// Protected profile route
exports.profile = (req, res) => {
  // req.user is set by auth middleware after token verification
  res.json({
    message: "Welcome to your profile!",
    user: req.user,
  });
};

• File: controllers/authController.js – Contains all logic related to authentication.

• exports.register handles user registration:

  • Checks if the user exists.

  • Hashes the password using hashService.

  • Saves the new user to MongoDB.

  • Returns a success message.

• exports.login handles user login:

  • Finds the user by email.

  • Compares passwords using hashService.comparePassword.

  • Generates a JWT token if valid.

  • Returns the token in the response.

• exports.profile handles protected profile route:

  • Returns user information from req.user, which is set by the auth middleware.

• Using a controller keeps route definitions clean and separates business logic from endpoint handling.

Auth Middleware

In this step, we create a middleware to protect routes by verifying JWTs. Only authenticated users can access protected endpoints.

File: middlewares/authMiddleware.js

// middlewares/authMiddleware.js

const { verifyToken } = require("../services/jwtService");

// Middleware to protect routes
module.exports = (req, res, next) => {
  // Step 1: Get Authorization header
  const authHeader = req.headers["authorization"];
  if (!authHeader)
    return res.status(401).json({ message: "No token provided" });

  // Step 2: Extract token from format 'Bearer <token>'
  const token = authHeader.split(" ")[1];
  if (!token) return res.status(401).json({ message: "Malformed token" });

  try {
    // Step 3: Verify token using jwtService
    const decoded = verifyToken(token);

    // Step 4: Attach decoded user info to request object
    req.user = decoded;

    // Proceed to next middleware or route handler
    next();
  } catch (err) {
    // If token is invalid or expired
    res.status(401).json({ message: "Invalid or expired token" });
  }
};

• File: middlewares/authMiddleware.js – Middleware for protecting routes.

• Step 1: Checks if the Authorization header is present.

• Step 2: Extracts the token from the Bearer <token> format.

• Step 3: Verifies the token using jwtService.verifyToken.

• Step 4: Attaches the decoded user info to req.user for use in subsequent route handlers.

• If the token is missing, malformed, invalid, or expired, the middleware responds with 401 Unauthorized. This ensures only authenticated users can access protected routes.

Auth Routes

In this step, we will define authentication-related routes and connect them with the controller and middleware.

File: routes/auth.js

// routes/auth.js

const express = require("express");
const router = express.Router();
const authController = require("../controllers/authController");
const authMiddleware = require("../middlewares/authMiddleware");

// Step 1: Register route
// Users send their name, email, and password to this endpoint
router.post("/register", authController.register);

// Step 2: Login route
// Users send email and password to receive JWT
router.post("/login", authController.login);

// Step 3: Protected profile route
// Only accessible to authenticated users with a valid JWT
router.get("/profile", authMiddleware, authController.profile);

module.exports = router;

• File: routes/auth.js – Central file to define authentication endpoints.

• router.post("/register", authController.register): Handles user registration.

• router.post("/login", authController.login): Handles user login and token generation.

• router.get("/profile", authMiddleware, authController.profile): Protected route, requires JWT. The authMiddleware ensures only authenticated users can access it.

• Using routes with controllers and middleware keeps the application organized and professional.

Main Server File

This is the main entry point of our application. It sets up the server, connects to the database, and mounts all routes.

File: server.js

// server.js

require("dotenv").config(); // Step 1: Load environment variables from .env
const express = require("express");
const connectDB = require("./config/db");

const app = express();

// Step 2: Connect to MongoDB
connectDB();

// Step 3: Middleware to parse JSON request bodies
app.use(express.json());

// Step 4: Mount auth routes
// All auth-related routes will start with /api/auth
app.use("/api/auth", require("./routes/auth"));

// Step 5: Default route to test server
app.get("/", (req, res) => {
  res.send("Hello World! Your server is working 🚀");
});

// Step 6: Start server on PORT from .env or default 5000
const PORT = process.env.PORT || 5000;
app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
});

• Load environment variables: Using dotenv to keep secrets and configuration separate from code.

• Connect to MongoDB: Calls connectDB() from config/db.js.

• Middleware: express.json() allows Express to parse JSON request bodies.

• Mount routes: app.use("/api/auth", ...) registers all authentication routes.

• Default route: A simple GET endpoint to verify server is running.

• Start server: app.listen starts listening on the configured port.

4. How to Test Your API

In this section, you’ll learn how to test your JWT authentication API using tools like Postman or any HTTP client.

Before testing, make sure your server is running. If it’s not running, open a terminal and run:

npm run dev

or

node server.js

This will start your server on the port defined in .env (default 5000).

Make sure your MongoDB is running. If using local MongoDB, start it with:

mongod

or ensure your MongoDB service is active.

Always check the terminal for any errors. If the server or database fails to start, your API requests will not work.

Register a User

Request:

POST http://localhost:5000/api/auth/register
Content-Type: application/json

{
  "name": "sumit",
  "email": "sumit@example.com",
  "password": "mypassword"
}

Response:

{
  "message": "User registered successfully!"
}

This sends a POST request to http://localhost:5000/api/auth/register with user details. If successful, you get a confirmation message.

Login

Request:

POST http://localhost:5000/api/auth/login
Content-Type: application/json

{
  "email": "sumit@example.com",
  "password": "mypassword"
}

Response:

{
  "message": "Login successful!",
  "token": "<JWT_TOKEN>"
}

This sends a POST request to http://localhost:5000/api/auth/login with email and password. If the credentials are correct, you receive a JWT to access protected routes.

Access Protected Route

Request:

GET http://localhost:5000/api/auth/profile
Authorization: Bearer <JWT_TOKEN>

Response:

{
  "message": "Welcome to your profile!",
  "user": {
    "id": "...",
    "email": "sumit@example.com",
    "iat": ...,
    "exp": ...
  }
}

This sends the JWT in the Authorization header using the Bearer scheme.

• Only valid tokens will allow access to this protected route.

• iat and exp indicate issued-at and expiry time of the token.

Note: Always include Authorization: Bearer <token> for protected routes.

Summary

This article gave you a comprehensive overview of JSON Web Tokens (JWTs) and their role in web authentication. It explained the stateless nature of HTTP, the need for tokens, and compares classic session tokens with JWTs.

We covered JWT structure, security mechanisms, and practical implementation using Node.js, Express, and MongoDB. We also discussed security considerations, token management, and how to test a JWT authentication API.

Here’s a Summary of the Key Points:

1. What is JWT?

   • JWT is a JSON-based open standard for securely representing claims between two parties, defined by RFC 7519.

   • Widely used for authorization in modern web applications and microservice architectures.

   • Alternative to session tokens for maintaining user state.

2. Stateless Nature of HTTP

   • HTTP does not retain information between requests, requiring each request to carry necessary data.

   • Tokens (session or JWT) are used to maintain user sessions in dynamic web applications.

3. Session Tokens

   • Classic approach where the server creates and stores a session ID, typically in cookies.

   • Works well for single-server setups but requires shared storage (for example, Redis) in multi-server environments.

   • Vulnerable if the shared cache goes down.

4. JWT: The Modern Solution

   • Server sends a signed JSON token to the client, which stores and sends it with each request.

   • No server-side storage required – all user info is in the token.

   • Signature ensures validity and integrity.

5. JWT Structure

   • Three parts: Header, Payload, Signature (separated by dots).

   • Header and payload are Base64 encoded JSON objects. Signature is a hash using a secret key.

   • Base64 encoding is for convenience, not security.

6. Decoding JWTs

   • Tools like jwt.io can decode JWTs to show header, payload, and signature.

   • Sensitive data should not be stored in JWTs, as payload is publicly readable.

7. JWT Security

   • Signature is created using a secret key and cryptographic algorithm.

   • Server verifies token integrity using the secret key.

   • JWTs identify users but do not act as passwords.

8. Security Considerations & Token Management

   • If a JWT is compromised, the attacker can impersonate the user until the token expires.

   • JWTs cannot be directly revoked; blacklisting is used to invalidate compromised tokens.

   • Session tokens can be invalidated by the server.

9. JWTs in Different Languages

   • JWTs are language-agnostic and can be implemented in Node.js, PHP, and other languages.

   • Useful for authentication and representing any kind of identity.

10. Practical Implementation: JWT Authentication with Express + MongoDB

    • Step-by-step guide to building a JWT authentication system:

      • Project setup and dependencies

      • Folder structure

      • Express server initialization

      • MongoDB connection

      • User model creation

      • Password hashing and JWT services

      • Auth controller and middleware

      • Auth routes

      • Main server file

      • API testing instructions

11. Testing the API

    • Instructions for registering users, logging in, and accessing protected routes using tools like Postman.

    • Example requests and responses provided.

12. Summary & Final Words

    • JWTs are secure, stateless, and widely used for authorization.

    • Security depends on safe token storage and proper management.

Final Words

You can find all the source code from this tutorial in this GitHub repository. If it helped you in any way, consider giving it a star to show your support!

Also, if you found the information here valuable, feel free to share it with others who might benefit from it. I’d really appreciate your thoughts – mention me on X @sumit_analyzen or on Facebook @sumit.analyzen, watch my coding tutorials, or simply connect with me on LinkedIn.

Integrating multifactor authentication capabilities into applications is crucial for strengthening their integrity. In social apps, authentication mechanisms eliminate unwanted access to personal information between two parties. Facial authentication is not entirely new, as most devices have it built-in as security measure. It offers stronger protection compared to many traditional methods, especially against risks like phishing, brute-force attacks, and account hacking.

Outline

• What to expect

• Prerequisites

• A Brief Intro to the Face API tool

• Project Setup

• Demo Project: Integrating Facial Recognition and Authentication

• Additional Information and Tips

• Conclusion

What to Expect

In this article, I’ll walk you through creating a multi-factor authentication system for a chat application powered by Stream.io, and ensuring efficient user face ID authentication to allow only authorized access to your app. I will illustrate all these with relevant code examples.

Prerequisites

Here are the necessary prerequisites to follow along with this tutorial:

• Intermediate knowledge of Node.js/Express for the backend aspect

• Knowledge of React for the frontend aspect

• Stream.io API key

Before we get started, we’ll briefly highlight the facial authentication tool of choice: Face-Api.js.

A Brief Intro to the Face API tool

Face-Api.js is a facial recognition package designed for integration with JavaScript-powered applications. It was built on top of the Tensor flow library and provides extensive facial detection based on machine learning models and abstract calculations.

In addition to all these features, it's friendly to use and can also be used locally with its predefined models. Here is a link to its documentation page, which provides relevant code examples.

It provides features such as face detection, face capture, and face match, which use the Euclidean algorithm to make precise distinctions. We'll now set it up alongside our chat application project in the next section.

Project Setup

As mentioned earlier, this is a full-stack project containing both the frontend and the backend aspects. In this section, we’ll set up both code bases before proceeding to the demo project section.

Frontend

We will power the application using the Vite framework for the frontend.

npm create vite@latest

After creating the React application, install face-api.js with this command:

npm i face-api.js

This will install the face package and the required dependencies. You can then install Stream’s powered chat SDK, which will form the main crux of the project.

npm i stream-chat stream-chat-react

After successful completion, we are finally done with the project structure scaffold. To aid ease of local testing of our frontend application, we will have to host the face models needed by the Face package locally. Here is a link to the models. Kindly copy the model's folder and paste it into the public folder in the code project. Next, we’ll set up our backend project.

Backend

The backend is built to store user details and ensure user authentication before accessing the chat application. MongoDB will be the database of choice, and we will use the Express.js library as the backend API development environment of choice. For the ease of setup, kindly clone this code-base and install it on the local PC. It comes preloaded with the necessary installation files. To further enjoy a seamless backend experience, you can utilize the MongoDB Atlas option as the database for storing user details. With that, we will now begin the code project in the next section.

Demo Project: Integrating Facial Recognition and Authentication

In this section, we will walk through setting up an authentication page on the frontend where a user can register their details, username, email, and password on the registration page. They are also obliged to take a snapshot of their face, and the face API will be called to detect a face in the image. They won't be allowed to proceed beyond this until it is successful.

Thereafter, the image faceDescriptor function is called, which generates a unique face description vector value of the user’s face based on the machine learning models provided. These values are securely stored in the MongoDB database via the Express.js backend after successfully registering. The application is coupled to a multifactor authentication system, which has both the password based authentication and the facial authentication mechanisms.

When the first hurdle (password authentication) is completed, the user is then required to take a face match, comparing it with the user's face descriptor stored from the registration page. The comparison is achieved using the Euclidean algorithmic comparison based on the threshold we provide. If it meets the threshold, the face is said to be matched, and the user gets access to the chat application; else, the user is denied access to the Stream.io-powered chat application. Relevant source code snippets highlighting these steps will be provided concurrently with images.

We’ll begin by building a defunct registration page for our chat application using React, of course. We will begin by importing and initializing the necessary packages.

import React, {useState, useRef, useEffect} from 'react';
import * as faceapi from 'face-api.js'
import {useNavigate} from 'react-router-dom'
import axios from 'axios';

const Register =()=> {

    const navigate= useNavigate("/")
    const userRef = useRef();
    const passwordRef= useRef();
    const emailRef = useRef();
    const FullRef = useRef()

In the code snippet above, we imported useful React hooks and initialized our installed Face-api.js tool. Axios will serve as our API request tool of choice for this project. The useRef hook will be used to track the user inputs. We then defined the register function and initialized the various useRef hooks for the various input fields to be inputted.

    useEffect(()=> {
const loadModels =async() => {
await faceapi.nets.tinyFaceDetector.loadFromUri('/models');
await faceapi.nets.faceLandmark68Net.loadFromUri('/models');
await faceapi.nets.faceRecognitionNet.loadFromUri('/models');
await faceapi.nets.faceExpressionNet.loadFromUri('/models');
await faceapi.nets.tinyFaceDetector.loadFromUri('/models');
setModelIsLoaded(true);
                startVideo();
}
  loadModels()  }, [])

In the code above, the useEffect hook is called to ensure that the various locally stored face-api models are initialized and active in our application. The models are stored in the models sub-folder within the public folder. Going forward, after initializing our models, we will now set up our camcorder feature on our webpage.

  const [faceDetected, setFaceDetected] = useState(false);


        // Start video feed
        const startVideo = () => {
            navigator.mediaDevices
                .getUserMedia({ video: true })
                .then((stream) => {
                    videoRef.current.srcObject = stream;
                })
                .catch((err) => console.error("Error accessing webcam: ", err));
        };
        const captureSnapshot = async () => {
            const canvas = snapshotRef.current;
            const context = canvas.getContext('2d');
            context.drawImage(videoRef.current, 0, 0, canvas.width, canvas.height);
            const dataUrl = canvas.toDataURL('image/jpeg');
            setSnapshot(dataUrl);

            // Generate the face descriptor (128-dimensional vector)
            const detection = await faceapi
                .detectSingleFace(canvas, new faceapi.TinyFaceDetectorOptions())
                .withFaceLandmarks()
                .withFaceDescriptor();

            if (detection) {
                const newDescriptor = detection.descriptor;
                setDescriptionValue(newDescriptor)
                console.log( newDescriptor);
               setSubmitDisabled(false)
                stopVid()
            } else {
                console.error("No face detected in snapshot");
            }
        };
    const stopVid =() => {

        navigator.mediaDevices
                .getUserMedia({ video: false })
                const stream = videoRef?.current?.srcObject;
        if (stream) {
            stream.getTracks().forEach(track => {track.stop()})
            videoRef.current.srcObject = null;
            setCameraActive(false)
        }
    }
        // Detect face in the video stream
        const handleVideoPlay = async () => {
            const video = videoRef.current;
            const canvas = canvasRef.current;

            const displaySize = { width: video.width, height: video.height };
            faceapi.matchDimensions(canvas, displaySize);

            setInterval(async () => {
                if (!cameraActive) return ;
                const detections = await faceapi.detectAllFaces(
                    video,
                    new faceapi.TinyFaceDetectorOptions()
                );

                const resizedDetections = faceapi.resizeResults(detections, displaySize);

                canvas.getContext('2d').clearRect(0, 0, canvas.width, canvas.height);
                faceapi.draw.drawDetections(canvas, resizedDetections);
                    const detected = detections.length > 0;
                 if (detected && !faceDetected) {
                captureSnapshot();  // Capture the snapshot as soon as a face is detected
            }

                setFaceDetected(detections.length > 0);
            }, 100);
        };

In the code above, we begin by defining a useState array when the user’s face is detected during the sign-up process. Thereafter, the function to trigger the browser camcorder is then activated. With this on, we can then trigger the handlePlayFunction in the code. This function monitors facial detection as highlighted by the face models already initialized. The stopVid function is also triggered when the user’s facial detection has been successfully completed.

In this section, we also activated the browser camcorder tool in our application to provide us with real time video. The CaptureSnapshot function helps to obtain a snapshot from the current video being showcased.

const RegSubmit = async (e) => {
  e.preventDefault();
  console.log("hello");

  try {
    const res = await axios.post(BACKEND_URL, {
      username: userRef.current.value,
      email: emailRef.current.value,
      FullName: FullRef.current.value,
      password: passwordRef.current.value,
      faceDescriptor: descriptionValue,
    });

    console.log(res.data);
    setError(false);
    navigate("/login");
    console.log("help");
  } catch (err) {
    console.error(err);
    setError(true);
  }
};

With all the values obtained, the regSubmit function is then defined. When executed, it stores the provided user details with the face description object on our backend server which can then be accessed in the next section for authentication.

Below is the full registration code.

import React, { useState, useRef, useEffect } from 'react';
import * as faceapi from 'face-api.js';
import { useNavigate } from 'react-router-dom';
import axios from 'axios';

const Register = () => {
  const navigate = useNavigate("/");

  const userRef = useRef();
  const passwordRef = useRef();
  const emailRef = useRef();
  const FullRef = useRef();
  const snapshotRef = useRef(null);
  const videoRef = useRef(null);
  const canvasRef = useRef(null);

  const [modelIsLoaded, setModelIsLoaded] = useState(false);
  const [detections, setDetections] = useState([]);
  const [error, setError] = useState(false);
  const [snapshot, setSnapshot] = useState(null);
  const [cameraActive, setCameraActive] = useState(true);
  const [submitDisabled, setSubmitDisabled] = useState(true);
  const [descriptionValue, setDescriptionValue] = useState(null);
  const [faceDetected, setFaceDetected] = useState(false);

  useEffect(() => {
    const loadModels = async () => {
      await faceapi.nets.tinyFaceDetector.loadFromUri('/models');
      await faceapi.nets.faceLandmark68Net.loadFromUri('/models');
      await faceapi.nets.faceRecognitionNet.loadFromUri('/models');
      await faceapi.nets.faceExpressionNet.loadFromUri('/models');
      await faceapi.nets.tinyFaceDetector.loadFromUri('/models');
      setModelIsLoaded(true);
      startVideo();
    };

    loadModels();
  }, []);

  const RegSubmit = async (e) => {
    e.preventDefault();
    console.log("hello");

    try {
      const res = await axios.post('http://localhost:5000/v1/users', {
        username: userRef.current.value,
        email: emailRef.current.value,
        FullName: FullRef.current.value,
        password: passwordRef.current.value,
        faceDescriptor: descriptionValue
      });

      console.log(res.data);
      setError(false);
      navigate("/login");
      console.log("help");
    } catch (err) {
      console.log(err);
      setError(true);
    }
  };

  const startVideo = () => {
    navigator.mediaDevices
      .getUserMedia({ video: true })
      .then((stream) => {
        videoRef.current.srcObject = stream;
      })
      .catch((err) => console.error("Error accessing webcam: ", err));
  };

  const stopVid = () => {
    navigator.mediaDevices.getUserMedia({ video: false });
    const stream = videoRef?.current?.srcObject;
    if (stream) {
      stream.getTracks().forEach((track) => track.stop());
      videoRef.current.srcObject = null;
      setCameraActive(false);
    }
  };

  const captureSnapshot = async () => {
    const canvas = snapshotRef.current;
    const context = canvas.getContext('2d');
    context.drawImage(videoRef.current, 0, 0, canvas.width, canvas.height);
    const dataUrl = canvas.toDataURL('image/jpeg');
    setSnapshot(dataUrl);

    const detection = await faceapi
      .detectSingleFace(canvas, new faceapi.TinyFaceDetectorOptions())
      .withFaceLandmarks()
      .withFaceDescriptor();

    if (detection) {
      const newDescriptor = detection.descriptor;
      setDescriptionValue(newDescriptor);
      console.log(newDescriptor);
      setSubmitDisabled(false);
      stopVid();

      if (storedDescriptor && isMatchingFace(storedDescriptor, newDescriptor)) {
        setInterval(alert("face matched"), 100);
      } else {
        alert("No Match Found!");
      }
    } else {
      console.error("No face detected in snapshot");
    }
  };

  const handleVideoPlay = async () => {
    const video = videoRef.current;
    const canvas = canvasRef.current;
    const displaySize = { width: video.width, height: video.height };
    faceapi.matchDimensions(canvas, displaySize);

    setInterval(async () => {
      if (!cameraActive) return;

      const detections = await faceapi.detectAllFaces(
        video,
        new faceapi.TinyFaceDetectorOptions()
      );

      const resizedDetections = faceapi.resizeResults(detections, displaySize);
      canvas.getContext('2d').clearRect(0, 0, canvas.width, canvas.height);
      faceapi.draw.drawDetections(canvas, resizedDetections);

      const detected = detections.length > 0;
      if (detected && !faceDetected) {
        captureSnapshot();
      }

      setFaceDetected(detected);
    }, 100);
  };

  return (
    <div className="flex flex-col w-full h-screen justify-center">
      <div className="flex flex-col">
        <form className="flex flex-col mb-2 w-full" onSubmit={RegSubmit}>
          <h3 className="flex flex-col mx-auto mb-5">Registration Page</h3>

          <div className="flex flex-col mb-2 w-[50%] mx-auto items-center">
            <input
              type="text"
              placeholder="Email"
              className="w-full rounded-2xl h-[50px] border-2 p-2 mb-2 border-gray-900"
              required
              ref={emailRef}
            />
            <input
              type="text"
              placeholder="Username"
              className="w-full rounded-2xl h-[50px] border-2 p-2 mb-2 border-gray-900"
              required
              ref={userRef}
            />
            <input
              type="text"
              placeholder="Full Name"
              className="w-full rounded-2xl h-[50px] border-2 p-2 mb-2 border-gray-900"
              required
              ref={FullRef}
            />
            <input
              type="password"
              placeholder="Password"
              className="w-full rounded-2xl h-[50px] border-2 p-2 mb-2 border-gray-900"
              required
              ref={passwordRef}
            />

            <div>
              {!modelIsLoaded && cameraActive && !descriptionValue ? (
                <p>Loading</p>
              ) : (
                <>
                  {!descriptionValue && (
                    <>
                      <video
                        ref={videoRef}
                        width="200"
                        height="160"
                        onPlay={handleVideoPlay}
                        autoPlay
                        muted
                      />
                      <canvas
                        ref={canvasRef}
                        width="200"
                        height="160"
                        style={{ position: 'absolute', top: 0, left: 0 }}
                      />
                      <p>
                        {faceDetected ? (
                          <span style={{ color: 'green' }}>Face Detected</span>
                        ) : (
                          <span style={{ color: 'red' }}>No Face Detected</span>
                        )}
                      </p>
                      <canvas
                        ref={snapshotRef}
                        width="480"
                        height="360"
                        style={{ display: 'none' }}
                      />
                    </>
                  )}
                </>
              )}

              {snapshot && (
                <div style={{ marginTop: '20px' }}>
                  <h4>Face Snapshot:</h4>
                  <img
                    src={snapshot}
                    alt="Face Snapshot"
                    width="200"
                    height="160"
                  />
                </div>
              )}
            </div>

            <div className="mt-2">
              <button type="button" onClick={stopVid}>
                Stop Video
              </button>
            </div>

            <button
              disabled={submitDisabled}
              className="mx-auto mt-4 rounded-2xl cursor-pointer text-white bg-primary w-[80%] lg:w-[50%] h-[40px] text-center items-center justify-center"
              type="submit"
            >
              Register
            </button>
          </div>

          <div className="flex flex-col mt-1 w-full">
            <p className="flex justify-center">
              Registered previously?&nbsp;
              <a href="/login" className="text-blue-600 underline">
                Login
              </a>
            </p>
          </div>

          {error && (
            <p className="text-red-600 text-center mt-2">
              Error while registering, try again
            </p>
          )}
        </form>
      </div>
    </div>
  );
};

export default Register;

Going forward, we will be working on our multifactor authentication system. In the code below, we will be highlighting the loginSubmit function which will be triggered when the user email and password credentials are provided for logging in to our chat application. The useRef hook is initialized which ensures that the values passed in the input boxes are parsed to the backend via the Axios request tool.

import React, { useState, useRef, useEffect } from 'react';
import { Link, useNavigate } from 'react-router-dom';
import axios from 'axios';

function Login() {
  const navigate = useNavigate();
  const userRef = useRef();
  const passwordRef = useRef();

  const [error, setError] = useState(false);

  const LoginSubmit = async (e) => {
    e.preventDefault();
    try {
      const res = await axios.post(
        'http://localhost:5000/v1/auth/login',
        {
          email: userRef.current.value,
          password: passwordRef.current.value,
        },
        { withCredentials: true }
      );

      console.log(res?.data);
      setError(false);
      navigate('/confirm-auth');
      console.log(res);
    } catch (err) {
      setError(true);
      console.log(err);
    }
  };
}

The full login page code example will be provided here. After successfully confirming their identity via the use of the password authentication feature, we can then go on to confirm the user’s identity via the use of the face recognition system.

import axios from 'axios';
import React, { useRef, useEffect, useState } from 'react';
import * as faceapi from 'face-api.js';
import { useNavigate } from 'react-router-dom';

First of all, we will set up the app by importing the necessary dependencies as highlighted in the code snippet above.

  useEffect(() => {
    const loadModels = async () => {
      await faceapi.nets.tinyFaceDetector.loadFromUri('/models');
      await faceapi.nets.faceLandmark68Net.loadFromUri('/models');
      await faceapi.nets.faceRecognitionNet.loadFromUri('/models');
      await faceapi.nets.faceExpressionNet.loadFromUri('/models');
    };

    loadModels();
  }, []);

  const handleVideoPlay = async () => {
    const video = videoRef.current;
    const canvas = canvasRef.current;

    const displaySize = { width: video.width, height: video.height };
    faceapi.matchDimensions(canvas, displaySize);

    setInterval(async () => {
      if (!cameraActive) return;

      const detections = await faceapi.detectAllFaces(
        video,
        new faceapi.TinyFaceDetectorOptions()
      );

      const resizedDetections = faceapi.resizeResults(detections, displaySize);
      canvas.getContext('2d').clearRect(0, 0, canvas.width, canvas.height);
      faceapi.draw.drawDetections(canvas, resizedDetections);

      const detected = detections.length > 0;
      if (detected && !faceDetected) {
        captureSnapshot();
      }

      setFaceDetected(detected);
    }, 100);
  };

  const startVideo = () => {
    navigator.mediaDevices
      .getUserMedia({ video: true })
      .then((stream) => {
        videoRef.current.srcObject = stream;
      })
      .catch((err) => console.error("Error accessing webcam: ", err));
  };

  const stopVid = () => {
    const stream = videoRef.current.srcObject;
    if (stream) {
      stream.getTracks().forEach((track) => track.stop());
      videoRef.current.srcObject = null;
      setCameraActive(false);
    }
  };

  const deleteImage = () => {
    setSnapshot(null);
    setDescriptionValue(null);
    setFaceDetected(false);
    setCameraActive(true);
    startVideo();
  };

  const captureSnapshot = async () => {
    const canvas = snapshotRef.current;
    const context = canvas.getContext('2d');
    context.drawImage(videoRef.current, 0, 0, canvas.width, canvas.height);

    const dataUrl = canvas.toDataURL('image/jpeg');
    setSnapshot(dataUrl);
    stopVid();

    const detection = await faceapi
      .detectSingleFace(canvas, new faceapi.TinyFaceDetectorOptions())
      .withFaceLandmarks()
      .withFaceDescriptor();

    if (detection) {
      const newDescriptor = detection.descriptor;
      setDescriptionValue(newDescriptor);
      console.log(newDescriptor);
    }
  };

After initializing all the necessary dependencies, we also imported our models as we did in the registration page to detect the user’s face and then generate a face description. We also allowed for the user to delete the snapshot and retake the image as many times as possible.

  const FaceAuthenticate = async (e) => {
    e.preventDefault();

    try {
      const res = await axios.post(
        'http://localhost:5000/v1/auth/face-auth',
        { faceDescriptor: descriptionValue },
        { withCredentials: true }
      );

      console.log(res?.data);
      navigate('/chat');
    } catch (err) {
      console.log(err);
    }
  };

After the face descriptor object gets generated, we then sent it to the backend to compare it with the stored face descriptor obtained at the point of registration. If they match, we get redirected to the chat application. Otherwise, an appropriate error message denying us access to the chat application is displayed.

Here is the code to the FaceAuth page:

import axios from 'axios';
import React, { useRef, useEffect, useState } from 'react';
import * as faceapi from 'face-api.js';
import { useNavigate } from 'react-router-dom';

const FaceAuth = () => {
  const navigate = useNavigate("/");

  const videoRef = useRef(null);
  const canvasRef = useRef(null);
  const snapshotRef = useRef(null);

  const [cameraActive, setCameraActive] = useState(true);
  const [snapshot, setSnapshot] = useState(null);
  const [descriptionValue, setDescriptionValue] = useState(null);
  const [faceDetected, setFaceDetected] = useState(false);

  useEffect(() => {
    const loadModels = async () => {
      await faceapi.nets.tinyFaceDetector.loadFromUri('/models');
      await faceapi.nets.faceLandmark68Net.loadFromUri('/models');
      await faceapi.nets.faceRecognitionNet.loadFromUri('/models');
      await faceapi.nets.faceExpressionNet.loadFromUri('/models');
    };

    loadModels();
  }, []);

  const handleVideoPlay = async () => {
    const video = videoRef.current;
    const canvas = canvasRef.current;

    const displaySize = { width: video.width, height: video.height };
    faceapi.matchDimensions(canvas, displaySize);

    setInterval(async () => {
      if (!cameraActive) return;

      const detections = await faceapi.detectAllFaces(
        video,
        new faceapi.TinyFaceDetectorOptions()
      );

      const resizedDetections = faceapi.resizeResults(detections, displaySize);
      canvas.getContext('2d').clearRect(0, 0, canvas.width, canvas.height);
      faceapi.draw.drawDetections(canvas, resizedDetections);

      const detected = detections.length > 0;
      if (detected && !faceDetected) {
        captureSnapshot();
      }

      setFaceDetected(detected);
    }, 100);
  };

  const startVideo = () => {
    navigator.mediaDevices
      .getUserMedia({ video: true })
      .then((stream) => {
        videoRef.current.srcObject = stream;
      })
      .catch((err) => console.error("Error accessing webcam: ", err));
  };

  const stopVid = () => {
    const stream = videoRef.current.srcObject;
    if (stream) {
      stream.getTracks().forEach((track) => track.stop());
      videoRef.current.srcObject = null;
      setCameraActive(false);
    }
  };

  const deleteImage = () => {
    setSnapshot(null);
    setDescriptionValue(null);
    setFaceDetected(false);
    setCameraActive(true);
    startVideo();
  };

  const captureSnapshot = async () => {
    const canvas = snapshotRef.current;
    const context = canvas.getContext('2d');
    context.drawImage(videoRef.current, 0, 0, canvas.width, canvas.height);

    const dataUrl = canvas.toDataURL('image/jpeg');
    setSnapshot(dataUrl);
    stopVid();

    const detection = await faceapi
      .detectSingleFace(canvas, new faceapi.TinyFaceDetectorOptions())
      .withFaceLandmarks()
      .withFaceDescriptor();

    if (detection) {
      const newDescriptor = detection.descriptor;
      setDescriptionValue(newDescriptor);
      console.log(newDescriptor);
    }
  };

  const FaceAuthenticate = async (e) => {
    e.preventDefault();

    try {
      const res = await axios.post(
        'http://localhost:5000/v1/auth/face-auth',
        { faceDescriptor: descriptionValue },
        { withCredentials: true }
      );

      console.log(res?.data);
      navigate('/chat');
    } catch (err) {
      console.log(err);
    }
  };

  return (
    <>
      <div className="flex w-full h-screen flex-col justify-center">
        <p className="flex flex-col mx-auto items-center text-lg font-semibold mb-3">
          Take a snapshot to confirm your identity
        </p>
        <p className="text-center mb-4">Ensure that the picture is taken in a bright area</p>

        <button
          onClick={startVideo}
          className="flex w-[30%] mx-auto text-center items-center justify-center mb-5 h-[40px] bg-blue-600 rounded-md text-white"
        >
          Turn on Webcam
        </button>

        {!snapshot ? (
          <>
            <video
              className="flex mx-auto items-center rounded-md"
              ref={videoRef}
              width="240"
              height="180"
              onPlay={handleVideoPlay}
              autoPlay
              muted
            />
            <canvas
              ref={snapshotRef}
              width="240"
              height="180"
              style={{ position: 'absolute', top: 0, left: 0 }}
            />
            <button onClick={captureSnapshot} className="mt-4 mx-auto block text-sm text-blue-600 underline">
              Take a snapshot
            </button>
          </>
        ) : (
          <div className="flex w-full justify-center">
            <img
              src={snapshot}
              className="rounded-lg"
              width="240"
              height="180"
              alt="Face Snapshot"
            />
          </div>
        )}

        <div className="flex flex-row w-full justify-evenly mt-5">
          <button
            onClick={deleteImage}
            className="bg-purple-500 text-white p-2 h-[35px] rounded-lg"
          >
            Delete Image
          </button>
          <button
            onClick={FaceAuthenticate}
            className="bg-purple-500 text-white p-2 h-[35px] rounded-lg"
          >
            Upload Image
          </button>
        </div>
      </div>
    </>
  );
};

export default FaceAuth;

Displayed below is how the face authentication page should look like.

Having set up the frontend, let's head to the backend and configure the registration and login endpoint for our project. The entire code to the backend project can be gotten here. We will only be highlighting the faceAuth backend function in this article.

To verify authentication, we will be using the sessions option instead of the JWT option. Important user information will be stored and accessed in the session cookies attached to the requests and responses to the frontend. Here is the faceAuth function:

const faceAuth = async (req, res) => {
  try {
    console.log(req.session);

    const id = req.session.passport?.user;
    console.log(id);


    const user = await User.findById(id);
    console.log(user);

    if (user == null) {
      return res.status(400).json({ err: "User not found" });
    }


  } catch (err) {
    console.error(err);
    res.status(500).json({ err: "Internal Server Error" });
  }
};

First, we defined an asynchronous function named faceAuth. We then obtained the unique ID of the user who had successfully scaled over the initial login process from the request session.

To confirm the similarity of the user's stored face descriptor and the picture sent from the frontend, we utilized the matching face function based on the Euclidean algorithm to confirm the user's identity as done below.

const isMatchingFace = (descriptor1, descriptor2, threshold = 0.6) => {
  // Convert the stored descriptors to Float32Array if they aren't already
  if (!(descriptor1 instanceof Float32Array)) {
    descriptor1 = new Float32Array(Object.values(descriptor1));
  }

  if (!(descriptor2 instanceof Float32Array)) {
    descriptor2 = new Float32Array(Object.values(descriptor2));
  }

  const distance = faceapi.euclideanDistance(descriptor1, descriptor2);
  console.log("Euclidean Distance:", distance);

  return distance < threshold;
};

As stated in the code above, the threshold of similarity of comparison used was 0.6. This is flexible and can be modified to suit the user's preference, as a higher threshold will provide better accuracy overall.
If the function returns true, then the user has been successfully authenticated and can then have access to our chat application. Here is the full code snippet.

const faceAuth = async (req, res) => {
  try {
    console.log(req.session);

    const id = req.session.passport?.user;
    console.log(id);

    const { faceDescriptor } = req.body;
    const user = await User.findById(id);
    console.log(user);

    if (user == null) {
      return res.status(400).json({ err: "User not found" });
    }

    const isMatchingFace = (descriptor1, descriptor2, threshold = 0.6) => {
      // Convert the stored descriptor (object) to a Float32Array
      if (!(descriptor1 instanceof Float32Array)) {
        descriptor1 = new Float32Array(Object.values(descriptor1));
      }

      if (!(descriptor2 instanceof Float32Array)) {
        descriptor2 = new Float32Array(Object.values(descriptor2));
      }

      const distance = faceapi.euclideanDistance(descriptor1, descriptor2);
      console.log("Euclidean Distance:", distance);

      return distance < threshold;
    };

    if (isMatchingFace(faceDescriptor, user.faceDescriptor)) {
      console.log("Face match successful");
      req.session.mfa = true;

      return res.status(200).json({
        msg: "User authentication was successful. Proceed to the chat app.",
      });
    } else {
      return res.status(401).json({ msg: "Face does not match. Access denied." });
    }
  } catch (err) {
    console.log(err);
    res.status(500).json({
      err: "User face couldn't be authenticated. Please try again later",
    });
  }
};

With the main hurdle completed, we can then navigate to our application and have a seamless chat experience.

Additionally, as a safety measure, a rate limiter is also in place to minimize the use of brute-force techniques by malicious individuals to gain access to the chat application.

Additional Information and Tips

The overall aim of these efforts is to achieve a more scalable and secure method of user validation. The threshold can easily be modified and tweaked to improve application accuracy. Alternatively, the AWS Rekognition tool can sufficiently replace the Face API tool with efficient cloud-powered models. The limitations of facial recognition can also be overcome by exploring biometric authentication, as it’s a known fact that each individual's fingerprint is unique, greatly reducing the risk of user compromise.

Conclusion

So far, we have walked through the process of creating an efficient multi-factor facial authentication-based tool to prevent intruder access to our chat application, ensuring and prioritizing the highest level of user privacy. Need an SDK that assures you of a seamless and secure chat experience? Try Stream.io today.

In this article, we’ll compare some libraries that you can use for authentication in your Next app. They include: Clerk, Kinde and Better Auth. You’ll learn how to set up these tools in a Next.js application, with the goal of creating at least one authenticated, protected page route.

The aim here is simply to see how each tool works when it comes to speed of setup and ease of use.

Table of Contents

• What are Clerk, Kinde and Better Auth?

• Prerequisites

• How to Set Up Authentication Using Clerk

• How to Set Up Authentication Using Kinde

• How to Set Up Authentication Using Better Auth

• When To Use Each Library

• Conclusion

What are Clerk, Kinde and Better Auth?

Clerk, Kinde and Better Auth are basically modern authentication providers, much like Auth.js, which have been built with developers in mind. Although they share similarities, they have certain aspects that differentiate them from each other.

To begin with, Clerk is more full-featured. It's more of a hosted solution that offers components which are ready-made, as well as user management and other integrations, which allow you to get up and running pretty quickly.

Kinde, on the other hand, is more of a developer platform, which has authentication, feature flags and team management all in one place.

Better Auth is more of an open-source and code-first place that gives developers the building blocks to create authentication without having to be locked into an ecosystem.

Prerequisites

The prerequisites for this tutorial are minimal, and the databases and Prisma ORM are only required for Better Auth. Alternatively, you can use any of the databases inside a Docker container instead of installing them locally, but that is outside of the scope of this tutorial.

You’ll need these to follow along:

• Node and npm installed

• Prisma ORM

• SQLite, PostgreSQL, or MySQL database set up locally

• Code editor/IDE

Let's see how to set up authentication with all three auth platforms in a Next.js application. We’ll use separate Next.js applications to set up each library so that the codebase will remain clean, and you can experience what it's like to set them up from scratch.

First, decide on a location for your project, like on the desktop and then use the command npx create-next-app@latest to set up a Next.js project. You can just use the default configuration. These are the settings I used:

✔ What is your project named? … my-app
✔ Would you like to use TypeScript? … No / Yes
✔ Which linter would you like to use? › ESLint
✔ Would you like to use Tailwind CSS? … No / Yes
✔ Would you like your code inside a src/ directory? … No / Yes
✔ Would you like to use App Router? (recommended) … No / Yes
✔ Would you like to use Turbopack? (recommended) … No / Yes
✔ Would you like to customize the import alias (@/* by default)? … No / Yes

We are creating three apps, so it's up to you if you want to duplicate the codebases now and give them different names like my-app, my-app2 and my-app3 or do them later when we reach each section.

How to Set Up Authentication Using Clerk

With your Next.js project set up, cd into the my-app folder or whatever name you gave the project and run the following command to install the Next.js SDK for Clerk:

npm install @clerk/nextjs

Now we need to create a middleware file that will grant us access to user authentication throughout our entire app.

Create a middleware.ts file with this code inside the /src folder:

import { clerkMiddleware } from '@clerk/nextjs/server'

export default clerkMiddleware()

export const config = {
  matcher: [
    // Skip Next.js internals and all static files, unless found in search params
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    // Always run for API routes
    '/(api|trpc)(.*)',
  ],
}

With this file, authentication is set up for different page routes.

All that's left is to add the <ClerkProvider> component to your app's layout.tsx file so that authentication is available throughout your entire app.

Just replace all of the code inside of src/app/layout.tsx with this code here:

import type { Metadata } from 'next';
import { Geist, Geist_Mono } from 'next/font/google';
import './globals.css';
import {
  ClerkProvider,
  SignInButton,
  SignUpButton,
  SignedIn,
  SignedOut,
  UserButton,
} from '@clerk/nextjs';

const geistSans = Geist({
  variable: '--font-geist-sans',
  subsets: ['latin'],
});

const geistMono = Geist_Mono({
  variable: '--font-geist-mono',
  subsets: ['latin'],
});

export const metadata: Metadata = {
  title: 'Create Next App',
  description: 'Generated by create next app',
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <ClerkProvider>
      <html lang="en">
        <body
          className={`${geistSans.variable} ${geistMono.variable} antialiased`}
        >
          <header className="flex justify-end items-center p-4 gap-4 h-16">
            <SignedOut>
              <SignInButton />
              <SignUpButton>
                <button className="bg-[#6c47ff] text-white rounded-full font-medium text-sm sm:text-base h-10 sm:h-12 px-4 sm:px-5 cursor-pointer">
                  Sign Up
                </button>
              </SignUpButton>
            </SignedOut>
            <SignedIn>
              <UserButton />
            </SignedIn>
          </header>
          {children}
        </body>
      </html>
    </ClerkProvider>
  );
}

What we did was to import the ClerkProvider, as well as the buttons for signing in and out using Clerk authentication. These additions have been added to the layout.tsx file which means that they are available throughout our entire application. So every page should display the sign in flow at the top of the page.

The ClerkProvider component is needed for integrating Clerk inside of our application, so now we can use session and user context with Clerks hooks and components.

Now you can run your Next.js app with npm run dev, and you should see the homepage, as well as a sign-in and sign-up button at the top of the page, as shown here:

Clicking the signup button will take you to a sign-up form where you can use an email address or sign in with Google, which is pretty easy.

When you have signed in, you should see your profile picture and account information in the top right-hand corner of the screen. That's the hard part done - all that's left is to create a page and then make the route protected so that only a signed-in user can access it.

To begin with, lets update our middleware.ts file with some code which lets us protect a route:

import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'

const isProtectedRoute = createRouteMatcher(['/dashboard(.*)'])

export default clerkMiddleware(async (auth, req) => {
  if (isProtectedRoute(req)) await auth.protect()
})

export const config = {
  matcher: [
    // Skip Next.js internals and all static files, unless found in search params
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    // Always run for API routes
    '/(api|trpc)(.*)',
  ],
}

We added some new imports for createRouteMatcher, which is a Clerk helper function that gives us the power to protect multiple routes. In this case, the dashboard page route in our application requires a user to be signed in to access the route. Now we need create a dashboard page. Create this folder and file inside the app folder: dashboard/page.tsx. Then complete the page by giving it some code like below:

export default function Dashboard() {
  return (
    <>
      <h1>Dashboard Page</h1>
    </>
  );
}

We created a simple page which has a heading that says Dashboard Page.

Congratulations, you have successfully added authentication to your Next app and protected a page route, and it only took a few steps! When you navigate to http://localhost:3000/dashboard as a non-signed-in user, you should be redirected to a sign-in form as shown below:

If you are already signed in, then you should see the Dashboard page. You can learn more using the Clerk official documentation.

How to Set Up Authentication Using Kinde

Create another Next.js application for this project if you have not done so already. Kinde will require you to create an account on their platform before using their authentication library. Let's go through the sign-up process.

Firstly, go to the Kinde website, and you should see a button that says "Start for free" or similar.

Clicking that button should take you to a page where you can create an account:

An email code verification may be required:

On the next screen, you should be able to enter your business details, which can be anything you want. Every time you set up authentication for an app, you will have to create an application for it on your account. Give it any name you want, like app-clerk-test3272346214. The same name will be used for the business and the domain.

On the next screen, we’ll choose to use an existing codebase because we have a local project:

The codebase is in Next.js, so select it from the list:

The next important step is choosing how users are going to sign in. I chose email and Google. You can select whichever options you desire:

Now, on the last screen, choose to explore at your own pace.

And finally, we’ve reach the dashboard screen.

Viewing details lets you see your app keys and environment variables, among other useful information.

That's the long part out of the way, let's get to some code. Navigate to your project folder and then install the package for Kinde:

npm i @kinde-oss/kinde-auth-nextjs

Now, create a .env.local file and put it in the root folder of your project with your environment variables. You can find your environment variables in the Quick Start page of your application.

Here's an example:

KINDE_CLIENT_ID=<your_kinde_client_id>
KINDE_CLIENT_SECRET=<your_kinde_client_secret>
KINDE_ISSUER_URL=https://<your_kinde_subdomain>.kinde.com
KINDE_SITE_URL=http://localhost:3000
KINDE_POST_LOGOUT_REDIRECT_URL=http://localhost:3000
KINDE_POST_LOGIN_REDIRECT_URL=http://localhost:3000/dashboard

Next, you need to create the following API endpoint and folder structure and files as shown here src/app/api/auth/[kindeAuth]/route.ts.

This is the code needed for the route.ts file:

import {handleAuth} from "@kinde-oss/kinde-auth-nextjs/server";

export const GET = handleAuth();

With this code, Kinde can now handle auth endpoints inside our application.

Once again, you’ll need a middleware.ts file so that authentication can be set up properly in your app. The file should be in the root directory and needs this code added to it:

import { withAuth } from "@kinde-oss/kinde-auth-nextjs/middleware";

export default function middleware(req) {
  return withAuth(req);
}

export const config = {
  matcher: [
    // Run on everything but Next internals and static files
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
  ]
};

Like before, we can now protect page routes with this file. Your app has to be wrapped in a Kinde Auth Provider so that you can access the data throughout your app.

Create an AuthProvider.tsx file inside the app directory with this code:

"use client";
import {KindeProvider} from "@kinde-oss/kinde-auth-nextjs";

export const AuthProvider = ({children}) => {
  return <KindeProvider>{children}</KindeProvider>;
};

Kinde uses a React Context Provider to maintain its internal state throughout our application by using the KindeProvider component.

Next, replace and update the layout.tsx file, so it is wrapped in the Auth Provider:

import type { Metadata } from 'next';
import { Geist, Geist_Mono } from 'next/font/google';
import './globals.css';
import { AuthProvider } from './AuthProvider';
import {
  RegisterLink,
  LoginLink,
  LogoutLink,
} from '@kinde-oss/kinde-auth-nextjs/components';

const geistSans = Geist({
  variable: '--font-geist-sans',
  subsets: ['latin'],
});

const geistMono = Geist_Mono({
  variable: '--font-geist-mono',
  subsets: ['latin'],
});

export const metadata: Metadata = {
  title: 'Create Next App',
  description: 'Generated by create next app',
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <AuthProvider>
      <div className="grid grid-flow-col gap2">
        <LoginLink>Sign in</LoginLink>
        <RegisterLink>Sign up</RegisterLink>
        <LogoutLink>Log out</LogoutLink>
      </div>
      <html lang="en">
        <body
          className={`${geistSans.variable} ${geistMono.variable} antialiased`}
        >
          {children}
        </body>
      </html>
    </AuthProvider>
  );
}

In this file, we also added buttons for signing up, signing in, and logging out which will be displayed at the top of every page as this is the main layout.tsx file. Our AuthProvider component is wrapped around our application which means we can now use Kinde throughout it.

The basic setup is now complete! Run the usual command to start the Next.js app, and you should see the sign-in flow buttons at the top of the screen.

You should be able to sign up and create an account. Doing so will redirect you to the dashboard screen, which shows a 404 error page. This is because we have not created a dashboard page yet.

This is what the Kinde register form looks like:

And this is what the Kinde sign-in form looks like:

Only one step remains now: creating a protected route for your authentication.

Create the following file structure and file for your dashboard page: src/app/dashboard/page.tsx.

Then add this code to the file:

'use client';

import { useKindeBrowserClient } from '@kinde-oss/kinde-auth-nextjs';
import { LoginLink } from '@kinde-oss/kinde-auth-nextjs/components';

export default function Dashboard() {
  const { isAuthenticated, isLoading } = useKindeBrowserClient();

  if (isLoading) return <div>Loading...</div>;

  return isAuthenticated ? (
    <div>
      <p>
        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque ut
        ante enim. Maecenas ut eros nec diam vulputate sollicitudin. Cras ut
        quam leo. Pellentesque semper, lacus sodales gravida suscipit, metus
        quam congue eros, nec sagittis est dolor eu turpis. Nulla congue
        tristique venenatis. Donec ac venenatis mauris. Donec commodo cursus
        magna, vitae tincidunt magna vestibulum eget.
      </p>
    </div>
  ) : (
    <div>
      You have to <LoginLink>Login</LoginLink> to see this page
    </div>
  );
}

This page file checks to see if the user is authenticated and signed in. If they are signed in, they see the Lorem ipsum text, and if they are not signed in, they will see a message telling them that they have to log in to see the page.

All you have to do is go to the dashboard route as a signed-in or signed-out user to see it for yourself. And that's pretty much the basics of authentication using the Kinde platform. See the online documentation to learn everything there is to know about it.

How to Set Up Authentication Using Better Auth

And lastly, let's create a project that uses Better Auth. Better Auth requires a database to store user data, so the setup will require a few more steps. You can find the installation guide here, but, we’ll also go through it here.

Ok, just like before, create a Next.js project if you have not done so yet and then install the better-auth package with this command:

npm install better-auth

Next, you have to set up your environment variables, so create a .env file with these values:

BETTER_AUTH_SECRET= #Create your own secret key!
BETTER_AUTH_URL=http://localhost:3000 # Base URL of your app

Make sure that you create a secret key, as if you were generating a secure password with uppercase and lowercase letters and numbers.

Let's get our Prisma package and PostgreSQL database set up, so run these scripts to initialise them:

npm install prisma --save-dev
npx prisma init
npm install @prisma/client

In the next step, we have to create a better auth instance. In this case, we will put the file in the src/lib/auth.ts.

So create an auth.ts file with this code:

import { betterAuth } from 'better-auth';
import { anonymous } from 'better-auth/plugins';
import { prismaAdapter } from 'better-auth/adapters/prisma';
// If your Prisma file is located elsewhere, you can change the path
import { PrismaClient } from '@/generated/prisma';

const prisma = new PrismaClient();
export const auth = betterAuth({
  database: prismaAdapter(prisma, {
    provider: 'postgresql', // or "mysql", "postgresql", ...etc
  }),
  plugins: [anonymous()],
});

In this file, we have configured Better Auth to use Prisma ORM for our database connection, and we will be connecting to a PostgreSQL database. If you want, you can change it to a different database, but the setup might be different, so bear that in mind. You could also use Docker if you know how to set it up. Anonymous sign-in is the default for users.

Now we need to create our database tables for saving user information, so use this command in the terminal to do that:

npx @better-auth/cli generate

You might see this warning, just select yes with "y":

prisma:warn In production, we recommend using `prisma generate --no-engine` (See: `prisma generate --help`)
✔ The file ./prisma/schema.prisma already exists. Do you want to overwrite the schema to the file? … yes

For handling API requests, we must have a route handler set up on our server. Create a folder structure and file for the route.ts file, like shown here /app/api/auth/[...all]/route.ts.

Add this code to the file:

import { auth } from '@/lib/auth'; // path to your auth file
import { toNextJsHandler } from 'better-auth/next-js';

export const { POST, GET } = toNextJsHandler(auth);

This file lets you handle POST and GET requests for your auth file.

Lastly, we have to create a lib/auth-client.ts file. This file allows you to interact with the auth server, and it has a plugin so users can sign in anonymously.

And here is the code to put inside this file:

import { createAuthClient } from 'better-auth/react';
import { anonymousClient } from 'better-auth/client/plugins';
export const authClient = createAuthClient({
  /** The base URL of the server (optional if you're using the same domain) */
  baseURL: 'http://localhost:3000',
  plugins: [anonymousClient()],
});

With this file, it's possible for users to sign in anonymously without having to even create an account or use social sign-in, thanks to the plugin.

All that remains is to create another dashboard page, which has authentication like before. Create another dashboard page with this structure: app/dashboard/page.tsx, and then add this code to the file:

'use client';

import { useState, useEffect } from 'react';
import { authClient } from '@/lib/auth-client';

type User = {
  id: string;
  email: string;
  emailVerified: boolean;
  name: string;
  createdAt: Date;
  updatedAt: Date;
  image?: string | null;
  isAnonymous?: boolean | null;
};

export default function Dashboard() {
  const [user, setUser] = useState<User | null>(null);
  const [isLoading, setIsLoading] = useState(true);
  const [isSigningIn, setIsSigningIn] = useState(false);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    const checkAuth = async () => {
      try {
        const session = await authClient.getSession();
        if (session.data?.user) {
          setUser(session.data.user);
        }
      } catch (err) {
        console.error('Auth check error:', err);
      } finally {
        setIsLoading(false);
      }
    };

    checkAuth();
  }, []);

  const handleAnonymousSignIn = async () => {
    try {
      setIsSigningIn(true);
      setError(null);

      const result = await authClient.signIn.anonymous();

      if (result.data) {
        setUser(result.data.user);
        console.log('Anonymous user signed in:', result.data.user);
      } else if (result.error) {
        setError(result.error.message || 'Failed to sign in anonymously');
      }
    } catch (err) {
      setError('An unexpected error occurred');
      console.error('Anonymous sign-in error:', err);
    } finally {
      setIsSigningIn(false);
    }
  };

  const handleSignOut = async () => {
    try {
      await authClient.signOut();
      setUser(null);
    } catch (err) {
      console.error('Sign out error:', err);
    }
  };

  if (isLoading) {
    return (
      <div className="max-w-4xl mx-auto p-6">
        <div className="flex items-center justify-center min-h-[400px]">
          <div className="text-center">
            <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-blue-500 mx-auto mb-4"></div>
            <p className="text-gray-600">Checking authentication...</p>
          </div>
        </div>
      </div>
    );
  }

  if (!user) {
    return (
      <div className="max-w-4xl mx-auto p-6">
        <div className="text-center">
          <h1 className="text-3xl font-bold mb-6">Access Required</h1>
          <p className="text-gray-600 mb-8">
            You need to be signed in to access our dashboard. Choose an option
            below to continue.
          </p>

          {error && (
            <div className="bg-red-100 border border-red-400 text-red-700 px-4 py-3 rounded mb-6 max-w-md mx-auto">
              {error}
            </div>
          )}

          <div className="bg-gray-50 p-8 rounded-lg border max-w-md mx-auto">
            <h2 className="text-xl font-semibold mb-4 text-black">
              Sign In Options
            </h2>

            <button
              onClick={handleAnonymousSignIn}
              disabled={isSigningIn}
              className="w-full bg-blue-500 hover:bg-blue-600 disabled:bg-blue-300 text-white px-6 py-3 rounded font-medium mb-4"
            >
              {isSigningIn ? 'Signing in...' : 'Sign In Anonymously'}
            </button>

            <p className="text-sm text-gray-500 mb-4">
              Anonymous access allows you to use our dashboard without creating
              an account. You can always link your account later.
            </p>
          </div>
        </div>
      </div>
    );
  }

  return (
    <div className="max-w-4xl mx-auto p-6">
      <div className="bg-green-50 border border-green-200 rounded-lg p-4 mb-6">
        <div className="flex items-center justify-between">
          <div>
            <h2 className="text-lg font-semibold text-green-800">
              Welcome, {user.isAnonymous ? 'Anonymous User' : user.name}!
            </h2>
            <p className="text-sm text-green-600">
              {user.isAnonymous
                ? 'You are signed in anonymously'
                : `Signed in as ${user.email}`}
            </p>
          </div>
          <button
            onClick={handleSignOut}
            className="bg-red-500 hover:bg-red-600 text-white px-4 py-2 rounded text-sm"
          >
            Sign Out
          </button>
        </div>
      </div>

      <h1 className="text-3xl font-bold mb-6">Dashboard</h1>

      {process.env.NODE_ENV === 'development' && (
        <div className="mt-8 bg-gray-100 p-4 rounded-lg">
          <h3 className="font-semibold mb-2 text-black">Debug Info:</h3>
          <pre className="text-xs text-gray-600 overflow-auto">
            {JSON.stringify(user, null, 2)}
          </pre>
        </div>
      )}
    </div>
  );
}

This code creates a dashboard page which requires a user to be authenticated and signed in to use it. After a user signs in anonymously, they can view some debug info about their profile. So basically, this page is an authentication flow for our dashboard view which integrates with our custom authClient. This page also handles loading error state and sign out for anonymous users.

Ok, now we probably need to reset our Prisma database again, or we could get schema and table errors.

First, make sure that your Prisma development database is running with this command:

npx prisma dev

And then run these commands to reset the database and apply the new migrations for the schema:

npx prisma migrate reset
npx prisma migrate dev

You might need to restart the Prisma development server and then run it with the command npx prisma dev.

Our Better Auth app needs two servers to be running.

1. The Prisma development server

2. The Next.js application

With the Prisma development server running, you can now start the Next.js app with the usual command npm run dev.

If you encounter any problems with the Prisma ORM or database, like tables missing or schema mismatches, then here are some useful commands which could hopefully resolve them.

# ⚠️ WARNING: This will drop the database, recreate it, and apply all migrations from scratch.
npx prisma migrate reset

# Applies any new migrations that haven’t been run yet (or creates a new one if your schema changed).
npx prisma migrate dev

# Starts Prisma Studio (a GUI for exploring and editing your database).
npx prisma dev

# Runs Better Auth CLI migrations (sets up any database tables/changes required for authentication).
npx @better-auth/cli migrate

These commands are self-explanatory and let us run migrations on our database when there are changes, and we can see our database inside of Prisma Studio.

This is what the dashboard page looks like when a user is not signed in:

Signing in will show the dashboard screen. To learn more about Better Auth, you can read their official documentation.

When To Use Each Library

Each of these authentication libraries have their pros and cons, and can suit various needs depending on your project. Knowing when to use each one can better prepare you for real-world conditions and when building for production, so let's go through them and see how they compare.

When to Use Clerk

Clerk excels when you need to use auth quickly without worrying about managing multiple servers, and when you need to have pre-made interfaces and management systems. It's great for startups and teams that want to prioritize developer experience and fast implementation.

It has a streamlined and user-friendly setup, which is still able to support the bare minimum essentials, so it's a really good option for small teams and projects that must have an easy implementation. If you are building a SaaS that needs a good interface and components from the start, or if you require social logins without a ton of code, then it's a very good solution, especially if you want speed and cost effectiveness in a smaller project.

When to Use Kinde

Kinde is a fantastic choice when you are keen on having transparent pricing and quick auth integration in more frameworks. Kinde has been designed to be a cost-effective alternative to Clerk and offers more transparent pricing and a more generous, free tier.

It's great for teams that need to have a reliable authentication option but want lower costs and better framework support. Kinde is effective when used in medium-sized projects that need more than a basic authentication system, but also don't have the need to have enterprise-grade tooling.

When to Use Better Auth

Better Auth is a great solution when you have a need for an expansive set of features out of the box. It is also worth noting that Better Auth has a plugin ecosystem that can simplify adding more advanced functionalities with only a few lines of code. Of all the options discussed in this article, Better Auth is by far the cleanest; however, it requires more coding knowledge and skills.

It's a good option if you are building a TypeScript application and want to have full control over the customization and auth data flows. The framework is agnostic and has features such as 2FA, multi-tenant support and other complex features so developers can get the best out of the tool, as there is no vendor lock-in. Functionality can easily be expanded with the plugin ecosystem, so developers can tailor it to their needs.

Conclusion

All three platforms are fairly good at their job, and I do not doubt that they are going to remain popular options for adding authentication to our applications. Auth.js is one of the most well-known out there; however, Clerk, Kinde and Better Auth also appear to have growing followings, and judging by conversations on socials, they appear to be the first choice for many developers at the moment.

After experiencing what it's like to set them up for the first time, I would have to say that Clerk is the easiest to set up because you don't have to create an account, and you can get the authentication working fairly quickly with little troubleshooting. Kinde would be the second easiest to set up, in my opinion. You do have to register for an account to use the platform; however, the setup was also pretty easy and did not need any troubleshooting.

Better Auth is a great platform, but the setup requires a bit more work because a database is required for storing users' information, which makes the process slightly more difficult. I also found it easier to create authenticated routes with the other two auth options. However, the fact that the platform is open-source with no vendor lock-in works in its favour because developers can self-host and it's completely free, which means no paid plans.

Performing repetitive tasks while testing APIs is stressful and time-wasting. For example, the process of retrieving, copying and pasting new authentication tokens for use in Postman is repetitive. You can simplify this process by using Postman scripts to store auth tokens and then reuse them without repeating the copy and paste steps.

To practice along with this guide, you should have:

• The Postman API client installed on your computer

• Experience in making API requests with Postman

• A backend application that uses JWT authentication and has its documentation in your Postman client

If you don’t have a backend application setup, I created one that you can clone from GitHub at orimdominic/freeCodeCamp-postman-api-jwt.

By the end of this article, you should be able to simplify the process of obtaining and reusing authentication tokens across your API requests. You should also have a practical understanding of some scripts necessary for use in other areas of software testing with Postman.

Table of Contents

• Table of Contents

• What are Postman Scripts?

• How to Simplify Your JWT Authentication Process

  • Authenticate to Get the Token

  • How to Save the Token in a Variable with a Postman Script

  • How to Use the Variable in a Request

• Next Steps

What are Postman Scripts?

Postman scripts are blocks of JavaScript code that you can write and run within the Postman API client to automate and enhance API testing workflows. You can use Postman scripts to add code to run before and after API requests. These scripts can be used to:

• Add logic and process data from API requests

• Write test assertions for API responses

• Run automated tests on API endpoints

You can find Postman scripts under the Scripts tab of an API request. Code written in the Pre-request tab runs before the request is made and code written in the Post-response tab runs after the response is made.

How to Simplify Your JWT Authentication Process

In summary, you will carry out the following steps to achieve the objective of this tutorial:

1. Authenticate to get the token

2. Save the token in a collection variable with Postman scripts

3. Use the variable in an API request

Authenticate to Get the Token

To get started, carry out the following steps:

1. Start your backend application and make sure it is running successfully.

2. Open up your Postman application and go to the API request for signing in to get a JWT.

3. Make an API request to the sign in endpoint and take note of the JSON response schema.

The highlighted part of the image above shows the JSON response from a successful sign in request. In the response schema, the auth token to be used for authorization is in the data.token field. You will use Postman scripts to store this token in a variable and then use the variable in the Authorization header of requests that require authorization.

How to Save the Token in a Variable with a Postman Script

In Postman, click on the Scripts tab next to the Body tab. If the Postman application window is small, you may need to click a dropdown to see it. Next, click on the Post-response tab. In the text area to the right, you will write the script to capture the auth token from the response and store it in a Postman variable. Copy the JavaScript code below and paste it into the text area.

if (pm.response.code == 200) {
    const token = pm.response.json().data.token
    pm.collectionVariables.set("auth_token", token)
}

Postman scripts use the pm identifier to access and modify information in the Postman environment. The script above uses pm to first ensure that the request was successful by checking if the response status code is 200.

Inside the conditional statement, pm.response.json().data.token is used to get the authentication token from the JSON response and store it in a collection variable called auth_token. If auth_token doesn’t exist already, it is created and its value is set to the value of token. If it exists already, its value is replaced.

To confirm that auth_token has been set, click on the name of the collection (labelled 1 in the screenshot above) and then click on the Variables tab (labelled 2 in the screenshot above). Next, instead of repeatedly copying the token and pasting it in the Authorization header of your requests, you will use auth_token in the Authorization header of your requests.

How to Use the Variable in a Request

Reference the collection variable in the Authorization header by surrounding it with double curly braces {{auth_token}}. When you make an API request, Postman will use the value referenced by {{auth_token}} as the Authorization header.

If another authentication request causes the value of auth_token to be updated, you no longer need to copy the new auth token. The script in the post-response tab will update the auth_token value and you can go on with making API requests smoothly. No need for repeatedly copying and pasting - Don’t Repeat Yourself (DRY).

Next Steps

In this tutorial, you have learnt how to use Postman scripts to set environment variables in Postman. You have also learnt how to eliminate the process of repeatedly copying and pasting auth tokens for use in API requests.

For guides on writing assertion tests for your APIs, check out the Test API Functionality and Performance in Postman guide by Postman.

Zero-Trust Authentication fixes this. Instead of trusting people once they log in, it checks every person, every device, and every request, every single time. The rule is simple: "Trust no one, verify everything."

This isn't just theory – it works. Companies using zero-trust security have smaller breaches, meet compliance rules easier, and control who sees what data. This matters because 95% of data breaches happen due to human mistakes, and the average breach now costs $4.88 million.

In this article, you will learn how to build a complete Zero-Trust Authentication system into your web app step by step. From multi-factor authentication (MFA) to behavioral anomaly detection, we will discuss the architecture decisions, code examples, and some real-world approaches you are likely able to implement right away.

Table of Contents

• Prerequisites

• What Is Zero-Trust Authentication?

• Architecture Overview

• Multi-factor Authentication (MFA)

• JWT Token Management

• Session Security

• Role-Based Access Control (RBAC)

  • Using Middleware to Enforce RBAC

  • Testing Access Control Logic

• Continuous Verification

  • Behavioral Analysis

  • Step-Up Authentication

• Security Monitoring

  • Automating Threat Response

• Conclusion

Prerequisites

Before implementing zero-trust, make sure your stack aligns with frequent calls for token checks, volumes of logging, and the additional auth step, all without impairing system performance on the users' end.

You should at least have knowledge of:

• JWT and secure session handling

• MFA, specifically understanding TOTP

• Basic understanding of middleware design

Audit your system: examine login flows, token handling, protected routes, session termination, and identify weak spots like long sessions or unprotected routes.

What Is Zero-Trust Authentication?

Zero-Trust Authentication (ZTA) redefines how access is granted in contemporary applications. It doesn't take network location or a single login event into account – it demands the continuous validation of an identity, context, and intent.

Whereas perimeter-based models consider anyone inside a network "safe," zero-trust presumes every request can be compromised. This means that access decisions are made in real time over verified identity, device posture, and behavioral signals. In short, it’s a "security-first" approach designed for a cloud-native, threat-aware world.

Architecture Overview

Building a ZTA system means checking everyone and everything, all the time. The architecture you can see below demonstrates this "never trust, always verify" approach in action:

Image source: civilsdaily

Here's how it works:

• Every request gets checked: When anyone tries to access your network (from office, home, or mobile), they hit the authentication layer first. No exceptions.

• Identity + context verification: The system doesn't just check passwords. It looks at who you are, what device you're using, where you're connecting from, and what you're trying to access.

• Continuous protection: Once inside, the system keeps watching. It protects your data, devices, networks, people, and workloads through constant monitoring and access controls.

• The big change: Traditional security created a "trusted inside" and "untrusted outside." Zero-trust eliminates this boundary. Whether you're connecting to cloud services (AWS, Office 365) or internal systems, every request goes through the same verification process.

Multi-factor Authentication (MFA)

MFA is the foundation of zero-trust security. It requires users to prove who they are with multiple pieces of evidence before getting access. In ZTA, even the strongest password isn't enough on its own.

To begin, start with a strong password, then add a second factor. For example, Time-based One-Time Password (TOTP) is the most secure. TOTP is the best second factor because it works offline and doesn't rely on SMS or email (which can be intercepted). Apps like Google Authenticator generate a new code every 30 seconds.

Here’s an example of what that would look like:

const speakeasy = require('speakeasy');
const QRCode = require('qrcode');

// Generate TOTP secret for new user
function generateTOTPSecret(userEmail) {
  const secret = speakeasy.generateSecret({
    name: userEmail,
    issuer: 'YourApp',
    length: 32
  });

  return {
    secret: secret.base32,
    qrCodeUrl: secret.otpauth_url
  };
}

When a new user signs up, this function creates a unique secret key just for them. The name is their email, issuer is your app name, and length: 32 makes it extra secure. It returns two things: the secret key (in base32 format) and a special URL that creates a QR code for easy setup.

To verify the code from their app, you check it against the stored secret:

// Verify TOTP token
function verifyTOTP(token, secret) {
  return speakeasy.totp.verify({
    secret: secret,
    token: token,
    window: 2,
    encoding: 'base32'
  });
}

When the user enters their 6-digit code, this function checks if it's correct. The window: 2 is smart – it allows for timing differences (like if their phone clock is slightly off). It returns true if the code is valid, false if not.

SMS verification can serve as a backup option. It’s less secure than TOTP but can work as a backup. Always limit how many SMS codes someone can request to prevent abuse:

// SMS verification with rate limiting
async function sendSMSVerification(phoneNumber, userId) {
  const attempts = await getRecentSMSAttempts(userId);
  if (attempts >= 3) {
    throw new Error('Too many SMS attempts. Please try again later.');
  }

  const code = generateRandomCode(6);
  await storeSMSCode(userId, code, 300); // 5-minute expiry

  await smsProvider.send(phoneNumber, `Your verification code: ${code}`);
}

Before sending an SMS, it checks how many times this user has already requested codes. If they've tried 3 times, it blocks them (prevents spam/abuse). If they're under the limit, it creates a random 6-digit code, saves it for 5 minutes (300 seconds), then sends it via SMS.

But what happens if a user loses their phone or authenticator app? Backup codes provide emergency access:

// Generate backup codes
function generateBackupCodes(userId) {
  const codes = [];
  for (let i = 0; i < 10; i++) {
    codes.push(generateRandomCode(8));
  }

  const hashedCodes = codes.map(code => hashCode(code));
  storeBackupCodes(userId, hashedCodes);

  return codes; // Only show to user once
}

This creates 10 emergency backup codes (each 8 characters long). The for loop runs 10 times, creating a new random code each time. Before storing them in the database, it "hashes" them (scrambles them for security). Then it returns the original codes to show the user once, but stores the scrambled versions so even if someone hacks your database, they can't see the real codes.

JWT Token Management

JSON Web Tokens (JWTs) are stateless authentication in a zero-trust system. Using them safely is critical because you need to carefully think through payload design, implement short expiration policies, and implement token rotation and blocklisting that could prevent token theft, token reuse, or privilege escalation.

Let's walk through how to securely implement and manage JWTs in your web application.

First, define a minimal and secure structure for your access tokens. Only add information that’s necessary for making authorization decisions, and never put anything sensitive even if it is encrypted.

// JWT payload structure
const tokenPayload = {
  sub: userId,           // Subject (user ID)
  email: userEmail,      // User identifier
  roles: userRoles,      // User roles array
  permissions: userPermissions, // Specific permissions
  iat: Math.floor(Date.now() / 1000), // Issued at
  exp: Math.floor(Date.now() / 1000) + 900, // Expires in 15 minutes
  jti: generateUniqueId(), // JWT ID for blocklisting
  aud: 'your-app',       // Audience
  iss: 'your-auth-service' // Issuer
};

In the code above, the payload consists of the user identity, roles, permissions, and metadata such as the issued time (iat), expiration (exp), and unique token ID (jti). While aud and iss describe the token's origin and audience for validation, jti is used for revocation. Thus, it keeps the payload as lean as possible to minimize exposure and overhead.

For security and usability, it’s better to use access tokens with a short lifespan and refresh tokens with a considerably longer duration, which minimizes the window for potential utilization of compromised tokens while providing a smooth user session.

Let's take this example:

// Token generation service
class TokenService {
  generateTokenPair(user) {
    const accessToken = jwt.sign(
      this.createAccessTokenPayload(user),
      process.env.JWT_SECRET,
      { expiresIn: '15m', algorithm: 'HS256' }
    );

    const refreshToken = jwt.sign(
      { sub: user.id, type: 'refresh' },
      process.env.REFRESH_SECRET,
      { expiresIn: '7d', algorithm: 'HS256' }
    );

    return { accessToken, refreshToken };
  }

  async refreshAccessToken(refreshToken) {
    try {
      const decoded = jwt.verify(refreshToken, process.env.REFRESH_SECRET);

      // Check if refresh token is blocklisted
      if (await this.isTokenBlocklisted(decoded.jti)) {
        throw new Error('Token has been revoked');
      }

      const user = await getUserById(decoded.sub);
      return this.generateTokenPair(user);
    } catch (error) {
      throw new Error('Invalid refresh token');
    }
  }
}

generateTokenPair will generate two signed JWTs – that is, an access token with a 15-minute expiration and a refresh token with a validity of 7 days. The refresh tokens are verified to grant new ones and are checked against a blocklist. This ensures that revoked tokens can’t be reused, even if they’re still technically valid.

If you choose, a sliding session can be implemented to reduce friction by renewing tokens for an active user without violating your expiration strategy.

Now, let's implement a sliding session that automatically refreshes JWTs when they're close to expiring and the user is still active.

// Sliding session implementation
async function extendSessionIfActive(token) {
  const decoded = jwt.decode(token);
  const timeUntilExpiry = decoded.exp - Math.floor(Date.now() / 1000);

  // If token expires within 5 minutes and user is active, refresh
  if (timeUntilExpiry < 300 && await isUserActive(decoded.sub)) {
    const user = await getUserById(decoded.sub);
    return this.generateTokenPair(user);
  }

  return null;
}

The above function checks for token expiration. If the token expires within 5 minutes and the user continues to interact, a new access token pair is issued. This way, the session is kept alive during real activity but still forces expiration for idle users.

// Token blocklist service
class TokenBlocklistService {
  async blocklistToken(token) {
    const decoded = jwt.decode(token);
    const expiresAt = new Date(decoded.exp * 1000);

    // Store in Redis with automatic expiry
    await redis.setex(
      `blocklist:${decoded.jti}`,
      Math.max(0, Math.floor((expiresAt - Date.now()) / 1000)),
      'revoked'
    );
  }

  async isTokenBlocklisted(jti) {
    const result = await redis.get(`blocklist:${jti}`);
    return result !== null;
  }
}

In the above code, when users log out or tokens are compromised, the jti is stored in Redis with an expiration time of the remaining life of the token. You can block future uses of a token by checking if its ID exists on the blocklist. This allows for instant invalidation, even though JWTs are stateless.

Session Security

In zero-trust environments, session management goes far beyond keeping users logged in. A session must be treated as a constantly evaluated contract between the user, their device, and the system – and should be revoked the moment trust breaks down.

Here, we’ll build a session system that incorporates adaptive trust scoring, dynamic timeouts, real-time visibility, and revocation mechanisms – all aligned with zero-trust principles.

For example, when a user successfully authenticates, you don’t just store a session ID. Instead, you collect contextual metadata to evaluate ongoing risk. The function below demonstrates how to initialize a session that’s both secure and context-aware.

// Comprehensive session creation
async function createSecureSession(userId, deviceInfo, clientInfo) {
  const sessionId = generateSecureSessionId();

  const session = {
    id: sessionId,
    userId: userId,
    deviceFingerprint: generateDeviceFingerprint(deviceInfo),
    ipAddress: clientInfo.ipAddress,
    userAgent: clientInfo.userAgent,
    location: await resolveLocation(clientInfo.ipAddress),
    createdAt: new Date(),
    lastActivity: new Date(),
    trustScore: calculateInitialTrustScore(deviceInfo, clientInfo),
    securityLevel: determineSecurityLevel(userId, deviceInfo)
  };

  await storeSession(session);
  return session;
}

Many other tools are tracking concerning details during session creation. The device fingerprint, IP address, geolocation, and browser agent data are collected. These metadata are used to compute a trust score, and finally, a security level is assigned to the session to be used for dynamically adjusting policies later.

With this contextual information captured during session creation, the system can spot suspicious behavior during the sessions and, in turn, adapt policies like re-authentication of users or termination of the session.

Not all sessions should be treated equally. If a user logs in via an unfamiliar device or risky location, they should have less time for their session lifespan compared to a trusted setup's time. The following implementation changes timeout periods on the basis of trust and risk factors:

// Adaptive session timeout
class SessionTimeoutManager {
  calculateTimeoutPeriod(session) {
    const baseTimeout = 30 * 60 * 1000; // 30 minutes
    const trustMultiplier = session.trustScore / 100;
    const securityMultiplier = this.getSecurityMultiplier(session.securityLevel);

    return Math.max(
      5 * 60 * 1000, // Minimum 5 minutes
      baseTimeout * trustMultiplier * securityMultiplier
    );
  }

  async checkSessionValidity(sessionId) {
    const session = await getSession(sessionId);
    if (!session) return false;

    const now = Date.now();
    const timeout = this.calculateTimeoutPeriod(session);

    // Check both idle timeout and absolute timeout
    const idleExpired = (now - session.lastActivity) > timeout;
    const absoluteExpired = (now - session.createdAt) > 8 * 60 * 60 * 1000; // 8 hours max

    return !idleExpired && !absoluteExpired;
  }
}

The above code keeps session duration adaptable to the risk context at hand. The timeout is calculated by adjusting the base value according to trust and security level, while imposing minimum and maximum bounds.

The system then periodically intervenes to see if the session has become invalid due to inactivity (idle timeout) or simply outlives its initial duration (absolute timeout). This provides a more flexible yet enforceable way of mitigating the risk behind stale or hijacked sessions.

Zero-trust should also mean visibility across all access points. The user should be able to view all active sessions associated with their account, and security systems should also allow them to control these sessions in fine-grained detail. The following code lets you manage those active sessions across devices.

// Cross-device session management
class SessionManager {
  async getUserSessions(userId) {
    const sessions = await getActiveSessionsForUser(userId);

    return sessions.map(session => ({
      id: session.id,
      deviceType: this.identifyDeviceType(session.userAgent),
      location: session.location,
      lastActivity: session.lastActivity,
      current: session.id === currentSessionId
    }));
  }

  async revokeSession(sessionId, requestingSessionId) {
    const session = await getSession(sessionId);
    if (!session) throw new Error('Session not found');

    // Verify requesting session has permission
    const requestingSession = await getSession(requestingSessionId);
    if (requestingSession.userId !== session.userId) {
      throw new Error('Unauthorized');
    }

    await this.terminateSession(sessionId);
    await this.logSecurityEvent('session_revoked', session);
  }
}

Here, users fetch a list of their active sessions along with identifying information such as device type and location. Any session can be securely revoked by the user who owns it, preventing unauthorized access if the session ID is compromised.

This also allows the user to detect suspicious activities in time. All revocations are logged for auditing purposes to enable post-incident investigations as well as compliance reports.

When a trust breaks due to credential theft, suspicious activity, or user-level actions such as password reset, all sessions have to be immediately revoked. This example guarantees a full revocation, promptly applied to all devices:

// Real-time session revocation
class SessionRevocationService {
  async revokeAllUserSessions(userId, reason) {
    const sessions = await getActiveSessionsForUser(userId);

    // Blocklist all tokens for this user
    await Promise.all(sessions.map(session => 
      this.blocklistSessionTokens(session.id)
    ));

    // Notify all active clients
    await Promise.all(sessions.map(session => 
      this.notifySessionTermination(session.id, reason)
    ));

    // Clear session data
    await clearUserSessions(userId);

    // Log security event
    await this.logSecurityEvent('all_sessions_revoked', {
      userId,
      reason,
      sessionCount: sessions.length
    });
  }
}

The above code permits full-scale revocation. It blocklists all session tokens, sends out termination notices to active clients (for example, through WebSockets), clears the session records on the server-side, and logs the event for auditing. It is an instantaneous and complete response to compromised accounts or states where user risk is very high. It is the foremost component of real-time zero-trust enforcement in any serious authentication system.

Role-Based Access Control (RBAC)

Identity verification determines what users can access once they’re logged in. As the basis for any system that is aware of permissions and follows least privilege, RBAC doesn’t grant access on an individual basis – it groups users into roles that define the operations they are permitted to perform.

Before assigning roles to users, you need a structured system to define what each role can do. A set of granular permissions is first identified and then aggregated under these roles, optionally allowing inheritance and hierarchy. The code below shows how to build a basic permission system:

// RBAC permission system
class PermissionSystem {
  constructor() {
    this.permissions = new Map();
    this.roles = new Map();
    this.roleHierarchy = new Map();
  }

  // Define granular permissions
  definePermission(name, description, resource, action) {
    this.permissions.set(name, {
      name,
      description,
      resource,
      action,
      createdAt: new Date()
    });
  }

  // Create role with inherited permissions
  createRole(name, description, parentRole = null) {
    const role = {
      name,
      description,
      permissions: new Set(),
      createdAt: new Date()
    };

    // Inherit permissions from parent role
    if (parentRole && this.roles.has(parentRole)) {
      const parent = this.roles.get(parentRole);
      role.permissions = new Set(parent.permissions);
      this.roleHierarchy.set(name, parentRole);
    }

    this.roles.set(name, role);
    return role;
  }

  // Add permission to role
  addPermissionToRole(roleName, permissionName) {
    const role = this.roles.get(roleName);
    if (!role) throw new Error('Role not found');

    if (!this.permissions.has(permissionName)) {
      throw new Error('Permission not found');
    }

    role.permissions.add(permissionName);
  }
}

The code above lets you specify fine-grained permissions like documents.read.own and organizes them into roles such as employee or manager that you can independently reuse. You can define roles to inherit from other roles, which avoids redundancy and promotes a consistent, scalable access control logic.

As a general rule to avoid privilege creep, permissions should always be as fine-grained as possible. This lets the application refine access decisions to specific actions or scopes: for example, allowing users to read only their documents versus reading all documents for their team.

// Fine-grained permission definitions
const permissions = {
  // User management
  'users.read': { resource: 'users', action: 'read' },
  'users.create': { resource: 'users', action: 'create' },
  'users.update': { resource: 'users', action: 'update' },
  'users.delete': { resource: 'users', action: 'delete' },

  // Document management
  'documents.read.own': { resource: 'documents', action: 'read', scope: 'own' },
  'documents.read.team': { resource: 'documents', action: 'read', scope: 'team' },
  'documents.read.all': { resource: 'documents', action: 'read', scope: 'all' },
  'documents.create': { resource: 'documents', action: 'create' },
  'documents.update.own': { resource: 'documents', action: 'update', scope: 'own' },
  'documents.delete.own': { resource: 'documents', action: 'delete', scope: 'own' },

  // System administration
  'system.logs.read': { resource: 'system', action: 'read', subresource: 'logs' },
  'system.config.update': { resource: 'system', action: 'update', subresource: 'config' }
};