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' }
};

With an array of permissions at its disposal, the app can undertake very precise access control decisions. Instead of merely addressing the binary "is admin" question, this capability enables the system to answer questions such as "can this user delete their own document but not others?"

Static roles are often insufficient. You may want to give people temporary or conditional access, for example, when the team lead takes over for a manager or when a user approves a higher access level for the sake of incident response.

To support these cases, the RBAC system must allow dynamic role assignment – that is, the ability to assign roles on the basis of time, context, or an external trigger such as a security workflow.

The code below assigns a temporary role to a user, notes the exact time at which the role was assigned to the user, and periodically revokes the right after some fixed amount of time. Also, it has a method to calculate a user's complete set of active rights, depending on their permanent rights, temporary rights, and role-based contextual rights.

// Dynamic role assignment system
class DynamicRoleAssignment {
  async assignTemporaryRole(userId, roleName, duration, reason) {
    const assignment = {
      userId,
      roleName,
      assignedAt: new Date(),
      expiresAt: new Date(Date.now() + duration * 1000),
      reason,
      active: true
    };

    await this.storeRoleAssignment(assignment);
    await this.logRoleAssignment(assignment);

    // Schedule automatic revocation
    setTimeout(() => {
      this.revokeExpiredAssignment(assignment.id);
    }, duration * 1000);

    return assignment;
  }

  async getUserEffectivePermissions(userId, context = {}) {
    const user = await getUserById(userId);
    const permanentRoles = user.roles || [];
    const temporaryRoles = await this.getActiveTemporaryRoles(userId);
    const contextualRoles = await this.getContextualRoles(userId, context);

    const allRoles = [...permanentRoles, ...temporaryRoles, ...contextualRoles];
    const permissions = new Set();

    for (const roleName of allRoles) {
      const rolePermissions = await this.getRolePermissions(roleName);
      rolePermissions.forEach(permission => permissions.add(permission));
    }

    return Array.from(permissions);
  }
}

This allows for more flexible security configurations. Temporary roles that are granted have an automatic expiration. The context roles may be added dynamically depending on contextual factors such as location or type of device. Permanent roles are combined with temporary and context roles to compute the aggregate permission set for the user on a per-request basis, which maintains flexibility without compromising control.

Using Middleware to Enforce RBAC

The RBAC policies have to be enforced before any request reaches a protected route or protected data. Middleware is a good place to run such checks in the scope of a web application. We’ll now look into how the reusable middleware function for authorization works.

// Authorization middleware
function createAuthorizationMiddleware(requiredPermission) {
  return async (req, res, next) => {
    try {
      // Extract user from validated JWT
      const user = req.user;
      if (!user) {
        return res.status(401).json({ error: 'Authentication required' });
      }

      // Get user's effective permissions
      const context = {
        ipAddress: req.ip,
        userAgent: req.get('User-Agent'),
        resourceId: req.params.id,
        timestamp: new Date()
      };

      const permissions = await roleSystem.getUserEffectivePermissions(
        user.id,
        context
      );

      // Check if user has required permission
      if (!permissions.includes(requiredPermission)) {
        await logUnauthorizedAccess(user.id, requiredPermission, context);
        return res.status(403).json({ error: 'Insufficient permissions' });
      }

      // Add permissions to request for downstream use
      req.userPermissions = permissions;
      next();
    } catch (error) {
      res.status(500).json({ error: 'Authorization check failed' });
    }
  };
}

// Usage in routes
app.get('/api/users', 
  authenticateToken,
  createAuthorizationMiddleware('users.read'),
  getUsersController
);

In the code above, the middleware will validate user identities in real-time, check if adequate permissions are granted, and allow or deny access accordingly. It’s a central mechanism for enforcing access rules in a uniform way across your routes, and it even records unauthorized attempts for auditing.

Testing Access Control Logic

Once you’ve implemented the RBAC system, testing becomes a must. You want to guarantee that permissions are inherited properly, that access is actually denied when a user isn’t authorized, and that your roles behave as designed in the real world as well as in edge-case scenarios.

The following example uses a testing framework to demonstrate the verification of two fundamental behaviors: inheritance of permissions from parent roles and rejection of unauthorized access.

// RBAC testing suite
describe('RBAC System', () => {
  test('should inherit permissions from parent roles', async () => {
    const manager = await roleSystem.createRole('manager', 'Team Manager', 'employee');
    await roleSystem.addPermissionToRole('manager', 'team.manage');

    const permissions = await roleSystem.getRolePermissions('manager');
    expect(permissions).toContain('documents.read.own'); // From employee
    expect(permissions).toContain('team.manage'); // Manager-specific
  });

  test('should deny access without proper permissions', async () => {
    const user = { id: 1, roles: ['employee'] };
    const req = { user, params: { id: 'doc123' } };
    const res = { status: jest.fn().mockReturnThis(), json: jest.fn() };

    const middleware = createAuthorizationMiddleware('documents.delete.all');
    await middleware(req, res, () => {}); // Middleware call simulating request

    expect(res.status).toHaveBeenCalledWith(403);
  });
});

The tests represent the positive and negative validations of the access rules. The first test determines whether inherited permissions flow freely from the parent to child roles. The second test blocks any user without the required permission, returning a status code appropriately.

Over time, you can enrich test coverage to include temporary role assignments, contextual conditions, and session-aware behavior to alert you to any regressions before they start affecting production access.

Continuous Verification

Modern access security is not a one-shot check but an ongoing process. A strong system must continuously verify user identity and context throughout the ongoing session while adapting to newly emerging risk signals.

In continuous verification, it’s an assurance that access stays appropriate while the user behavior, device posture, or environment changes mid-session.

To uniquely identify a device, you can combine subtle traits like browser settings, hardware specs, and plugin data. This forms a device “fingerprint,” which helps flag new or suspicious devices attempting access.

// Advanced device fingerprinting
class DeviceFingerprintService {
  generateFingerprint(deviceInfo) {
    const components = [
      deviceInfo.userAgent,
      deviceInfo.screenResolution,
      deviceInfo.timezone,
      deviceInfo.language,
      deviceInfo.platform,
      deviceInfo.hardwareConcurrency,
      deviceInfo.memorySize,
      deviceInfo.availableFonts?.join(','),
      deviceInfo.plugins?.map(p => p.name).join(','),
      deviceInfo.webglRenderer,
      deviceInfo.audioContext
    ];

    return this.hashComponents(components);
  }

  calculateTrustScore(currentFingerprint, knownFingerprints) {
    if (knownFingerprints.length === 0) return 50; // Neutral for new device
    const similarities = knownFingerprints.map(known =>
      this.calculateSimilarity(currentFingerprint, known)
    );
    return Math.min(100, Math.max(...similarities) * 100);
  }

  async updateDeviceTrust(userId, deviceFingerprint, securityEvents) {
    const device = await this.getOrCreateDevice(userId, deviceFingerprint);
    let trustAdjustment = 0;

    securityEvents.forEach(event => {
      switch (event.type) {
        case 'successful_login': trustAdjustment += 5; break;
        case 'failed_login': trustAdjustment -= 10; break;
        case 'suspicious_activity': trustAdjustment -= 25; break;
      }
    });

    device.trustScore = Math.max(0, Math.min(100, device.trustScore + trustAdjustment));
    await this.updateDevice(device);
    return device.trustScore;
  }
}

Generating a fingerprint hash from device traits, this service uses historical events to dynamically adjust the device's trust score. Step-up authentication may be prompted by low scores, or access may be denied altogether.

Behavioral Analysis

People tend to use apps rather consistently – they type a certain way, move the mouse in a particular manner, or browse varied content. Behavioral analysis tries to detect that anomaly by comparing ongoing activities to known ones.

// Behavioral analysis system
class BehaviorAnalysisService {
  async analyzeUserBehavior(userId, currentSession) {
    const historicalBehavior = await this.getUserBehaviorProfile(userId);
    const anomalies = [];

    const typingAnomaly = this.analyzeTypingPatterns(
      currentSession.typingData,
      historicalBehavior.typingProfile
    );
    if (typingAnomaly.score > 0.7) {
      anomalies.push({ type: 'typing_pattern', score: typingAnomaly.score, details: typingAnomaly.details });
    }

    const navigationAnomaly = this.analyzeNavigationPatterns(
      currentSession.navigationData,
      historicalBehavior.navigationProfile
    );
    if (navigationAnomaly.score > 0.6) {
      anomalies.push({ type: 'navigation_pattern', score: navigationAnomaly.score, details: navigationAnomaly.details });
    }

    const timeAnomaly = this.analyzeTimePatterns(
      currentSession.timestamp,
      historicalBehavior.timeProfile
    );
    if (timeAnomaly.score > 0.5) {
      anomalies.push({ type: 'time_pattern', score: timeAnomaly.score, details: timeAnomaly.details });
    }

    return {
      overallRiskScore: this.calculateOverallRisk(anomalies),
      anomalies,
      recommendations: this.generateRecommendations(anomalies)
    };
  }

  analyzeTypingPatterns(currentData, historicalProfile) {
    if (!currentData || !historicalProfile) return { score: 0 };
    const dwellTimeVariance = this.calculateVariance(currentData.dwellTimes, historicalProfile.averageDwellTime);
    const flightTimeVariance = this.calculateVariance(currentData.flightTimes, historicalProfile.averageFlightTime);
    const score = Math.max(dwellTimeVariance, flightTimeVariance);
    return { score, details: { dwellTimeVariance, flightTimeVariance, sampleSize: currentData.keystrokes.length } };
  }
}

This will detect suspicious changes in user behavior and typing characteristics as early warning indicators of session hijacking or insider threat.

Access from a new country or city can either be harmless or highly suspicious. Comparing login geography against historical patterns helps flag impossible travel or access from banned regions.

// Location-based access control
class LocationAccessControl {
  async validateLocationAccess(userId, ipAddress, session) {
    const location = await this.resolveLocation(ipAddress);
    const user = await getUserById(userId);
    const historicalLocations = await this.getUserLocations(userId);
    const locationRisk = this.assessLocationRisk(location, historicalLocations);

    const lastLocation = await this.getLastKnownLocation(userId);
    if (lastLocation) {
      const impossibleTravel = this.checkImpossibleTravel(lastLocation, location, session.lastActivity);
      if (impossibleTravel.detected) {
        await this.logSecurityEvent('impossible_travel', {
          userId, fromLocation: lastLocation, toLocation: location,
          timeWindow: impossibleTravel.timeWindow,
          minimumTravelTime: impossibleTravel.minimumTravelTime
        });
        return { allowed: false, reason: 'impossible_travel', requiresStepUp: true };
      }
    }

    if (user.allowedCountries && !user.allowedCountries.includes(location.country)) {
      return { allowed: false, reason: 'country_restriction', requiresStepUp: true };
    }

    const highRiskCountries = ['XX', 'YY', 'ZZ'];
    if (highRiskCountries.includes(location.country)) {
      return { allowed: true, reason: 'high_risk_location', requiresStepUp: true, additionalVerification: ['sms', 'email'] };
    }

    return { allowed: true, riskScore: locationRisk, location };
  }

