简介

导出为 Word 需要配置 JSON Web Token (JWT) 身份验证，以保持对文件安全性的控制。JWT 端点生成并提供授权令牌，用于验证提交的内容来自已授权用户，从而防止未经授权的访问。JWT 作为标准的 Web 服务授权解决方案，详细文档可访问 https://jwt.io/。

本指南将全面介绍如何将导出为 Word 功能与 TinyMCE 集成，包括使用 PHP 服务器生成 JWT 令牌。内容涵盖项目设置、服务器配置以及 TinyMCE 的自定义。

您将构建的内容

在深入技术细节之前，以下是通过本指南您将实现的成果：

  • 一个运行导出为 Word 插件且可正常工作的 TinyMCE 编辑器

  • 一个使用 JWT 令牌的安全身份验证系统

  • 一个简单的 PHP 服务器来处理身份验证

本指南面向初次接触 JWT 身份验证和 TinyMCE 集成的开发者。

先决条件

在开始之前，请确保您具备以下条件：

  • 计算机上已安装 PHP（检查方法：在终端中运行 php -v）

  • 计算机上已安装 OpenSSL（检查方法：在终端中运行 openssl version）

  • 计算机上已安装 Composer（检查方法：在终端中运行 composer -v）

  • 一个 TinyMCE API 密钥（可从 TinyMCE 网站获取）

  • 基本的命令行操作知识

开始前请确保已准备好 API 密钥，服务器和客户端配置都需要用到它。

更新 PHP 配置文件

使用以下命令定位 PHP 配置文件：

php --ini

在文本编辑器中打开配置文件，确保启用以下设置：

extension=openssl
extension_dir='ext'
扩展目录的路径可能因系统而异。

快速入门指南

项目设置

# 创建并进入项目目录
mkdir tinymce-app
cd tinymce-app
# 初始化 Composer
composer require firebase/php-jwt

创建项目结构

# 创建用于存放 Web 文件的 public 文件夹
touch index.html
touch jwt.php

您的项目结构应如下所示：

/tinymce-app
  index.html  (TinyMCE 网页)
  jwt.php     (服务器代码)
  composer.json
  composer.lock
  vendor

配置

生成公钥/私钥对

设置 JWT 身份验证

要为 TinyMCE 导出为 Word 设置 JSON Web Token (JWT) 身份验证，请按以下步骤操作：

  1. 将公钥添加到您的 Tiny 账户，登录。

  2. 通过 Tiny 账户 - JWT 密钥 设置一个 JSON Web Token (JWT) 提供者端点

  3. 配置您的 TinyMCE 以使用 JWT 端点。

导出为 Word 服务器需要使用在 JSON Web Token (JWT) 提供者端点上生成的 私钥 对应的 公钥。存储在导出为 Word 服务器上的公钥用于确保内容来自已授权用户。

在账户门户的 JWT 密钥部分，有两种生成和添加公钥的方法：

  1. 在 Tiny 账户 - JWT 密钥 页面生成新的密钥对（推荐）。

  2. 在本地生成密钥对，然后在 Tiny 账户 - JWT 密钥 页面导入公钥。

使用 Tiny 账户 JWT 密钥页面生成密钥对

Tiny 账户 - JWT 密钥 页面提供“生成新密钥对”选项，可快速、安全地生成所需的密钥。该操作会存储一份 公钥 的副本，并提供一个包含公钥和私钥的可下载文件。Tiny 不会存储 私钥，且该密钥对之后无法找回。

在本地生成密钥对并添加到账户

此方法分为两步：在本地生成密钥对，然后将公钥添加到账户门户。

在本地生成密钥对

在本地生成密钥对时，需使用支持的算法之一。导出为 Word 不支持对称加密算法，如 HS256。Tiny 推荐使用 RS256 算法。支持的算法如下：

  • RS256

  • RS384

  • RS512

  • PS256

  • PS384

  • PS512

有关这些算法的详细信息，请访问：RFC 7518，JSON Web 算法 (JWA) 第 3 节 - 数字签名和 MAC 的加密算法。

关于在本地生成密钥对的说明，请参阅：为 Tiny Cloud 创建私钥/公钥对。

在账户门户的 JWT 密钥部分添加公钥

在本地生成公钥后，使用账户门户 JWT 密钥部分的“导入公钥”选项进行添加。位置：Tiny 账户 - JWT 密钥。

设置一个 JSON Web Token (JWT) 端点

JSON Web Token (JWT) 端点是用于生成并向用户提供授权令牌的服务。这些令牌可用于验证提交的内容是由已授权用户发送的，并防止未经授权的访问。

