Introduction: Why JWT for Headless Security?

Headless means your backend exclusively provides data without a presentation layer—for example, a PHP API that only returns JSON to a mobile app or JavaScript frontend. In such a stateless environment, traditional session authentication doesn't work smoothly: the server must process each request independently without tracking user sessions.

JSON Web Tokens (JWT) offer a compact, self-contained, and secure way to transmit authorization information. After logging in, the client receives a token that is sent with every API call, allowing your backend to easily verify if the user is authorized.

The Anatomy of a JWT

• Header: Contains metadata such as the algorithm (alg) and the token type (typ).
• Payload: Contains the "claims"—data about the user (sub), the issuer (iss), and the expiration (exp). You can also add roles or permissions here.
• Signature: A cryptographic signature over the header and payload, using your secret key, to prevent tampering.

Part 1: The PHP Backend – Building a JWT API

In this part, we'll build the PHP backend that issues and validates tokens. We will use firebase/php-jwt to create and verify JWTs, ensuring strict claim and algorithm validation.

• Structure:
  • api/login.php: Validates login credentials and returns a JWT (access + refresh).
  • api/refresh.php: Refreshes the access token using a valid refresh token.
  • api/secure-data.php: Secure endpoint; only accessible with a valid access token.
  • .env: Contains your secret keys (JWT_SECRET and JWT_REFRESH_SECRET).
• Installation:
     

  composer require firebase/php-jwt

   

1. Generating a Token (login.php)

<?php
require __DIR__ . '/vendor/autoload.php';
use Firebase\JWT\JWT;

// Load secret from .env
$secret       = getenv('JWT_SECRET');
$refreshSecret= getenv('JWT_REFRESH_SECRET');

// Validate user...
if (validUser($_POST['email'], $_POST['password'])) {
    $now = time();
    $accessPayload = [
        'iss' => 'https://your-domain.com',
        'aud' => 'https://your-domain.com',
        'iat' => $now,
        'exp' => $now + 900,      // 15 minutes
        'sub' => getUserId(),
        'role'=> 'user'
    ];
    $refreshPayload = [
        'iss' => 'https://your-domain.com',
        'aud' => 'https://your-domain.com',
        'iat' => $now,
        'exp' => $now + 604800,   // 1 week
        'sub' => getUserId()
    ];
    $accessToken  = JWT::encode($accessPayload, $secret, 'HS256');
    $refreshToken = JWT::encode($refreshPayload, $refreshSecret, 'HS256');
    echo json_encode(['accessToken'=>$accessToken, 'refreshToken'=>$refreshToken]);
    exit;
}
http_response_code(401);
echo json_encode(['error'=>'Invalid credentials']);

2. Validating a Token (secure-data.php)

<?php
require __DIR__ . '/vendor/autoload.php';
use Firebase\JWT\JWT;
use Firebase\JWT\Key;

$secret = getenv('JWT_SECRET');
$auth   = $_SERVER['HTTP_AUTHORIZATION'] ?? '';
if (preg_match('/Bearer\s(\S+)/', $auth, $m)) {
    try {
        $token = $m[1];
        $decoded = JWT::decode($token, new Key($secret, 'HS256'));
        // Check iss and aud
        if ($decoded->iss !== 'https://your-domain.com' || $decoded->aud !== 'https://your-domain.com') {
            throw new Exception('Invalid token issuer or audience');
        }
        echo json_encode(['data'=>'Secure information']);
        exit;
    } catch (Exception $e) {
        http_response_code(401);
        echo json_encode(['error'=>'Access denied']);
        exit;
    }
}
http_response_code(401);
echo json_encode(['error'=>'No token found']);

3. Refresh Endpoint (refresh.php)

<?php
require __DIR__ . '/vendor/autoload.php';
use Firebase\JWT\JWT;
use Firebase\JWT\Key;

$refreshSecret = getenv('JWT_REFRESH_SECRET');
$body = json_decode(file_get_contents('php://input'), true);
try {
    $decoded = JWT::decode($body['refreshToken'], new Key($refreshSecret, 'HS256'));
    $now = time();
    $newAccess = [
        'iss'=>'https://your-domain.com','aud'=>'https://your-domain.com',
        'iat'=>$now,'exp'=>$now+900,'sub'=>$decoded->sub
    ];
    $token = JWT::encode($newAccess, getenv('JWT_SECRET'), 'HS256');
    echo json_encode(['accessToken'=>$token]);
} catch (Exception $e) {
    http_response_code(401);
    echo json_encode(['error'=>'Invalid refresh token']);
}

Part 2: The Ionic Vue App – API Communication with Axios

