简介

“从 Word 导入”功能需要设置 JSON Web Token (JWT) 认证，以保持对文件安全性的控制。JWT 端点生成并提供授权令牌，用于验证提交的内容由授权用户发送，防止未授权访问。作为标准的 Web 服务授权解决方案，JWT 的文档可在 https://jwt.io/ 上找到。

本指南提供了将“从 Word 导入”功能与 TinyMCE 集成的全面操作步骤，包括“从 Word 导入”功能，通过使用 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 端点授权该用户，端点将向“从 Word 导入”功能发送一个 JWT，以证明该用户已获得授权。

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

  4. “从 Word 导入”服务器会发送响应，表示内容提交成功（或在必要时返回未授权信息）。

JWT 端点要求

用于“从 Word 导入”功能的 JSON Web Token（JWT）端点需要满足以下条件：

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

  • 用户身份验证 - 必须有一种方法来验证用户身份，并确认其应具有对“从 Word 导入”功能的访问权限。

  • JWT 必须使用与提供给 Tiny 账户 - JWT 密钥的公钥配对的私钥进行签名生成。

  • 端点或服务器需生成包含令牌的 JSON 响应。“从 Word 导入”功能会将该令牌随请求一起提交给“从 Word 导入”服务器。

“从 Word 导入”功能所需的 JWT 声明

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

aud (必选)

类型：字符串

aud 是一个大小写敏感的字符串，必须与已启用“从 Word 导入”插件的有效 API 密钥匹配。

iat (必选)

类型：数字

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

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

类型：数字

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: 'importword',
      toolbar: 'importword',
      importword_converter_options: {
        'format': 'Letter',
        'margin_top': '1in',
        'margin_right': '1in',
        'margin_bottom': '1in',
        'margin_left': '1in'
      },
      // importword_token_provider 从 `/jwt.php` 端点获取令牌。
      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 Word 导入演示</h1>
  <textarea>
    欢迎使用 TinyMCE！尝试使用“从 Word 导入”功能。
  </textarea>
</body>
</html>

配置步骤

添加您的 API 密钥

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

  • API 密钥在 HTML 脚本源和 JWT 有效负载中应保持一致。

添加您的私钥

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

  • 确保它是 PKCS8 格式

  • 保持此密钥安全，切勿公开分享

运行您的项目

  1. 启动服务器：

    php -S localhost:3000

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

  3. 您应该会看到：

    • TinyMCE 编辑器

    • 工具栏中的“从 Word 导入”按钮