下图展示了 JWT 的使用方式：

JSON Web Token 调用流程图 1. JSON Web Token 调用流程

当用户打开“导出至 Word”功能时：

  1. “导出至 Word”功能会代表用户请求一个签名的 JWT。

  2. 如果您的 JWT 端点授权该用户，您的 JWT 端点将向“导出至 Word”功能发送一个 JWT，以证明该用户已获得授权。

  3. 当用户发出请求（例如导出文档）时，该 JWT 将随请求一起发送，以表明该用户已获得授权。此 JWT 会使用存储在“导出至 Word”服务器上的公钥进行验证。

  4. “导出至 Word”服务器会发送响应，指示内容提交是否成功（必要时会指示未授权）。

JWT 端点要求

“导出至 Word”功能的 JSON Web Token (JWT) 端点需要满足以下条件：

  • 端点或服务器接受 JSON HTTP POST 请求。

  • 用户身份验证 - 一种验证用户身份以及其应具有“导出至 Word”功能访问权限的方法。

  • JWT 是使用与提供给 Tiny Account - JWT Keys 的公钥配对的私钥生成（签名）的。

  • 端点或服务器生成包含令牌的 JSON 响应。“导出至 Word”功能会将此令牌随请求提交给“导出至 Word”服务器。

“导出至 Word”功能所需的 JWT 声明

由 JWT 端点生成的 JSON Web Token 必须包含以下声明：

aud (必需)

类型： String

aud 是一个区分大小写的字符串，必须与启用了“导出至 Word”插件的有效 API 密钥匹配。

iat (必需)

类型： Number

iat 代表签发时间戳，以秒为单位指定。例如，若要将签发时间设置为当前时间戳，则将当前时间戳除以 1000 来计算签发时间。

示例
iat: Math.floor(Date.now() / 1000), // 签发时间戳
exp (必需)

类型： Number

exp 代表过期时间戳，以秒为单位指定。例如，若要设置 10 分钟的有效期，则将过期时间计算为当前时间戳加上 600 秒。

示例
exp: Math.floor(Date.now() / 1000) + (60 * 10) // 过期时间（10 分钟）

服务器设置 (jwt.php)

在根目录下，将服务器设置代码复制并粘贴到 jwt.php 文件中。

<?php
require 'vendor/autoload.php'; // 设置自动加载
use \Firebase\JWT\JWT;

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

// 检查 OpenSSL 扩展
if (!extension_loaded('openssl')) {
    fatalError('您需要在 php.ini 中启用 openssl 扩展。');
}

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

// JWT 载荷
$payload = array(
    "aud" => "no-api-key",
    "iat" => time(), // 签发时间戳
    "exp" => time() + 60 * 10 // 过期时间（10 分钟）
);

try {
    // 令牌使用您的私钥通过 RS256 算法签名
    $privateKey = <<<EOD
    -----BEGIN PRIVATE KEY-----
    {在此放置您的 PKCS8 私钥}
    -----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());
}
?>

网页设置 (index.html)

在您创建了 index.html 文件的 public 文件夹内添加 HTML 设置代码。

<!DOCTYPE html>
<html>
<head>
  <title>带 Word 导出功能的 TinyMCE</title>
  <script
    src="https://cdn.tiny.cloud/1/no-api-key/tinymce/8/tinymce.min.js"
    referrerpolicy="origin"
    crossorigin="anonymous">
  </script>
  <script>
    tinymce.init({
      selector: 'textarea',
      plugins: 'exportword',
      toolbar: 'exportword',
      exportword_converter_options: {
        'format': 'Letter',
        'margin_top': '1in',
        'margin_right': '1in',
        'margin_bottom': '1in',
        'margin_left': '1in'
      },
      // exportword_token_provider 从 `/jwt.php` 端点获取令牌。
      exportword_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 导出至 Word 演示</h1>
  <textarea>
    欢迎使用 TinyMCE！试试导出至 Word 功能。
  </textarea>
</body>
</html>

配置步骤

添加您的 API 密钥

  • 将两个文件中的 no-api-key 替换为您实际的 TinyMCE API 密钥

  • HTML script 源和 JWT 载荷中的 API 密钥应相同

添加您的私钥

  • 将 jwt.php 中的私钥占位符替换为您的实际私钥

  • 确保它是 PKCS8 格式

  • 妥善保管此密钥，切勿公开分享

运行您的项目

  1. 启动服务器：

    php -S localhost:3000

  2. 在浏览器中打开：http://localhost:3000

  3. 您应该会看到：

    • TinyMCE 编辑器

    • 工具栏中的“导出为 Word”按钮