In this part, we'll build the frontend in Ionic Vue. We will install Axios, create a service for all our API calls including refresh token rotation, and implement secure storage.

1. Secure Storage & Axios Setup

First, install the secure storage plugin for Capacitor:

npm install @capacitor-community/secure-storage

// src/services/AxiosService.js
import axios from 'axios';
import { SecureStoragePlugin } from '@capacitor-community/secure-storage';

const API_URL = import.meta.env.VITE_API_URL || 'https://your-domain.com/api';
const storage = new SecureStoragePlugin();

const axiosInstance = axios.create({ baseURL: API_URL, headers:{'Content-Type':'application/json'} });

axiosInstance.interceptors.request.use(async config => {
  const token = await storage.get({ key:'accessToken' });
  if (token.value) config.headers.Authorization = `Bearer ${token.value}`;
  return config;
});

export default axiosInstance;

2. Login & Token Storage (LoginPage.vue)

<script setup>
import { SecureStoragePlugin } from '@capacitor-community/secure-storage';
import axiosService from '@/services/AxiosService';
const storage = new SecureStoragePlugin();

async function handleLogin() {
  const resp = await axiosService.post('/login.php', params);
  await storage.set({ key:'accessToken', value:resp.data.accessToken });
  await storage.set({ key:'refreshToken', value:resp.data.refreshToken });
  router.push('/tabs/dashboard');
}
</script>

3. Refresh Logic

In your interceptor, you can automatically make a refresh call on a 401 error:

axiosInstance.interceptors.response.use(null, async error => {
  if (error.response?.status === 401) {
    const refresh = await storage.get({key:'refreshToken'});
    const { data } = await axios.post('/refresh.php', { refreshToken: refresh.value });
    await storage.set({key:'accessToken', value:data.accessToken});
    error.config.headers.Authorization = `Bearer ${data.accessToken}`;
    return axiosInstance.request(error.config);
  }
  return Promise.reject(error);
});

Best Practices & Security

• Always use HTTPS for transport security.
• Store tokens in secure storage (e.g., Capacitor Secure Storage), not in localStorage.
• Implement access and refresh token rotation for short-lived sessions.
• Always validate iss, aud, and alg on the server side.
• Limit the token payload to the minimum necessary data.

Conclusion

This guide highlights that true security starts with a "security-first" architecture: short-lived tokens, a dual-token strategy, secure client-side storage, and strict server-side validation. With this layered approach, you can build a resilient, production-ready headless application that is resistant to modern threats.

Het bericht Secure Headless Architecture with Ionic Vue and a PHP JWT API verscheen eerst op Utilewebsites.

1. Install Required Packages Add the necessary libraries to your project:

npm install pdfjs-dist @capacitor/filesystem @capacitor-community/http

2. Component Code (Web en Mobile)
Add the following code as a component in your Ionic Vue project:

<template>
  <ion-page>
    <ion-header>
      <ion-toolbar>
        <ion-title>PDF Viewer</ion-title>
      </ion-toolbar>
    </ion-header>
    <ion-content class="ion-padding">
      <ion-button @click="downloadAndRenderPdf">Download PDF</ion-button>
      <!-- PDF.js rendering container -->
      <div v-if="pdfUrl">
        <canvas ref="pdfCanvas" style="width: 100%;"></canvas>
      </div>
    </ion-content>
  </ion-page>
</template>

<script>
import { defineComponent, watch } from "vue";
import { IonPage, IonHeader, IonToolbar, IonTitle, IonContent, IonButton } from "@ionic/vue";
import { Filesystem, Directory } from "@capacitor/filesystem";
import { CapacitorHttp } from "@capacitor/core";
import * as pdfjsLib from 'pdfjs-dist/legacy/build/pdf';

// Set the workerSrc to the imported worker
pdfjsLib.GlobalWorkerOptions.workerSrc = new URL(
  "pdfjs-dist/build/pdf.worker.min.mjs",
  import.meta.url
).toString();

import { Capacitor } from '@capacitor/core';

// Add detailed platform and path logging
const platform = Capacitor.getPlatform();
console.log('Platform detection:', {
  platform,
  isAndroid: platform === 'android',
  isWeb: platform === 'web'
});