  checkImpossibleTravel(fromLocation, toLocation, lastActivity) {
    const distance = this.calculateDistance(fromLocation, toLocation);
    const timeElapsed = Date.now() - lastActivity;
    const maximumSpeed = 900; // km/h
    const minimumTravelTime = (distance / maximumSpeed) * 3600000;
    return { detected: timeElapsed < minimumTravelTime, timeWindow: timeElapsed, minimumTravelTime, distance };
  }
}

This logic prevents abuse via VPNs or stolen credentials by requiring step-up verification when impossible travel or unusual locations are detected.

Step-Up Authentication

Step-up security introduces friction only when truly needed. With lower risk considered, users move freely. When risk levels rises, they're asked for stronger proofs, such as biometrics or hardware tokens.

// Step-up authentication system
class StepUpAuthenticationService {
  async evaluateStepUpRequirement(userId, requestContext, resourceSensitivity) {
    const riskFactors = await this.calculateRiskFactors(userId, requestContext);
    const stepUpRequired = this.shouldRequireStepUp(riskFactors, resourceSensitivity);

    if (stepUpRequired.required) {
      return {
        required: true,
        methods: this.selectAuthenticationMethods(riskFactors, stepUpRequired.level),
        expiresIn: this.calculateStepUpDuration(stepUpRequired.level),
        reason: stepUpRequired.reason
      };
    }

    return { required: false };
  }

  async calculateRiskFactors(userId, context) {
    return {
      deviceTrust: await this.getDeviceTrustScore(userId, context.deviceFingerprint),
      locationRisk: await this.getLocationRiskScore(userId, context.ipAddress),
      behaviorAnomaly: await this.getBehaviorAnomalyScore(userId, context.sessionData),
      timeSinceLastAuth: Date.now() - context.lastAuthTime,
      resourceSensitivity: context.resourceSensitivity || 'medium'
    };
  }

  shouldRequireStepUp(riskFactors, sensitivity) {
    let score = 0;
    if (riskFactors.deviceTrust < 70) score += 30;
    if (riskFactors.deviceTrust < 40) score += 20;
    if (riskFactors.locationRisk > 0.6) score += 25;
    if (riskFactors.locationRisk > 0.8) score += 15;
    if (riskFactors.behaviorAnomaly > 0.5) score += 20;
    if (riskFactors.behaviorAnomaly > 0.7) score += 10;
    const hours = riskFactors.timeSinceLastAuth / (1000 * 60 * 60);
    if (hours > 8) score += 10;
    if (hours > 24) score += 15;

    score *= { low: 0.7, medium: 1.0, high: 1.3, critical: 1.6 }[sensitivity] || 1.0;

    if (score >= 80) return { required: true, level: 'high', reason: 'high_risk_detected' };
    if (score >= 50) return { required: true, level: 'medium', reason: 'moderate_risk_detected' };
    if (score >= 25) return { required: true, level: 'low', reason: 'low_risk_detected' };
    return { required: false };
  }

  selectAuthenticationMethods(riskFactors, level) {
    const methods = [];
    if (level === 'high') {
      methods.push('hardware_token', 'biometric');
      if (riskFactors.deviceTrust < 30) methods.push('admin_approval');
    } else if (level === 'medium') {
      methods.push('totp', 'sms');
      if (riskFactors.locationRisk > 0.7) methods.push('email_verification');
    } else if (level === 'low') {
      methods.push('totp');
    }
    return methods;
  }
}

The service uses this balancing technique between critical resources and risks while keeping normal workflows intact when things look safe.

Security Monitoring

Security monitoring provides the observability layer that’s essential for detecting, analyzing, and responding to threats in real time. A strong system must log every authentication event, highlight anomalies, and allow for rapid and automated response to threats. This phase further builds trust by constantly evaluating access patterns and acting on them when signals of risk emerge.

Logging is visibility at its base. These days, every authentication attempt, be it successful, failed, or suspicious, needs to be logged with exhaustive context. This very information helps forensic analysis, alerting, and compliance reporting.

// Comprehensive authentication event logging
class AuthenticationLogger {
  async logAuthenticationEvent(eventType, userId, context, result) {
    const logEntry = {
      timestamp: new Date().toISOString(),
      eventType,
      userId,
      sessionId: context.sessionId,
      ipAddress: context.ipAddress,
      userAgent: context.userAgent,
      deviceFingerprint: context.deviceFingerprint,
      location: context.location,
      authenticationMethod: context.authMethod,
      result: result.success ? 'success' : 'failure',
      failureReason: result.failureReason,
      riskScore: result.riskScore,
      additionalFactorsRequired: result.stepUpRequired,
      processingTime: result.processingTime,
      correlationId: context.correlationId
    };

    // Store in multiple destinations for redundancy
    await Promise.all([
      this.writeToDatabase(logEntry),
      this.sendToLogAggregator(logEntry),
      this.updateRealTimeMetrics(logEntry)
    ]);

    // Trigger real-time alerts for critical events
    if (this.isCriticalEvent(logEntry)) {
      await this.triggerSecurityAlert(logEntry);
    }
  }

  isCriticalEvent(logEntry) {
    const criticalConditions = [
      logEntry.result === 'failure' && logEntry.failureReason === 'brute_force_detected',
      logEntry.riskScore > 80,
      logEntry.eventType === 'impossible_travel_detected',
      logEntry.eventType === 'account_takeover_suspected'
    ];

    return criticalConditions.some(condition => condition);
  }

  async generateSecurityReport(userId, timeRange) {
    const events = await this.getAuthenticationEvents(userId, timeRange);

    const analysis = {
      totalEvents: events.length,
      successfulLogins: events.filter(e => e.result === 'success').length,
      failedAttempts: events.filter(e => e.result === 'failure').length,
      uniqueDevices: new Set(events.map(e => e.deviceFingerprint)).size,
      uniqueLocations: new Set(events.map(e => e.location?.country)).size,
      averageRiskScore: events.reduce((sum, e) => sum + e.riskScore, 0) / events.length,
      timePatterns: this.analyzeTimePatterns(events),
      locationPatterns: this.analyzeLocationPatterns(events),
      devicePatterns: this.analyzeDevicePatterns(events)
    };

    return analysis;
  }
}

In the above code, the class logs detailed authentication events such as the approximate device and location from which it was initiated, the authentication methods used, and the risk score.

From a security perspective, it’s envisaged to generate security reports with the advantage of flagging critical events such as brute-force attempts or logins from suspicious geographies that can send real-time alerts.

Monitoring authentication events isn’t enough – the system must be able to interpret patterns and flag suspicious behavior. This detection system combines static rule-based checks with dynamic anomaly detection powered by machine learning. It identifies threats like brute-force attacks, credential stuffing, and unusual geographic access, then escalates them automatically for further action.

The following code performs real-time threat detection by analyzing recent authentication events and contextual data. Here's what it does, broken down clearly:

// Suspicious activity detection system
class SuspiciousActivityDetector {
  constructor() {
    this.detectionRules = this.initializeDetectionRules();
    this.mlModel = this.loadAnomalyDetectionModel();
  }

  async analyzeActivity(userId, recentEvents, context) {
    const suspiciousPatterns = [];

    // Rule-based detection
    const ruleViolations = await this.checkDetectionRules(userId, recentEvents);
    suspiciousPatterns.push(...ruleViolations);

    // ML-based anomaly detection
    const anomalies = await this.detectAnomalies(userId, recentEvents, context);
    suspiciousPatterns.push(...anomalies);

    // Threat intelligence correlation
    const threatMatches = await this.correlateThreatIntelligence(context);
    suspiciousPatterns.push(...threatMatches);

    if (suspiciousPatterns.length > 0) {
      await this.escalateSuspiciousActivity(userId, suspiciousPatterns);
    }

    return {
      suspicious: suspiciousPatterns.length > 0,
      patterns: suspiciousPatterns,
      riskScore: this.calculateSuspiciousActivityRisk(suspiciousPatterns)
    };
  }

  initializeDetectionRules() {
    return [
      {
        name: 'brute_force_detection',
        condition: (events) => {
          const failedAttempts = events.filter(e =>
            e.result === 'failure' &&
            Date.now() - new Date(e.timestamp).getTime() < 300000 // 5 minutes
          );
          return failedAttempts.length >= 5;
        },
        severity: 'high',
        action: 'temporary_lockout'
      },
      {
        name: 'credential_stuffing',
        condition: (events) => {
          const recentFailures = events.filter(e =>
            e.result === 'failure' &&
            Date.now() - new Date(e.timestamp).getTime() < 3600000 // 1 hour
          );
          const uniqueUsernames = new Set(recentFailures.map(e => e.username));
          return uniqueUsernames.size >= 10;
        },
        severity: 'medium',
        action: 'rate_limiting'
      },
      {
        name: 'suspicious_location_pattern',
        condition: (events) => {
          const locations = events.map(e => e.location?.country).filter(Boolean);
          const uniqueCountries = new Set(locations);
          return uniqueCountries.size >= 3 && events.length >= 5;
        },
        severity: 'medium',
        action: 'enhanced_verification'
      }
    ];
  }

  async detectAnomalies(userId, events, context) {
    const features = this.extractFeatures(events, context);
    const anomalyScore = await this.mlModel.predict(features);

    if (anomalyScore > 0.7) {
      return [{
        type: 'ml_anomaly',
        score: anomalyScore,
        features: features,
        description: 'Machine learning model detected anomalous behavior pattern'
      }];
    }

    return [];
  }
}

This class applies multiple techniques to detect threats. It first evaluates authentication history using static rules for brute-force attempts, large-scale credential reuse, or location anomalies. It then passes behavioral data through a trained ML model to spot subtle patterns missed by rules. If any suspicious pattern is detected, it returns a structured risk report and initiates escalation.

Automating Threat Response

Most times, systems respond in real-time. Automated threat response follows predefined actions and includes locking an account, alerting users, or blocking an IP, among others, when a high-risk event occurs.

// Automated threat response system
class AutomatedThreatResponse {
  constructor() {
    this.responsePlaybooks = this.initializeResponsePlaybooks();
    this.escalationPolicies = this.loadEscalationPolicies();
  }

  async processSecurityEvent(event) {
    const threatLevel = this.assessThreatLevel(event);
    const applicablePlaybooks = this.selectPlaybooks(event, threatLevel);

    const responses = [];
    for (const playbook of applicablePlaybooks) {
      const response = await this.executePlaybook(playbook, event);
      responses.push(response);
    }

    if (threatLevel === 'critical' || responses.some(r => !r.success)) {
      await this.escalateToHuman(event, responses);
    }

    return {
      event,
      threatLevel,
      responses,
      timestamp: new Date()
    };
  }

