Import from Word with JWT authentication (PHP) Guide

Introduction

Import from Word requires setting up JSON Web Token (JWT) authentication to maintain control over file security. A JWT endpoint generates and provides authorization tokens that verify submitted content is sent by authorized users, preventing unauthorized access. As a standard web services authorization solution, JWT is documented extensively at https://jwt.io/.

This guide provides a comprehensive walkthrough for integrating Import from Word with TinyMCE, including Import from Word functionality, by using a PHP server for JWT token generation. It covers project setup, server configuration, and TinyMCE customization.

What You’ll Build

Before diving into the technical details, here’s what you’ll achieve with this guide:

A working TinyMCE editor running the Import from Word plugin
A secure authentication system using JWT tokens
A simple PHP server to handle the authentication

This guide is designed for developers new to JWT authentication and TinyMCE integration.

Prerequisites

Before starting, ensure you have:

PHP installed on your computer (to check, run php -v in your terminal)
OpenSSL installed on your computer (to check, run openssl version in your terminal)
Composer installed on your computer (to check, run composer -v in your terminal)
A TinyMCE API key (get one from TinyMCE’s website)
Basic familiarity with the command line

Make sure you have your API key ready before starting. You’ll need it for both the server and client configuration.

Update PHP Configuration File

Use the following command to locate the PHP configuration file:

php --ini

Open the configuration file in a text editor and ensure the following settings are enabled:

extension=openssl
extension_dir='ext'

The path to the extension directory may vary depending on your system.

Quick Start Guide

Project Setup

# Create and enter project directory
mkdir tinymce-app
cd tinymce-app
# Initialize Composer
composer require firebase/php-jwt

Create Project Structure

# Create the public folder for your web files
touch index.html
touch jwt.php

Your project should look like this:

/tinymce-app
  index.html  (TinyMCE webpage)
  jwt.php     (Server code)
  composer.json
  composer.lock
  vendor

Setup

Generate a Public/Private Key Pair

Setting up JWT authentication

To set up JSON Web Token (JWT) authentication for TinyMCE Import from Word:

Add a public key to your Tiny Account, login.
Set up a JSON Web Token (JWT) Provider endpoint via Tiny Account - JWT Keys
Configure your TinyMCE to use the JWT endpoint.

The Import from Word Server requires a public key generated from the same private key that will be used on your JSON Web Token (JWT) provider endpoint. The public key(s) stored on the Import from Word Server are used to ensure that content is sent by authorized users.

There are two methods for generating and adding a public key to your API key:

The secure key pair generator at Tiny Account - JWT Keys (recommended).
Generate a key pair locally and add the public key to Tiny Account - JWT Keys.

Generate a key pair using the Tiny Account JWT Keys page

The Tiny Account - JWT Keys page provides a private/public key generator, providing a quick and secure way of generating the required keys. This generator will store a copy of the public key, and provide a downloadable file for both the public and private keys. Tiny does not store the private key and the key pair cannot be retrieved later.

Generate a key pair locally

When generating a key pair locally, use one of the supported algorithms. Import from Word does not support symmetrical encryption algorithms, such as HS256. Tiny recommends using the RS256 algorithm. The following algorithms are supported:

RS256
RS384
RS512
PS256
PS384
PS512

For details on each of these algorithms, visit: RFC 7518, JSON Web Algorithms (JWA) Section 3 - Cryptographic Algorithms for Digital Signatures and MACs.

For instructions on generating a key pair locally, see: Creating a private/public key pair for Tiny Cloud.

Add a public key to the Tiny Cloud API key

Once a public key has been generated, add the public key to the Tiny Cloud API key at: Tiny Account - JWT Keys.

Set up a JSON Web Token (JWT) endpoint

A JSON Web Token (JWT) endpoint is a service for generating and providing authorization tokens to users. These tokens can then be used to verify that submitted content was sent by an authorized user and to prevent unauthorized access.

The following diagram shows how JWTs are used:

Figure 1. JSON Web Token Call Flow

When a user opens Import from Word:

JWT endpoint requirements

A JSON Web Token (JWT) endpoint for Import from Word requires:

The endpoint or server accepts a JSON HTTP POST request.
User authentication - A method of verifying the user, and that they should have access to the Import from Word.
The JWTs are generated (signed) using the private key that pairs with the public key provided to Tiny Account - JWT Keys.
The endpoint or server produces a JSON response with the token. Import from Word will submit the token with requests to the Import from Word Server.

Required JWT claims for Import from Word

JSON Web Tokens produced by the JWT endpoint must include the following claims:

aud (required): Type: String

The aud is case-sensitive string that must match a valid API key that has the Import from Word plugin enabled.
iat (required): Type: Number

The iat represents the issue timestamp, specified as the number of seconds. For example, to set the issue time to the current timestamp, calculate the issue time as the current timestamp divided by 1000.

Example

iat: Math.floor(Date.now() / 1000), // Issue timestamp

exp (required): Type: Number

The exp represents the expiration timestamp, specified as the number of seconds. For example, to set a validity period of 10 minutes, calculate the expiration time as the current timestamp plus 600 seconds.

Example

exp: Math.floor(Date.now() / 1000) + (60 * 10) // Expiration time (10 minutes)

Server Setup (jwt.php)

In the root directory, copy and paste the server setup code into the jwt.php file.

<?php
require 'vendor/autoload.php'; // Setting up the Autoload
use \Firebase\JWT\JWT;

function fatalError($message) {
    http_response_code(500);
    header('Content-Type: application/json');
    die(json_encode(array("message" => "JWT auth failed: " . $message)));
}

// Check for OpenSSL extension
if (!extension_loaded('openssl')) {
    fatalError('You need to enable the openssl extension in your php.ini.');
}

// Enable CORS
header("Access-Control-Allow-Origin: *");
header("Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept");

// JWT payload
$payload = array(
    "aud" => "YOUR-API-KEY",
    "iat" => time(), // Issue timestamp
    "exp" => time() + 60 * 10 // Expiration time (10 minutes)
);

try {
    // Tokens are signed with the RS256 algorithm your private key
    $privateKey = <<<EOD
    -----BEGIN PRIVATE KEY-----
    {Your private PKCS8 key goes here}
    -----END PRIVATE KEY-----
    EOD;
    $token = JWT::encode($payload, $privateKey, 'RS256');

    http_response_code(200);
    header('Content-Type: application/json');
    echo json_encode(array("token" => $token));
} catch (Exception $e) {
    fatalError($e->getMessage());
}
?>

Web Page Setup (index.html)

Inside the public folder where you created the index.html file add the HTML setup code.

<!DOCTYPE html>
<html>
<head>
  <title>TinyMCE with Word Import</title>
  <script
    src="https://cdn.tiny.cloud/1/YOUR-API-KEY/tinymce/7/tinymce.min.js"
    referrerpolicy="origin">
  </script>
  <script>
    tinymce.init({
      selector: 'textarea',
      plugins: 'importword',
      toolbar: 'importword',
      importword_converter_options: {
        'format': 'Letter',
        'margin_top': '1in',
        'margin_right': '1in',
        'margin_bottom': '1in',
        'margin_left': '1in'
      },
      // importword_token_provider fetches a token from the `/jwt.php` endpoint.
      importword_token_provider: () => {
        return fetch('http://localhost:3000/jwt.php', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
        }).then(response => response.json());
      },
    });
  </script>
</head>
<body>
  <h1>TinyMCE Import Word Demo</h1>
  <textarea>
    Welcome to TinyMCE! Try the Import from Word feature.
  </textarea>
</body>
</html>

Configuration Steps

Add Your API Key

Replace YOUR-API-KEY in both files with your actual TinyMCE API key
The API key should be the same in both the HTML script source and the JWT payload

Add Your Private Key

Replace the private key placeholder in jwt.php with your actual private key
Make sure it’s in PKCS8 format
Keep this key secure and never share it publicly

Running Your Project

Start the server:
```
php -S localhost:3000
```
Open your browser to: http://localhost:3000
You should see:
- The TinyMCE editor
- An "Import from Word" button in the toolbar