export default defineComponent({
  name: "TestpdfPage",
  components: {
    IonPage,
    IonHeader,
    IonToolbar,
    IonTitle,
    IonContent,
    IonButton,
  },
  data() {
    return {
      pdfUrl: null, // URL of the PDF to be rendered
    };
  },
  methods: {
    // Method to download and render the PDF
    async downloadAndRenderPdf() {
      try {
        console.log("Starting PDF download process...");

        const pdfUrl = "https://example.com/sample.pdf";
        const fileName = "temp.pdf";
        const dirPath = "downloaded";
        const savedFilePath = `${dirPath}/${fileName}`;

        console.log("Downloading PDF using CapacitorHttp from:", pdfUrl);

        // Clean up the existing directory
        try {
          await Filesystem.rmdir({
            path: dirPath,
            directory: Directory.Data,
            recursive: true,
          });
          console.log("Cleaned up existing directory");
        } catch (e) {
          console.log("No existing directory to clean up");
        }

        // Download PDF using native HTTP
        const response = await CapacitorHttp.get({
          url: pdfUrl,
          responseType: "arraybuffer",
        });

        console.log("Download response:", response);

        // Check if response.data is a string (Base64) or an ArrayBuffer
        let base64Data;
        if (typeof response.data === 'string') {
          // Data is already Base64-encoded
          base64Data = response.data;
          console.log("Received data is a Base64 string");
        } else {
          // Convert ArrayBuffer to Base64
          base64Data = this.arrayBufferToBase64(response.data);
          console.log("Converted ArrayBuffer to Base64");
        }

        console.log("Base64 data length:", base64Data.length);

        // Save to device storage
        try {
          await Filesystem.mkdir({
            path: dirPath,
            directory: Directory.Data,
            recursive: true,
          });
          console.log("Created directory for PDF");

          await Filesystem.writeFile({
            path: savedFilePath,
            data: base64Data,
            directory: Directory.Data,
          });

          console.log("File saved locally");

          // Check if the file exists and get its size
          const fileStat = await Filesystem.stat({
            path: savedFilePath,
            directory: Directory.Data,
          });

          console.log("File exists:", fileStat.uri);
          console.log("File size in bytes:", fileStat.size);

          if (fileStat.size === 0) {
            console.error("Downloaded file is empty.");
            return;
          }

          // Set the PDF URL to display it
          this.pdfUrl = "data:application/pdf;base64," + base64Data;
        } catch (fsError) {
          console.error("Filesystem Error:", fsError);
          throw fsError;
        }
      } catch (error) {
        console.error("Operation Failed:", error);
      }
    },
    // Method to render the PDF on a canvas
    async renderPdf() {
      console.log("Starting PDF rendering process...");

      const canvas = this.$refs.pdfCanvas;
      if (!canvas) {
        console.error("Canvas element not found");
        return;
      }
      console.log("Canvas element found");

      const ctx = canvas.getContext("2d");
      if (!ctx) {
        console.error("Failed to get 2D context");
        return;
      }
      console.log("2D context obtained");

      try {
        const pdf = await pdfjsLib.getDocument(this.pdfUrl).promise;
        console.log("PDF document fetched successfully");

        const page = await pdf.getPage(1);
        console.log("Page 1 of PDF document fetched successfully");

        const viewport = page.getViewport({ scale: 1.5 });
        console.log("Viewport created with scale 1.5");

        canvas.width = viewport.width;
        canvas.height = viewport.height;
        console.log("Canvas dimensions set to width:", viewport.width, "height:", viewport.height);

        const renderContext = {
          canvasContext: ctx,
          viewport: viewport,
        };

        console.log("Starting PDF page render");
        await page.render(renderContext).promise;
        console.log("PDF rendered successfully");
      } catch (error) {
        console.error("Error rendering PDF:", JSON.stringify(error, Object.getOwnPropertyNames(error)));
      }
    },
    // Helper method to convert ArrayBuffer to Base64
    arrayBufferToBase64(buffer) {
      let binary = "";
      const bytes = new Uint8Array(buffer);
      const len = bytes.byteLength;
      for (let i = 0; i < len; i++) {
        binary += String.fromCharCode(bytes[i]);
      }
      return btoa(binary);
    },
  },
  watch: {
    // Watcher to render the PDF when the URL changes
    pdfUrl(newUrl) {
      if (newUrl) {
        this.$nextTick(() => {
          this.renderPdf();
        });
      }
    }
  }
});
</script>

3. Explanation

• HTTP Plugin: Safely downloads files on mobile devices.
• Filesystem Plugin: Saves files locally in the Documents directory, critical for Android/iOS.
• PDF.js: Responsible for rendering PDFs into a canvas element.

4. Compatibility

• Android/iOS: Ensure permissions are set for file access in AndroidManifest.xml and Info.plist.
• Web: PDF.js works directly with external URLs without requiring local storage.

Het bericht Steps to Download and Display a PDF in an Ionic Vue App (Android/iOS): verscheen eerst op Utilewebsites.