  initializeResponsePlaybooks() {
    return [
      {
        name: 'brute_force_response',
        triggers: ['brute_force_detected'],
        actions: [
          { type: 'temporary_lockout', duration: 900 },
          { type: 'rate_limiting', factor: 10 },
          { type: 'notify_user', method: 'email' },
          { type: 'log_security_event', level: 'high' }
        ]
      },
      {
        name: 'account_takeover_response',
        triggers: ['impossible_travel', 'behavior_anomaly_high'],
        actions: [
          { type: 'terminate_all_sessions' },
          { type: 'require_password_reset' },
          { type: 'notify_user', method: 'multiple' },
          { type: 'freeze_account', duration: 7200 }
        ]
      }
    ];
  }

  async executePlaybook(playbook, event) {
    const execution = {
      playbookName: playbook.name,
      eventId: event.id,
      actions: [],
      success: true
    };

    for (const action of playbook.actions) {
      try {
        const result = await this.executeAction(action, event);
        execution.actions.push(result);
        if (!result.success) {
          execution.success = false;
          break;
        }
      } catch (err) {
        execution.success = false;
        execution.error = err.message;
      }
    }

    return execution;
  }

  async executeAction(action, event) {
    switch (action.type) {
      case 'temporary_lockout':
        await this.lockoutUser(event.userId, action.duration);
        return { success: true, type: action.type };
      case 'notify_user':
        await this.notifyUser(event.userId, action.method, event);
        return { success: true, type: action.type };
      default:
        return { success: false, type: action.type, error: 'Unknown action' };
    }
  }
}

Here, the system uses playbooks – predefined actions to be taken in response to threats. For example, locks user from further brute-force attempts for some time and sends them an email notification. Freezing the account and ending all sessions are some reactive measures you can take if suspicious behavior indicates a takeover. These measures ensure fast and consistent action to mitigate damage even before humans can get involved.

Conclusion

Zero-trust authentication creates a strong line of distinction going against classic perimeter-based security. It must be painstakingly planned, implemented in layers, and constantly improved. This article offers a structured path, from basic MFA to intelligent behavioral monitoring and automated threat response.

Complementing the improvement of security, zero-trust promises better user experience, compliance readiness, and decreased incident risk. When organizations maintain a perpetual position of zero trust, we can see an actual positive impact on their ability to detect, prevent, and respond to threats in real time.

To have long-term success with this approach, you’ll need to continuously monitor your setup, perform periodic assessments, and be responsive to evolving attack patterns. Feedback loops and performance data are essential to keep the system secure yet user-friendly.

As threats grow more sophisticated, so must our defenses. ZTA provides a durable foundation – ready to evolve with emerging technologies like adaptive biometrics and AI-driven risk engines. Organizations investing in it today will be better equipped to meet tomorrow’s security and usability demands.

In this article, you'll learn about:

• What a JSON Web Token (JWT) is

• How JWTs are structured and created

• Different JWT signing techniques and algorithms (Symmetric vs. Asymmetric)

• How JWTs are used in real-world authentication flows

• Important security best practices for using JWTs

Table of Contents

• What is a JWT?

  • JSON Web Tokens Are Made Of Three Elements

  • Asymmetric Signing (RS256) Explained

  • Analogy: The Lock and Key for Asymmetric Signatures

• Symmetric Signing: HS256 (HMAC with SHA-256)

  • How HS256 Verification Works

• JWTs in Action: A Typical Authentication Flow

• JWT Security Best Practices & Considerations

What Is a JWT?

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA or ECDSA.
— Introduction to JWT by jwt.io

While accurate, this definition can be a bit dense at first glance. Imagine you want to send someone a sealed, tamper-proof message. That's essentially what a JSON Web Token (JWT) is. It's a secure message, a special kind of message designed to be sent between two parties which can be assured it came from an expected sender.

Each JWT is digitally signed using either a secret code (for symmetric algorithms like HMAC) or a private key (for asymmetric algorithms like RSA or ECDSA).

This secret code or private key is known only to the system that issues the JWT (often called an authentication provider, like Auth0, AWS Cognito, or Firebase Auth, which handles user logins and identity).

This signature proves two things:

1. Authenticity: It proves the message really came from who it claims to be from.

2. Integrity: It proves that the message hasn't been changed or tampered with since it was signed. If even one character is altered, the signature won't match, and you'll know something is wrong, meaning the contents of the JWT can't be trusted.

JSON Web Tokens Are Made of Three Elements

JWTs are made up of 3 key parts:

1. Header

2. Payload

3. Signature

Header

The header contains metadata information about the token. Think of it like a label on a package – it tells you what’s inside and how it was prepared.

Typically, the header contains:

alg: This specifies the algorithm used to sign the JWT. Common algorithms are HS256 (HMAC with SHA-256) or RS256 (RSA with SHA-256).

typ: This specifies the type of token, which is almost always JWT for standard JSON Web Tokens.

Example (decoded):

{ 
  "alg": "RS256",
  "typ": "JWT" 
}

Payload

This is the second part of the JWT, and it's where the real data or "claims" are stored. Claims are statements about an entity (usually a user) and any other additional data. Using the previous analogy of a package, think of it as the “contents” of the package.

There are three types of claims:

1. Registered Claims: These are predefined claims that are recommended for common use cases. They are not mandatory but are very useful for interoperability. These include:

• iss – issuer, who issued the token (for example, your application’s domain)

• sub – subject, the subject of the token (for example, a User’s ID)

• aud – audience, the audience of the token (that is, who the token is intended for – for example, a specific API)

• exp – expiration, the expiry date as a timestamp

• iat – issued at, when the token was issued as a timestamp

• nbf – not before, when the token becomes valid (that is, the token cannot be used or deemed valid before this timestamp)

• jti – JWT ID, a unique identifier for the token, useful for preventing replay attacks or blacklisting

2. Public Claims: These can be defined by anyone using JWTs. To avoid naming conflicts, it's a good practice to register them or define them using a unique identifier like a URI.

3. Private Claims: These are custom claims created to share specific information between parties who agree on using them. They are entirely up to you and your application's needs.

Example payload:

{
  "sub": "1234567890", //  subject
  "name": "John Doe", // private claim
  "admin": true, // private claim / role
  "iat": 1678886400, // Issued at a specific timestamp
  "exp": 1678890000  // Expires at a specific timestamp
}

Like the header, this JSON object is also Base64Url encoded (a URL-safe variant of Base64 encoding) to form the second part of the JWT string.

Important Note: The payload is encoded*, not encrypted.* This means that anyone can easily decode the JWT and read its contents. Never put sensitive information (like passwords) directly into the payload unless the entire JWT itself is encrypted (which is a separate process called JWE - JSON Web Encryption). The security of a standard JWT comes entirely from the signature, which prevents tampering.

Signature

The signature, as we've already discussed, is the most important part of the JWT. Without it, there's no protection applied to the JWT, meaning no way to validate the origin of the token or its integrity.

The signature is created by taking the encoded header, the encoded payload, and a secret key (or a private key if using asymmetric algorithms like RSA). These are then run through the cryptographic algorithm specified in the header (alg field). For HS256, a shared secret key is used. For RS256, a private key is used to sign, and a corresponding public key is used to verify. We’ll get on to verification soon.

Think of it like a tamper-proof seal on your package, or even better, a wax seal on a letter. If you receive your letter and the wax seal has been broken, you'd naturally believe the contents of the letter may not be original and therefore can't be trusted.

In pseudo-code it would look like this:

Signature = Algorithm( Base64Url(Header) + "." + Base64Url(Payload), SecretKey )

The result of this signing process is the signature, which is also Base64Url encoded to form the third part of the JWT string.

At the end of the whole process your JWT would look like this:

base64EncodedHeader.base64EncodedPayload.base64EncodedSignature

Asymmetric Signing (RS256) Explained

When a JWT uses an algorithm like RS256 (RSA Signature with SHA-256), it employs an asymmetric cryptographic process involving a public and private key pair. This is where the core magic of proving authenticity and integrity happens without needing to share a secret.

The Signing Process (by the Issuer)

The sender (the server that issues the JWT, like Auth0) possesses the private key. This key is kept absolutely secret and secure. Here are the steps:

1. Prepare the data: The server takes the header (which includes the algorithm) and the payload. It Base64Url-encodes them, and then concatenates them with a dot: Base64Url(Header) + "." + Base64Url(Payload).

   For example, with this header:

    {
      "typ": "JWT",
      "alg": "RS256"
    }
   

   And this payload:

    {
      "sub": "1234567890",
      "name": "John Doe",
      "admin": true,
      "iat": 1751494086,
      "exp": 1751497686
    }
   

   This would create a Base64Url-encoded header.payload string like the animated example below:

   

2. Calculate the hash: It then calculates a hash (using SHA-256 in this case) of this combined header and payload string.

3. Sign the hash: Finally, it signs this hash using its private key. This cryptographically transformed hash is the signature part of the JWT.

The JWT is then formed by concatenating the Base64Url-encoded header, the Base64Url-encoded payload, and the Base64Url-encoded signature, separated by dots: header.payload.signature.

The top segment below shows the full JWT token (header.payload.signature):

The Verification Process

This is where the magic happens, and it's often a point of confusion. The public key doesn't "decrypt" the original data like a symmetric key does. Instead, it performs a unique verification process.

The receiver (the client or another server that needs to verify the JWT) possesses the public key. This key does not need to be kept secret – it can be freely distributed.

Here's a step-by-step explanation:

1. Separate the parts: The first thing the receiver does is split the incoming JWT string into its three Base64Url-encoded components: the Header, the Payload, and the Signature.

2. Obtain the public key: The verifier needs the public key that corresponds to the private key used by the issuer. Public keys are often available via a JWKS (JSON Web Key Set) endpoint (for example, your-domain.com/.well-known/jwks.json).

3. Re-create the data to be hashed: The receiver takes the received, Base64Url-encoded Header and the received, Base64Url-encoded Payload. It then combines them exactly as the issuer did: EncodedHeader.EncodedPayload.

4. Compute a local hash (Hash A): This combined string is then put through the same hashing algorithm (for example, SHA-256) that was specified in the JWT's header. This produces a new, locally computed hash (let's call this "Hash A"). This local hash represents what the content should look like if it hasn't been tampered with.

5. "Unsign" the received signature with the public key to get the original signed hash (Hash B): This is the core cryptographic step. The verifier uses the public key (obtained in step 2) to perform a mathematical operation on the received signature. This operation does not create a new signature for comparison. Instead, it effectively "unsigns" or "decrypts" the signature to reveal the original hash ("Hash B") that was produced by the issuer's private key.

   • Crucial Point: This process is for verifying authenticity, not decrypting confidential data. The public key confirms that the signature was indeed created by the corresponding private key, and as part of that confirmation, it returns the original hash that was signed.

6. Compare the hashes: The verifier now has two hashes:

   • Hash A: The hash it computed locally from the received header and payload (from step 4).

   • Hash B: The original hash that was extracted from the received Signature using the public key (from step 5)

7. If Hash A matches Hash B: It proves two critical things:

   1. Authenticity: The token was indeed signed by the legitimate holder of the corresponding private key (for example, Auth0).

   2. Integrity: The content of the header and payload has not been tampered with since it was originally signed. If even a single character in the header or payload were changed, Hash A would be different, and it would not match Hash B. In this case, the JWT is considered valid and its contents can be trusted.

8. If the hashes do NOT match: The token is considered invalid and must be rejected. This indicates either that the JWT was signed by an unauthorised party (a forged token) or that its header or payload has been altered after it was signed.

Analogy: The Lock and Key for Asymmetric Signatures

Private Key: A special, unique key that can lock a box (create a signature). Only the owner has this key.

Public Key: A widely distributed key that can test if a box was locked by the corresponding private key. It can't lock a new box, but it can confirm if an existing lock is authentic.

You don't re-lock the box with the public key. You use the public key to check if the existing lock (the signature) is genuine and corresponds to the contents of the box.

Symmetric Signing: HS256 (HMAC With SHA-256)

While RS256 uses a pair of keys (private for signing, public for verifying), many JWTs you'll encounter are signed symmetrically, most commonly with the HS256 algorithm. HS256 stands for HMAC (Hash-based Message Authentication Code) with SHA-256.

The fundamental difference here is the use of a single, shared secret key for both signing and verification.

How HS256 Signing Works

1. Shared secret key: The issuer (for example, your authentication provider) possesses a single, confidential secret key. This key is known only to the issuer and any parties (like your API) that need to verify the token.

2. Combine header and payload: Just like with asymmetric signing, the issuer takes the Base64Url-encoded Header (which specifies "alg": "HS256") and the Base64Url-encoded Payload, and joins them with a dot.

3. Apply HMAC-SHA256: This combined string is then fed into the HMAC-SHA256 algorithm along with the secret key. The HMAC algorithm uses the secret key to create a unique hash (the signature) of the data. In pseudo-code, it looks like this:

   Signature = HMAC-SHA256( Base64Url(Header) + "." + Base64Url(Payload), SecretKey )

4. Form the JWT: The resulting signature (which is also Base64Url-encoded) is appended to the header and payload with a dot, forming the complete JWT: base64EncodedHeader.base64EncodedPayload.base64EncodedSignature.

How HS256 Verification Works

When a receiver gets an HS256-signed JWT, it goes through a verification process.

First, it separates the parts. The JWT is split into its three Base64Url-encoded components: Header, Payload, and Signature, as we did with asymmetric JWTs.

Then, it obtains the shared secret key. The receiver must also possess the exact same secret key that the issuer used to sign the token. This key is not publicly distributed like a public key – it must be securely provisioned to any entity that needs to verify tokens.

Next, it re-calculates the signature. The receiver does this by taking the received Base64Url-encoded Header and Payload, combining them, and then re-applying the HMAC-SHA256 algorithm using the same secret key. This produces a new, locally computed signature.

Finally, the receiver compares the signature it just calculated locally with the signature it received as part of the JWT.

• If the two signatures match: The token is considered valid. This confirms its authenticity (it came from someone who knows the secret) and integrity (it hasn't been tampered with).

• If the signatures do NOT match: The token is invalid and must be rejected. This indicates either tampering or that it was signed with a different, unknown secret key.

Key Differences and Considerations:

• Key management: With HS256, the secret key must be securely shared and kept confidential by all parties involved in both signing and verifying. This can be more challenging to manage securely at scale compared to the public/private key model, where only the private key needs strict secrecy.

• Performance: HS256 is generally faster to compute than asymmetric algorithms like RS256, making it suitable for high-volume scenarios where the secret key can be securely distributed.

JWTs in Action: A Typical Authentication Flow

Now that you understand how JWTs are structured and signed, let's look at how they're typically used in a real-world web application. This authentication flow is a common pattern you'd encounter.

Step 1: User Logs In:

A user opens a client application (for example, a web browser, mobile app) and enters their login credentials (username and password).

The client sends these credentials securely (always over HTTPS!) to an authentication server (like Auth0, AWS Cognito, or your own backend's authentication endpoint).

Step 2: Authentication Server Issues JWT:

Then the authentication server verifies the user's credentials. If valid, it generates a new JWT. This JWT contains claims (like the user's ID, roles, expiration time) in its payload and is digitally signed by the server's private key (for asymmetric algorithms like RS256) or secret key (for symmetric algorithms like HS256).

The server then sends this signed JWT back to the client.

Step 3: Client Stores JWT:

The client receives the JWT and typically stores it in a secure location, such as browser memory storage, session storage, or an HTTP-only cookie. The method of storage depends on the client type and security considerations.

Step 4: Client Makes API Calls:

When the user wants to access a protected resource on a backend API (for example, their profile data, a private feed), the client includes the JWT in the request.

The standard way to do this is by sending the token in the Authorization header of the HTTP request, prefixed with the word Bearer:

Authorization: Bearer <your_jwt_here>

Step 5: API Verifies JWT & Authorises Request:

Now, the backend API receives the request and extracts the JWT from the Authorization header. The API then performs the JWT verification process depending on the algorithm:

• It checks the token's claims, especially the exp (expiration) claim, to ensure it's still valid.

• If the token is valid, the API trusts the claims within the payload (for example, the user's ID) and proceeds to fulfill the request, potentially using the user's roles to determine if they have permission to access the requested resource.

• If the token is invalid (bad signature, expired, and so on), the API rejects the request, typically with an HTTP 401 Unauthorised status.

This flow is powerful because JWTs are stateless: once issued, the authentication server doesn't need to keep a record of active sessions. The API can verify the token independently, which simplifies scaling and reduces server load.

JWT Security Best Practices and Considerations

While JWTs offer powerful authentication capabilities, using them securely requires careful attention to best practices. Misconfigurations or oversight can lead to significant vulnerabilities.

Always Use HTTPS/TLS:

Crucial: JWTs are encoded, not encrypted, by default. This means anyone who intercepts the token during transmission can easily read its payload. Therefore, JWTs (and all authentication traffic) must always be transmitted over HTTPS (TLS) to encrypt the communication channel itself and prevent eavesdropping.

Protect Your Signing Keys:

Whether it's a private key (for RS256) or a shared secret key (for HS256), these keys are paramount. If an attacker gains access to your signing key, they can forge valid JWTs, impersonate users, and compromise your system. Store these keys securely, preferably in dedicated key management services.

Keep Access Tokens Short-Lived (exp claim):

You should always set short expiration times (for example, 5-15 minutes) for your JWTs used as access tokens. This minimises the window of opportunity for an attacker if a token is compromised.

Since JWTs are stateless, they are hard to revoke immediately once issued. A short lifespan is your primary defense against compromised tokens.

Implement Refresh Tokens (for Longer Sessions):

To maintain user experience with short-lived access tokens, use refresh tokens. A refresh token is a separate, longer-lived token (usually stored more securely) that can be exchanged for a new, short-lived access token when the current one expires, without requiring the user to re-authenticate. Refresh tokens can be revoked by the server, offering better control.

Never Put Sensitive Data in the Payload:

Reiterating this crucial point: the JWT payload is Base64Url encoded, which is easily reversible. Do not put passwords, highly sensitive PII (Personally Identifiable Information), or confidential business data directly into the JWT payload. Only include non-sensitive or publicly available information, or data that's already encrypted by other means.

Validate ALL Claims on Verification:

When verifying a JWT, don't just check the signature. Always validate all relevant claims, including:

• exp (Expiration): Ensure the token hasn't expired.

• iss (Issuer): Verify the token came from the expected authentication server.

• aud (Audience): Ensure the token is intended for your specific API/application.

• nbf (Not Before): Check if the token is active yet.

Consider Token Revocation (for critical cases):

For situations requiring immediate revocation (for example, user password change, account deactivation), typical stateless JWTs are challenging. Strategies include:

• Short expiration times (as above).

• A blacklist/revocation list: Store the jti (JWT ID) of revoked tokens in a database, checking this list on every request. This adds a stateful lookup but provides immediate revocation.

Thanks for reading!

I hope you’ve found this tutorial useful, and as always if you want to ask any questions or hear about upcoming articles, you can always follow me on ‘X’, my handle is @grantdotdev and follow by clicking here.

By the end, you'll have a fully functional authentication system with Astro actions, magic link authentication using Supabase, bot protection via Cloudflare Turnstile, protected routes and middleware, and secure session management.

Table of Contents

• Prerequisites

• Understanding the Technologies

  • What is Astro?

  • What are Astro Actions?

  • What is Supabase?

  • What is Cloudflare Turnstile?

• Understanding SSR Authentication

  • SSR vs. SPA Authentication

• Why Protect Auth Forms?

• Part 1: How to Set Up the Backend

  • Set Up Supabase Backend

  • Set Up Cloudflare Turnstile

• Part 2: How to Set Up the Frontend

  • Create the Astro Project

  • Configure Astro for SSR

  • Install Supabase Dependencies

  • Configure Environment Variables

• Part 3: How to Set Up Supabase SSR

  • Create the Supabase Client

  • Create Middleware for Route Protection

• Part 4: How to Build the User Interface

  • Update the Layout

  • Create the Sign-In Page

  • Create the Protected Page

• Part 5: How to Set Up Astro Actions

  • Create the Authentication Actions

  • Create the Code Exchange API Route

• Part 6: How to Test Your Application

• Notes and Additional Resources

  • Useful Documentation

  • Complete Code Repository

Prerequisites

This tutorial assumes you are familiar with:

• Web development frameworks

• Basic authentication flows

• Basic Backend-as-a-Service (BaaS) concepts

Understanding the Technologies

What is Astro?

Astro is a UI-agnostic web framework that renders server-first by default. It can be used with any UI framework, including Astro client components.

What are Astro Actions?

Astro actions allow you to write server-side functions that can be called without explicitly setting up API routes. They provide many useful utilities that simplify the process of running server logic and can be called from both client and server environments.

What is Supabase?

Supabase is an open-source Backend-as-a-Service that builds upon Postgres. It provides key features such as authentication, real-time capabilities, edge functions, storage, and more. Supabase offers both a hosted version for easy scaling and a self-hostable version for full control.

What is Cloudflare Turnstile?

Turnstile is Cloudflare's replacement for CAPTCHAs, which are visual puzzles used to differentiate between genuine users and bots. Unlike traditional CAPTCHAs, which are visually clunky, annoying, and sometimes difficult to solve, Turnstile detects malicious activity without requiring users to solve puzzles, while providing a better user experience.

Understanding SSR Authentication

Server-side rendered (SSR) auth refers to handling authentication on the server using a cookie-based authentication method.

The flow works as follows:

1. The server creates a session and stores a session ID in a cookie sent to the client

2. The browser receives the cookie and automatically includes it in future requests

3. The server uses the cookie to determine if the user is authenticated

Since browsers cannot modify HTTP-only cookies and servers cannot access local storage, SSR authentication requires careful management to prevent security risks such as session hijacking and stale sessions.

SSR vs. SPA Authentication

Single-Page Applications (SPAs), like traditional React apps, handle authentication on the client side because they don't have direct access to a server. SPAs typically use JWTs stored in local storage, cookies, or session storage, sending these tokens in HTTP headers when communicating with servers.

Why Protect Auth Forms?

Authentication protects sensitive resources from unauthorized access, making auth forms primary targets for bots and malicious actors. Taking extra precautions is important for maintaining security.

Part 1: How to Set Up the Backend

Set Up Supabase Backend

First, you'll need a Supabase account. Create a project, then:

1. Go to the Authentication tab in the sidebar

2. Click the Sign In / Up tab under Configuration

3. Enable user sign-ups

4. Scroll down to Auth Providers and enable email (disable email confirmation for this tutorial)

Set Up Cloudflare Turnstile

1. Log in or register for a Cloudflare account

2. Click the Turnstile tab in the sidebar

3. Click the "Add widget" button

4. Name your widget and add "localhost" as the hostname

5. Leave all other settings as default, and create the widget

After creating the widget, copy the secret key and add it to your Supabase dashboard:

1. Go back to Supabase Authentication settings

2. Navigate to the Auth Protection tab under Configuration

3. Turn on Captcha protection

4. Choose Cloudflare as the provider

5. Paste your secret key

Part 2: How to Set Up the Frontend

Create the Astro Project

Next, you will need to create an Astro project. Open your preferred IDE or Text editor’s integrated terminal and run the following command to scaffold an Astro project in a folder named “ssr-auth.” Feel free to use any name you like.

npm create astro@latest ssr-auth

Follow the provided prompts and choose a basic template to start with. When it’s done, change into the folder, then run npm install to install dependencies, followed by npm run dev to start the server, and your site will be available at localhost:4321.

Configure Astro for SSR

Set Astro to run in SSR mode by adding output: "server", to the defineConfig function found in the astro.config.mjs file at the root of the folder.

Next, add an adapter to create a server runtime. For this, use the Node.js adapter by running this command in a terminal: npx astro add node. This will add it and automatically make all relevant changes.

Finally, add Tailwind for styling. Run this command in a terminal window: npx astro add tailwind. Follow the prompts, and it will make any changes necessary.

At this stage, your astro.config.mjs should look like this:

// @ts-check
import { defineConfig } from "astro/config";
import node from "@astrojs/node";
import tailwindcss from "@tailwindcss/vite";

// https://astro.build/config
export default defineConfig({
  output: "server",
  adapter: node({
    mode: "standalone",
  }),
  vite: {
    plugins: [tailwindcss()],
  },
});

Install Supabase Dependencies

You can do this by running the following command:

npm install @supabase/supabase-js @supabase/ssr

Configure Environment Variables

Create a .env file in the project root and add the following. Remember to replace with your actual credentials:

SUPABASE_URL=<YOUR_URL>
SUPABASE_ANON_KEY=<YOUR_ANON_KEY>
TURNSTILE_SITE_KEY=<YOUR_TURNSTILE_SITE_KEY>

You can get the Supabase values from the dashboard:

💡Note: In Astro, environment variables accessed on the client side must be prefixed with 'PUBLIC'. But since we're using Astro actions that run on the server, the prefix is not required.

Part 3: How to Set Up Supabase SSR

Create the Supabase Client

Create src/lib/supabase.ts:

import { createServerClient, parseCookieHeader } from "@supabase/ssr";
import type { AstroCookies } from "astro";

export function createClient({
    request,
    cookies,
}: {
    request: Request;
    cookies: AstroCookies;
}) {
    const cookieHeader = request.headers.get("Cookie") || "";

    return createServerClient(
        import.meta.env.SUPABASE_URL,
        import.meta.env.SUPABASE_ANON_KEY,
        {
            cookies: {
                getAll() {
                    const cookies = parseCookieHeader(cookieHeader);
                    return cookies.map(({ name, value }) => ({
                        name,
                        value: value ?? "",
                    }));
                },
                setAll(cookiesToSet) {
                    cookiesToSet.forEach(({ name, value, options }) =>
                        cookies.set(name, value, options)
                    );
                },
            },
        }
    );
}

This sets up Supabase to handle cookies in a server-rendered application and exports a function that takes the request and cookies object as input. The function is set up like this because Astro has three ways to access request and cookie information:

• Through Astro’s global object, which is only available on Astro pages.

• Through AstroAPIContext object, which is only available in Astro actions.

• Through APIContext which is a subset of the global object and is available through API routes and middleware.

So the createClient function accepts the request and cookies objects separately to make it flexible and applicable in the various contexts in which it may be used.

Create Middleware for Route Protection

Next, create a middleware.ts file in the src folder and paste this into it:

import { defineMiddleware } from "astro:middleware";
import { createClient } from "./lib/supabase";

export const onRequest = defineMiddleware(async (context, next) => {
    const { pathname } = context.url;

    console.log("Middleware executing for path:", pathname);

    const supabase = createClient({
        request: context.request,
        cookies: context.cookies,
    });

    if (pathname === "/protected") {
        console.log("Checking auth for protected route");

        const { data } = await supabase.auth.getUser();

        // If no user, redirect to index
        if (!data.user) {
            return context.redirect("/");
        }
    }

    return next();
});

This middleware checks for an active user when accessing the protected route and redirects unauthenticated users to the index page.

Part 4: How to Build the User Interface

Update the Layout

First, update src/layouts/Layout.astro to include the Turnstile script. Add this just above the closing </head> tag:

<script
    src="https://challenges.cloudflare.com/turnstile/v0/api.js"
    async
    defer>
</script>

Create the Sign-In Page

Replace the contents of src/pages/index.astro:

---
import Layout from "../layouts/Layout.astro";
import { createClient } from "../lib/supabase";
import "../styles/global.css";

const supabase = createClient({
    request: Astro.request,
    cookies: Astro.cookies,
});

const { data } = await supabase.auth.getUser();

if (data.user) {
    return Astro.redirect("/protected");
}

const apiKey = import.meta.env.TURNSTILE_SITE_KEY;
---

<Layout>
    <section class="flex flex-col items-center justify-center m-30">
        <h1 class="text-4xl text-left font-bold mb-12">Sign In to Your Account</h1>
        <form id="signin-form" class="flex flex-col gap-2 w-1/2">
            <label for="email" class="">Enter your email</label>
            <input
                type="email"
                name="email"
                id="email"
                placeholder="youremail@example.com"
                class="border border-gray-500 rounded-md p-2"
                required
            />
            <div class="cf-turnstile" data-sitekey={apiKey}></div>
            <button
                type="submit"
                id="sign-in"
                class="bg-gray-600 hover:bg-gray-700 p-2 rounded-md text-white font-bold w-full cursor-pointer disabled:bg-gray-500 disabled:hover:bg-gray-500 disabled:cursor-not-allowed"
                >Sign In</button
            >
        </form>
    </section>
</Layout>

Here, the frontmatter creates a Supabase server client and then uses it to check if we have an active user. It redirects based on this information. This works because the front matter runs on the server side, and the project is set to server output.

The template displays a simple form with an email input. To complete it, add this below the closing </Layout> tag:

<script>
    import { actions } from "astro:actions";

    declare global {
        interface Window {
            turnstile?: {
                reset: () => void;
            };
        }
    }

    const signInForm = document.querySelector("#signin-form") as HTMLFormElement;
    const formSubmitBtn = document.getElementById("sign-in") as HTMLButtonElement;

    signInForm?.addEventListener("submit", async (e) => {
        e.preventDefault();
        formSubmitBtn.disabled = true;
        formSubmitBtn.textContent = "Signing in...";

        try {
            const turnstileToken = (
                document.querySelector(
                    "[name='cf-turnstile-response']"
                ) as HTMLInputElement
            )?.value;

            if (!turnstileToken) {
                throw new Error("verification_missing");
            }

            const formData = new FormData(signInForm);
            formData.append("captchaToken", turnstileToken);

            const results = await actions.signIn(formData);

            if (!results.data?.success) {
                if (results.data?.message?.includes("captcha protection")) {
                    alert("Verification failed. Please try again.");
                    if (window.turnstile) {
                        window.turnstile.reset();
                    }
                    formSubmitBtn.disabled = false;
                    formSubmitBtn.textContent = "Sign In";
                    return;
                } else {
                    alert("Oops! Could not sign in. Please try again");
                    formSubmitBtn.disabled = false;
                    formSubmitBtn.textContent = "Sign In";
                    return;
                }
            }

            formSubmitBtn.textContent = "Sign In";
            alert("Please check your email to sign in");
        } catch (error) {
            if (window.turnstile) {
                window.turnstile.reset();
            }
            formSubmitBtn.disabled = false;
            formSubmitBtn.textContent = "Sign In";
            console.log(error);
            alert("Something went wrong. Please try again");
        }
    });
</script>

This adds some vanilla JavaScript that calls the SignIn Upon form submission. This action provides user feedback through alerts and manages the button’s text and disabled state. This effectively adds client-side interactivity to the page.

Create the Protected Page

Create src/pages/protected.astro:

---
import Layout from "../layouts/Layout.astro";
import { createClient } from "../lib/supabase";
import "../styles/global.css";

const supabase = createClient({
    request: Astro.request,
    cookies: Astro.cookies,
});

const { data } = await supabase.auth.getUser();
---

<Layout>
    <section class="flex flex-col items-center justify-center m-30">
        <h1 class="text-4xl text-left font-bold mb-12">You are logged in!</h1>
        <p class="mb-6">Your user Id: {data.user?.id}</p>
        <button
            id="sign-out"
            class="bg-gray-600 hover:bg-gray-700 px-4 py-2 rounded-md text-white font-bold cursor-pointer disabled:bg-gray-500 disabled:hover:bg-gray-500 disabled:cursor-not-allowed"
            >Sign Out</button
        >
    </section>
</Layout>

<script>
    import { actions } from "astro:actions";
    const signOutBtn = document.getElementById("sign-out") as HTMLButtonElement;

    signOutBtn?.addEventListener("click", async (e) => {
        e.preventDefault();
        signOutBtn!.disabled = true;
        signOutBtn!.textContent = "Signing out...";

        try {
            const results = await actions.signOut();

            if (!results.data?.success) {
                signOutBtn!.disabled = false;
                signOutBtn!.textContent = "Sign Out";
                return alert("Oops! Could not sign Out. Please try again");
            }
            return window.location.reload();
        } catch (error) {
            signOutBtn.disabled = false;
            signOutBtn.textContent = "Sign Out";
            console.log(error);
            return alert("Something went wrong. Please try again");
        }
    });
</script>

This page retrieves the user data server-side in the front matter and displays it in the template, along with a sign-out button.

The JavaScript in the script tags handle calling the sign-out action, user feedback, and button state, as in the index.astro page.

Part 5: How to Set Up Astro Actions

Create the Authentication Actions

Finally, add an actions folder in the src folder and create an index.ts file to hold our logic. Paste the following into it:

import { defineAction, type ActionAPIContext } from "astro:actions";
import { z } from "astro:schema";
import { createClient } from "../lib/supabase";

const emailSignUp = async (
    {
        email,
        captchaToken,
    }: {
        email: string;
        captchaToken: string;
    },
    context: ActionAPIContext
) => {
    console.log("Sign up action");
    try {
        const supabase = createClient({
            request: context.request,
            cookies: context.cookies,
        });

        const { data, error } = await supabase.auth.signInWithOtp({
            email,
            options: {
                captchaToken,
                emailRedirectTo: "http://localhost:4321/api/exchange",
            },
        });

        if (error) {
            console.error("Sign up error", error);
            return {
                success: false,
                message: error.message,
            };
        } else {
            console.log("Sign up success", data);
            return {
                success: true,
                message: "Successfully logged in",
            };
        }
    } catch (err) {
        console.error("SignUp action other error", err);
        return {
            success: false,
            message: "Unexpected error",
        };
    }
};

export const server = {
    signIn: defineAction({
        accept: "form",
        input: z.object({
            email: z.string().email(),
            captchaToken: z.string(),
        }),
        handler: async (input, context) => {
            return emailSignUp(input, context);
        },
    }),
    signOut: defineAction({
        handler: async (_, context) => {
            const supabase = createClient({
                request: context.request,
                cookies: context.cookies,
            });
            const { error } = await supabase.auth.signOut();
            if (error) {
                console.error("Sign out error", error);
                return {
                    success: false,
                    message: error.message,
                };
            }
            return {
                success: true,
                message: "Successfully signed out",
            };
        },
    }),
};

This action handles both sign-in and sign-out methods. A Supabase server instance is created during the sign-in method, and the magic link method is used for sign-in. It passes a redirect URL, which we have yet to create, and handles any errors that may occur.

It also passes the token verification, allowing Supabase to perform verification on our behalf, eliminating the need to call Cloudflare’s verify APIs directly.

The sign-out method calls Supabase’s sign-out method and handles any potential errors.

The redirect URL refers to an API route that exchanges the code from the email Supabase sends for a session that Supabase handles.

Create the Code Exchange API Route

Create src/pages/api/exchange.ts:

import type { APIRoute } from "astro";
import { createClient } from "../../lib/supabase";

export const GET: APIRoute = async ({ request, cookies, redirect }) => {
    const url = new URL(request.url);
    const code = url.searchParams.get("code");

    if (!code) {
        return redirect("/");
    }

    const supabase = createClient({ request, cookies });
    const { error } = await supabase.auth.exchangeCodeForSession(code);

    if (error) {
        console.error("Error exchanging code for session:", error);
        return redirect("/404");
    }

    return redirect("/protected");
};

This grabs the code from the URL in the magic link sent, creates a server client, and calls the exchangeCodeForSession method with the code. It handles any error by redirecting to Astro’s built-in not-found page.

Otherwise, it will redirect to the protected page as Supabase handles the session implementation details.

Part 6: How to Test Your Application

Start your development server: npm run dev

Visit the provided localhost URL. You should see the sign-in page with the Turnstile widget:

If you try to access the /protected page, it will redirect you back to this view until you sign in. Now, sign in, and you should get an email with a link that will redirect you to the /protected page. This is what you should see:

And with that, you've successfully built a comprehensive auth system that leverages Astro actions, Supabase auth, and Cloudflare Turnstile's bot protection. This setup provides a secure, user-friendly authentication experience while protecting your application from malicious actors.

Notes and Additional Resources

Useful Documentation

• Supabase's advanced guide to SSR

• Supabase SSR package

• Astro Cookies documentation

• Supabase PKCE flow documentation

• Astro Actions documentation

• Get started with Turnstile

Complete Code Repository

The complete code for this project is available on GitHub:

• Base authentication setup

• With Cloudflare Turnstile

The reality is, keeping personal data safe isn't something you should be doing because it's good practice – it's something you have to do. Users are trusting developers to care for their data day in and day out, and power must be wielded wisely. If you're writing code that involves getting, processing, or storing someone's personal data, then you should be being proactive about keeping it safe.

So the question is: how do you safely keep personal data?

Table of Contents

• Know What You

Know What You're Protecting

If you must protect information, first determine what information must be protected. It is crucial to protect sensitive information from unauthorized access to ensure data security. Below is a list of some common types of sensitive data:

• Personally Identifiable Information (PII): name, address, phone number, email, Social Security number.

• Financial Data: bank details, payment history, credit card number.

• Authentication Data: password, auth tokens, API keys, security question responses.

• Health Info: any kind of HIPAA-protected information about the health and medical history of the user.

Once you know what information has to be rendered secure, then you can go ahead and render it secure.

Best Practices in Data Security

1. Encrypt Everything

Your best protection against hacking is encryption. When data is encrypted, even if hackers have access to it, they cannot do anything with it in the absence of the decryption key.

For stored sensitive information, use hashing with a salt, a process that turns a password into an irreversible value. This way, even if someone gains access to the stored data, the actual password isn't exposed.

import hashlib
import os

def hash_password(password):
    salt = os.urandom(32)  # Generate a new salt
    hashed_password = hashlib.pbkdf2_hmac('sha256', password.encode('utf-8'), salt, 100000)
    return salt + hashed_password

For data in transit, always use HTTPS:

sudo certbot --nginx -d yourdomain.com

This ensures data is encrypted between your server and the user. You can also reduce how often data is in transit by using edge computing. Rather than sending sensitive data to external servers, increasing risk, it allows data to be stored and processed locally.

2. Perform Secure Authentication

Weak authentication is an extremely critical security vulnerability.

Authentication is the process of verifying who a user is (for example, logging in), while authorization is verifying what they're allowed to do (for example, access admin features).

Make sure that you:

• Perform strong password habits.

• Perform multi-factor authentication (MFA). MFA requires users to present two or more verification factors (for example password and one-time code from a mobile device), making it much harder for attackers to gain access.

• Perform OAuth 2.0 or OpenID Connect third-party authentication. These are secure industry-standard protocols that allow users to authenticate via trusted platforms like Google or Facebook, reducing the need to store credentials yourself.

Example: Here’s an authentication setup using JWT (JSON Web Tokens) in Python:

import jwt
import datetime

SECRET_KEY = "your_secret_key"

def generate_token(user_id):
    payload = {
        "user_id": user_id,
        "exp": datetime.datetime.utcnow() + datetime.timedelta(hours=1)
    }
    return jwt.encode(payload, SECRET_KEY, algorithm='HS256')

This function generates a secure token for a user. The token contains the user ID and an expiration time, and it's signed using a secret key. Clients send this token with each request, and servers verify it to ensure the request comes from an authenticated user.

3. Minimize the Data You Need to Store

One of the simplest things you can do to protect personal data? Store less than you have to. Consider the following questions:

• Do I really need to store this data?

• How long do I really need to keep it for?

• Can I anonymise it?

For example, if you are going to need analytics, consider deleting personal identifiers prior to storing the data:

const anonymizeData = (user) => {
    return {
        sessionId: generateRandomId(),
        event: user.event,
        timestamp: new Date().toISOString()
    };
};

This JavaScript function removes identifying information (like name or email) and replaces it with a random session ID, keeping only the data necessary for analytics.

For instance, if you manage email lists, avoid storing unnecessary subscriber data beyond what is required for communication.

Regularly clean and scrub email lists to remove outdated or inactive addresses. Sending emails to outdated/inactive addresses can damage your domain reputation, leading to blacklisting and email deliverability issues. If you only need email addresses for temporary campaigns, consider automated deletion policies to remove old data.

4. Secure Your APIs

If your application is consuming other services, protect your API endpoints. You can do this by:

• Require tokens or API keys: These act as credentials to access the API and prevent unauthorized use.

• Implement rate limiting to deter abuse: This prevents attackers from flooding your server with too many requests.

• Validate and sanitize all input data: This protects against injection attacks and malformed inputs.

Here's how you can validate API input in Node.js:

const express = require('express');
const app = express();

app.post('/api/data', (req, res) => {
    const { name, email } = req.body;
    if (!name || !email.includes('@')) {
        return res.status(400).send('Invalid input');
    }
    res.send('Data received');
});

This ensures the API receives valid data and returns an error for incorrect input, which is a basic form of input sanitization.

5. Lock Down Your Database

Your database is an attack treasure trove, so lock it down:

• Use parameterized queries to prevent SQL injection. These queries separate data from code.

• Limit database access using role-based permissions: Only give each user or service the access it needs—no more.

• Back up and test restoration procedures: Regular backups ensure you can recover data in the event of a breach or corruption.

Here's a safe way to query a database in Python:

import sqlite3

def get_user(email):
    conn = sqlite3.connect('database.db')
    cursor = conn.cursor()
    cursor.execute("SELECT * FROM users WHERE email = ?", (email,))
    return cursor.fetchone()

This example uses a parameterized query (the ? placeholder) to safely insert the email into the SQL command, protecting against injection.

Also, never overlook how databases and internal systems might be accessed remotely. Remote access, whether for IT admins, support teams, or mobile workers, often involves logging in from unfamiliar devices—which introduces new security challenges. Tools that allow for secure, contactless logins without typing passwords or installing software on the remote machine reduce the risk of credential theft.

You can also ensure that remote database connections, SSH access, and admin panels are protected with strong authentication, IP restrictions, and, ideally, VPN access to avoid exposing sensitive entry points to the internet.

And remember, you don’t have to reinvent the wheel—there are powerful data protection tools available to keep your data safe from breaches and downtime. Want to know which ones stand out? Check out this guide for a breakdown of some of the best solutions.

6. Periodically Audit and Update Your Code

Unpatched software and outdated dependencies are essentially an open invitation to the attackers. Update your software and conduct security audits regularly.

Perform security scans for your project:

npm audit fix --force  # For Node.js projects

pip install --upgrade package_name  # For Python projects

These commands help find and fix known vulnerabilities in your project dependencies.

7. Train Your Employees

Your security is just as strong as your weakest link. If one employee handles sensitive data irresponsibly, everything else may have been for naught.

• Standard security training: Regular sessions on topics like phishing, password security, and data handling.

• Implement solid policies on user data handling: For instance, never download sensitive data to personal devices.

• Establish a security-oriented culture: Encourage reporting of suspicious activity, regular internal audits, and open communication about threats.

8. Give Users Control Over Their Data

Transparency breeds trust. Give users control to:

• View and download their data.

• Terminate their account easily.

• Make adjustments in privacy settings.

If you are collecting data, provide an opt-out. Users must be able to protect sensitive data and be in control of what becomes of their information. This is why it is important to have a privacy policy: users need to know what data you are collecting and for what purpose. Check out this privacy policy template if you need to create one for your site.

Final Thoughts

Data protection isn't just about coding well—it's about attitude. Get in the head of an attacker for a day, minimize vulnerabilities, and put user privacy at the top of your mind.

So the next time you're scanning the headlines for news of the latest ginormous data breach, you can be confident that your apps are bulletproof. Be smart, continue to learn, and let's make the internet safe—one line of secure code at a time.

For those new to development or without technical expertise, managing servers, databases, and user logins can be overwhelming. This is where Backend as a Service (BaaS) helps.

BaaS platforms provide ready-made backend solutions, making app development simpler. Whether you're a developer or someone with no coding experience, BaaS allows you to focus on your app’s features instead of handling backend complexities.

​​This article will explore BaaS, its features, pricing, and popular BaaS​ tools.

Table of Contents

• ​​​What is Backend as a Service (BaaS)?

• Key Features of Baas

• Why use Backend as a Service (BaaS)?

• When to Use Backend as a Service (BaaS)

• What are the Popular Backend as a Service (BaaS) Tools?

• How to Get Started with BaaS (Quick Example)

• Conclusion

​​​What is Backend as a Service (BaaS)?

BaaS is a cloud platform that provides pre-built backend infrastructure and services. It eliminates the need for developers to manage servers, databases, and other backend tasks.

​​Source: https://www.cloudflare.com

​​Key Features of BaaS

Here are some features of BaaS:

• BaaS makes it easy to create and manage user accounts and logins without much coding.

• It lets you store and manage data, eliminating the need to set up a database from scratch.

• BaaS comes with tools (APIs and SDKs) that help connect your application to the backend easily.

• Many BaaS platforms let you see updates in real time, so your application can show live data to users.

• BaaS offers space in the cloud to store files and images, making it easy to handle user uploads.

• You don’t need to worry about managing servers—BaaS takes care of that for you, so you can focus on building your application.

• Some BaaS platforms allow you to send notifications to users about updates or messages.

• BaaS often provides tools to track user interactions, helping you understand what works and what doesn’t.

• It also makes it easy to integrate with other services like payment systems and social media with minimal effort.

• As your app grows, BaaS scales with it, handling more users and data seamlessly.

Why use Backend as a Service (BaaS)?

There are several key reasons why BaaS is an excellent choice for developers:

• Pre-built features reduce development time, allowing you to focus on design and functionality instead of backend issues.

• With BaaS, you don’t have to worry about servers, scaling, or security updates—the provider takes care of it all.

• Most BaaS platforms offer essential features like user authentication, data storage, and real-time updates, helping you build your app without starting from scratch.

• As your application gets more users, BaaS can handle it! These services adjust to support more users and data, so you can focus on growing your app.

• BaaS handles the infrastructure so you don’t need to spend time or money on the backend. This allows you to focus on design and creating user experiences that add value to your users.

When to Use Backend as a Service (BaaS)

BaaS is perfect for building an app in a short amount of time without managing the backend. Here are the scenarios when BaaS makes sense:

• BaaS handles your app’s backend, letting you focus on its features. For example, when building a to-do list app, BaaS makes it easy to manage user logins and task data without setting up servers from scratch.

• For small teams or solo devs, BaaS handles the backend. You do not need extra resources.

• If you're launching a startup, Baas lets you release a Minimum Viable Product (MVP) without delay. It helps you speed up development and cut costs.

• If your app needs features like user authentication, data storage, or push notifications, BaaS provides them out of the box. For example, when building a social media app, BaaS simplifies user logins and file uploads, saving you from starting from scratch.

• BaaS automatically scales to support more users, allowing you to focus on improving your app. For example, a small multiplayer game can start with a few players, and as it grows, BaaS will seamlessly handle thousands without extra backend effort.

What are the Popular Backend as a Service (BaaS) Tools?

If you're looking to explore BaaS, here are popular platforms you can use:

Clerk

Clerk software focuses on user management. It offers tools for authentication, user profiles, and permissions management. It’s great for developers who need simple user management in their apps.

Features of clerk

Clerk provides:

• Multi-factor authentication (MFA)

• Passwordless login (magic links, OTPs)

• Social & OAuth login (Google, GitHub, and so on)

• Enterprise SSO (SAML, OAuth)

• Biometric login (Face ID, Touch ID)

It also handles:

• User profiles & custom attributes

• Roles & permissions

• Teams & organizations

• Session management

For security, it offers:

• Token-based authentication (JWT)

• Rate limiting

• Audit logs

• GDPR & SOC 2 compliance

For developers, it comes with:

• Prebuilt UI components

• SDKs for React, Next.js, Vue, and so on

• Custom email & SMS templates

To learn more, click here: Clerk

Pricing

Clerk offers a Free Plan that includes up to 10,000 Monthly Active Users (MAUs) at no cost. For more advanced features, the Pro Plan is available at $25 per month, which also includes the first 10,000 MAUs.

For detailed and up-to-date information on Clerk's pricing plans, please visit their official pricing page:

Firebase

Firebase is a Google-backed BaaS platform. It is known for its real-time databases, authentication, and cloud storage. It also has easy-to-use tools for web and mobile apps.

Features of Firebase

Firebase provides:

Backend Services

• Firestore & Realtime Database

• Cloud Storage

• Serverless Functions

• Web Hosting

Authentication

• Email & password login

• Social logins (Google, Facebook, and so on)

• Phone authentication

• Anonymous sign-in

Analytics & Monitoring

• Google Analytics

• Crash tracking (Crashlytics)

• Performance monitoring

• A/B testing

Engagement Tools

• Push notifications

• Remote app updates

• In-app messaging

Machine Learning

• Text recognition

• Image labelling

To learn more, click here: Firebase

Pricing plan

Firebase offers a Spark Plan (free tier) and a Blaze Plan (pay-as-you-go). The Spark Plan provides limited free usage, while the Blaze Plan charges based on your actual usage. For detailed and up-to-date information on Firebase's pricing plans, please visit their official pricing page.

Convex

Convex is a serverless BaaS platform. It provides real-time data sync and scalable backend services. The design simplifies serverless computing for developers.

Convex Features

• Database – Real-time data storage

• Serverless Functions – Run backend logic without managing servers

• Authentication – Built-in user auth & access control

• Caching – Faster data retrieval

• Webhooks & Crons – Automate tasks & trigger events

To learn more, click here: Convex

Pricing

• Free Plan – Limited resources for small projects

• Pro Plan – Pay-as-you-go based on usage

Check out full details for convex pricing

8base

A low-code platform that allows developers to build serverless apps with minimal setup. It provides database management, authentication, and API development tools.

8base Features

• Backend Builder – Manage your database easily.

• Serverless Functions – Run custom backend logic.

• GraphQL API – Auto-generated API for your data.

• Authentication – Built-in user login & access control.

• File Management – Store and manage files.

To learn more, click here: 8base

Pricing

• Free Plan – $0/month (1 developer, basic features).

• Developer Plan – $25/month per developer.

• Professional Plan – $150/month (5 developers).

• Custom Plan – Contact 8base for enterprise solutions.

Check out full pricing details here: 8base Pricing

Backendless

Backendless is a no-code platform that makes app development easy. It provides APIs, data storage, user management, and real-time updates in one place.

Features

• UI Builder: Design your app's front end visually without coding.

• Real-Time Database: Store and sync data in real-time across clients.

• User Authentication: Manage user sign-ups, logins, and roles.

• Cloud Code: Implement custom server-side logic without managing servers.

• Push Notifications: Send real-time alerts to users on various devices.

To learn more, click here: Backendless

Pricing

Backendless offers several plans to suit different needs:

• Free Plan: Ideal for small projects or learning purposes.

• Scale Fixed Plan: Provides predictable monthly billing with set resource limits.

• Scale Variable Plan: Offers flexibility with usage-based billing, scaling as your app grows.

• Backendless Pro: A self-hosted solution for enterprises requiring unlimited scalability and control.

For more details on Backendless's pricing plans, please visit their official pricing plan page.

Appwrite

Appwrite is an open-source BaaS that provides databases, authentication, file storage, real-time updates, serverless functions, and API management. It supports multiple platforms and offers built-in security and scalability for modern apps.

Features

• Authentication: Secure user login with over 30 methods, including email/password, OAuth, and magic URLs.

• Database: Scalable storage with advanced permissions, custom data validation, and support for relationships.

• Functions: Deploy serverless functions in over 13 languages, with automatic GitHub deployment and custom domain support.

• Storage: Manage and serve files with built-in security and privacy features.

• Real-Time: Subscribe to database events for instant updates.

To learn more, click here: Appwrite

Pricing

• Free – $0/month (5GB bandwidth, 2GB storage, 750K function runs).

• Pro – Starts at $15/month (more storage, bandwidth, & features).

• Scale – Starts at $599/month (for large-scale projects).

For more details on the pricing plan check their official pricing page.

Nhost

Nhost is a full backend platform with a GraphQL API, database, authentication, and storage. It’s easy to set up and great for modern app development.

Nhost Features

• Authentication – Secure login with email, OAuth, and so on.

• Database – Scalable storage with permissions.

• Serverless Functions – Run backend code without servers.

• Storage – Secure file hosting.

• Real-Time – Instant updates on data changes.

To learn more, click here: Nhost.

Pricing

• Free – $0/month (basic features for small projects).

• Pro – $25/month (more resources & support).

• Dedicated Compute – $50/month per vCPU/2GB RAM (for scaling apps).

Check out full details here: Nhost Pricing

Back4apps

Back4App is an open-source BaaS that simplifies backend development. It provides a complete infrastructure for building, hosting, and managing scalable apps. With built-in server-side features, developers can focus on coding without managing servers or databases.

Back4App Features

• Database – Manage data with APIs & a visual editor

• Authentication – Secure user login & roles

• Real-Time – Instant data updates

• Push Notifications – Send alerts to users.

• Cloud Functions – Run custom backend code.

To learn more, click here: Back4apps.

Pricing

• Free – 25K requests, 250MB storage, 1GB transfer/month.

• MVP Plan – For launching small apps.

• Dedicated Plan – For production apps with more resources.

The MVP Plan in Back4App refers to a Minimum Viable Product (MVP) Plan. It is designed for startups and developers who are launching a small app with essential backend services. This plan provides enough resources to test and validate an idea before scaling up.

While Dedicated Plan in Back4App provides a private server with dedicated resources for apps that need better performance, security, and scalability. It is ideal for production apps with high traffic or specific infrastructure requirements.

Check out full details here: Back4App Pricing.

AWS Amplify

AWS Amplify is a development platform from Amazon Web Services (AWS). It simplifies building and deploying web and mobile apps. It offers tools and services for developers. They can integrate scalable backends, manage frontends, and add features like authentication, storage, and APIs.

AWS Amplify Features

• Authentication – Secure login with email, social sign-in, and multi-factor authentication

• Database & API – Build real-time APIs with AWS databases

• Storage – Manage files and media with Amazon S3

• Hosting – Deploy full-stack apps with continuous deployment

To learn more, click here: Aws Amplify

Pricing

• Free Tier (First 12 months)

  • 1,000 build minutes/month

  • 5GB storage

  • 15GB bandwidth

  • 500K API requests

• Pay-As-You-Go (After Free Tier)

  • Build & Deploy – $0.01 per build minute

  • Storage – $0.023 per GB/month

  • Bandwidth – $0.15 per GB served

  • API Requests – $0.30 per 1M requests

Full details here: AWS Amplify Pricing

Supabase

Supabase is an open-source alternative to Firebase. It uses PostgreSQL for its database. It has built-in features like authentication, APIs, and real-time subscriptions.

Supabase Features

• Database – PostgreSQL with full SQL support.

• Authentication – Secure login with email, password, and social logins.

• Storage – Store and serve files easily.

• Real-Time – Get instant updates when data changes.

• Edge Functions – Run serverless backend logic.

To learn more, click here: Supabase.

Pricing

• Free – Great for small projects i.e. projects for learning, and experimentation.

• Pro – Starts at $25/month (includes $10 compute credits).

• Team – Starts at $599/month (for advanced features & support).

Full details here: Supabase Pricing

How to Get Started with BaaS (Quick Example)

Let’s go through a quick example to get started. In this tutorial, I’ll use Firebase as an example.

• Go to the Firebase website and sign up using your Google account.

• After signing in, create a new Firebase project by following the on-screen instructions.

• Go to "Authentication" and enable a sign-in method, like email/password or Google login

• In "Firestore Database," create a new database for your app's data.

• Install Firebase SDK in your project and integrate authentication, databases, and other Firebase services into your app.

For more detailed instructions on setting up Firebase, check out this article: How to Authenticate Your React App Using Firebase where I explain each step in depth.

Conclusion

Backend as a Service (BaaS) is ideal for developers. It provides an efficient and cost-effective way to handle backend development tasks. BaaS can speed up your development. It lets you avoid server management. You can then focus on building better apps.

If you're new to backend development, check out the BaaS tools in this article. They can simplify your workflow. Try out BaaS today and take your development to the next level!

Have you tried using BaaS for your applications? Share your experiences!

If you found this article helpful, share it with others who may find it interesting.

Stay updated with my projects by following me on Twitter, LinkedIn and GitHub.

Thank you for reading.

Keycloak is an enterprise-ready, open source identity access management (IAM) solution that's scalable, extensible, and robust. And it really doesn't need all that much care and feeding to launch a simple implementation.

This article will introduce you to the technology and the ways it can integrate best-practice authentication into your infrastructure.

Note on Hitachi Contributions to Keycloak:

Takashi Norimatsu works for Hitachi and has been the official maintainer of Keycloak since late 2021. Hitachi has been actively contributing to Keycloak since at least 2018.

Hitachi appears to be doing more strategically with open source in general and Keycloak in particular. I believe strong, continued corporate support as part of an open source project is a positive sign, but at the very least, you should be aware of the corporate support for Keycloak during your assessment.

Getting Started with Keycloak

I'll begin with a brief "quick start". As you can see from this screenshot, Keycloak will run happily on multiple platforms. And their product documentation is excellent.

But here's some very simple one-command Docker syntax that will create a fully-functioning live Keycloak instance on your local machine:

docker run -p 8080:8080 \
     -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
     -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.0.7 start-dev

That's it. After a minute or two, you can open the administration interface on your browser using the appropriate variation of:

localhost:8080

Based on the Docker command defaults, you'll log in using admin and admin. Spend a few minutes digging into the environment to get a feel for the tools that are available.

What Keycloak Offers

Ok. So why do you need Keycloak? Because it supports all the functionality demanded by modern deployments. That'll include Single Sign-On (SSO) to allow seamless authentication across multiple applications and services, OAuth2, OpenID Connect, SAML protocol compliance, and federated identities using existing LDAP or Active Directory setups or through social media logins like Google.

Keycloak incorporates the use of Multi-factor Authentication (MFA), built-in token revocation and expiration mechanisms, fine-grained permission management through Role-based Access Control (RBAC), and end-to-end encryption for sensitive communications. GDPR, HIPAA, and PCI DSS compliance are all possible.

Keycloak comes with a RESTful API for scripted and programmatic interactions. That will encourage task automation to further optimize your authentication processes. And your developers can build their own custom plugins to fill any usability gaps you encounter.

The Business Case for Keycloak

Because Keycloak is open source, there'll be no license fees to worry about. But open source gives you a lot more than just "cheap".

Keycloak cuts out vendor lock-in, allowing you to work with any platform or cloud provider – or move between them whenever necessary. It can also reduce overall operational costs through its simplified deployments (how much time did it take you to get that Docker image up and running?), automated updates, and no limits or cost penalties for even millions of monthly API calls or active users.

Having out-of-the-box (and free) access to the full feature set (including RBAC and MFA) also simplifies planning and execution. There's nothing "more" efficient than having to wait a week to access paywalled functionality until you get a response to your request for more project funding. All Keycloak features are just a click away.

This radar chart illustrates the feature and functionality differences between Keycloak and its major commercial peers.

What to Consider

As much as Keycloak has to offer, it won't be the ideal choice for every use-case. And there are issues about which you should be aware up front.

For instance, while getting started may be easy, fully configuring, say, clustering and high availability for Keycloak can be complex for teams without experience in identity management. Managing latency issues for very large deployments can be challenging.

And while the documentation is generally excellent, it may not fully address specific complexities or edge-case scenarios. Similarly, there's no resource within the Keycloak community that offers guaranteed support. Although there are excellent third-party providers out there.

It's possible that, because you're not working with a commercial product, demonstrating regulatory compliance could be a bit more involved. You may also need to adapt your logging functionality to comply with various audit trail requirements.

Finally, customizable environments risk introducing destabilizing complexity. The further off the beaten trail your plugins and API implementations wander, the greater the odds that something will eventually break – especially around version upgrades.

Your Next Steps

It's always helpful to explore the journeys other people took with a new technology.

So this page includes information on a fascinating case study involving a Japanese bank that was looking for an API solution and decided on Keycloak because of its high level API security features. Yuichi Nakamura’s presentation at the OpenShift Commons event in 2023 gives details how the bank successfully used Keycloak to secure their APIs. Nakamura, Hitachi Chief OSS Strategist, has recently been appointed as Head of Hitachi Open Source Program Office (OSPO).

And this is an account of a university that implemented Kerberos Single Sign-On (SSO) for FreeIPA and configured Keycloak to connect with FreeIPA. The university successfully achieved user authentication from Keycloak by leveraging the SSSD option under “user federation” instead of relying on Kerberos or LDAP.

I’m no stranger to Keycloak myself, having taught a Getting Started with Keycloak course on Pluralsight. For beginners, this may be a good place to start. A 10 day free trial is available.

In this article, you’ll learn how to integrate this type of authorization with Permit.io in Nuxt.

Table of Contents

• Table of Contents

• What is the Difference Between Authentication and Authorization?

• What is Role Based Access Control (RBAC)?

• What are the Benefits of Using Authorization As A Service?

• What We’ll Be Building

• How to Plan RBAC with Permit.io

• How to Setup Permit.io in Nuxt

• How to Control API Access with Nuxt Middleware

• How to Test RBAC in the Community Dashboard

• Summary

What is the Difference Between Authentication and Authorization?

When building applications, we often carry out authentication together with authorization. However, these two concepts are essentially different.

Authentication is verifying who a user is. During the authentication process, the user usually needs to log in with some identifier like email, phone, username, with Google, with Microsoft, and so on.

Authorization specifies the resources an authenticated user can view and what they can do in the application. Authorization tells a user's access rights after that user has been successfully authenticated.

For example, authentication is a user logging in with email and password or verifying their phone number with SMS. On the other hand, authorization is a writer creating and editing posts while only admins can approve and publish those posts.

The primary purpose of authentication is to establish a user's identity before granting them access to the system. The main goal of authorization is to control user actions and protect sensitive data or resources.

What is Role Based Access Control (RBAC)?

Role-Based Access Control (RBAC) is an authorization model that you can use to manage and restrict access to system resources. It is based on the responsibilities, duties, or roles of users.

In RBAC, roles represent predefined sets of permissions that tell which actions a user can execute in an application. These roles are then assigned to users based on their job functions or responsibilities.

In common systems, anyone can assign permissions to individual users. In RBAC, we group permissions into roles. In turn, we assign these roles to users. For example, in a community dashboard, users might have roles like “Admin”, “Mentor”, or “Member”.

Aside from Role-Based Access Control, other popular authorization models exist such as Attribute-Based (ABAC) and Relationship-based (ReBAC) access controls. Attribute-Based Access Control uses a wide range of attributes and fits constantly changing systems. You could also combine it with Role-Based Access Control. For more info, see the Permit.io article on RBAC vs. ABAC.

What are the Benefits of Using Authorization As A Service?

You can build authorization models yourself in your application. But it may be time-consuming and cost-ineffective in the long run.

Using an external provider for authorization allows you to focus on the business logic in your applications. The benefits of outsourcing authorization are similar to using a third party like Auth0 or Firebase for Authentication.

Authorization as a Service provides a solution for managing user access and permissions in applications. When you use such an authorization solution, you enjoy enhanced security, granular access policies’ control, auto-scaling policies, reduced maintenance burden, faster upgrades, robust logging, and so on.

Permit.io is free to use for up to a 1000 Monthly Active Users, and has a UI and API for RBAC, ABAC, and ReBAC.

To Get Started with Permit.io:

• Go to app.permit.io

• Create an account

• Create a workspace (in your account)

What We’ll Be Building

A community dashboard connects members within a community or forum. It is a platform where they can interact and access resources.

For demo purposes of RBAC, we’ll build a simple community dashboard that will include 3 types of content (entities): posts, materials, and announcements.

The code we will be using is at https://github.com/obumnwabude/rbac-community-dashboard. It consists of a Nuxt repo with its server configured for API calls and its front end built with Vue. Clone it with git and explore the code in an editor/IDE.

In the server, we will expose GET, POST, and DELETE endpoints for each entity (posts, materials, and announcements). In Nuxt, you can use the HTTP verb in the file name for the endpoint handler. So we can have posts.get.ts*, posts.delete.ts, materials.post.ts,* and so on, with each file containing the respective handler for the involved API endpoint.