JWT authentication (PHP)

简介

TinyMCE AI 需要设置 JSON Web Token (JWT) 身份验证，以保持对 AI 功能访问的控制。JWT 端点生成并提供授权令牌，用于验证用户是否有权使用 AI 功能，防止未经授权的访问。作为标准的 Web 服务授权解决方案，JWT 在 https://jwt.io/ 上有详细的文档说明。TinyMCE 建议使用 jwt.io/libraries 上列出的库来创建 JWT 令牌。

本指南提供了将 TinyMCE AI 与 TinyMCE 集成的全面演练，包括 TinyMCE AI 的功能，通过使用 PHP 服务器生成 JWT 令牌。它涵盖了项目设置、服务器配置和 TinyMCE 定制。

将构建的内容

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

• 一个运行 TinyMCE AI 插件的可用 TinyMCE 编辑器

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

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

本指南是为不熟悉 JWT 身份验证和 TinyMCE 集成的开发人员设计的。

先决条件

在开始之前，请确保您已经：

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

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

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

• 拥有一个启用了 TinyMCE AI 的 TinyMCE API 密钥（从 Tiny 网站获取）

• 基本熟悉命令行

确保在开始之前准备好 API 密钥。服务器和客户端配置都需要它。

更新 PHP 配置文件

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

php --ini

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

extension=openssl
extension_dir='ext'

扩展目录的路径可能因系统而异。

快速入门指南

项目设置

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

创建项目结构

# 创建用于 Web 文件的公共文件夹
touch index.html
touch jwt.php

项目应该如下所示：

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

生成公钥/私钥对

TinyMCE AI 服务器需要由将用于 JSON Web Token (JWT) 提供者端点的相同 私钥 生成的 公钥。存储在 TinyMCE AI 服务器上的公钥用于确保内容是由授权用户发送的。

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

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

2. 在本地生成密钥对并在 Tiny 账户 - JWT 密钥 处导入公钥。

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

Tiny 账户 - JWT 密钥页面提供了一个“生成新密钥对”选项，提供了一种快速且安全的生成所需密钥的方法。这将存储公钥的副本，并提供一个可下载的文件，包含公钥和私钥。Tiny 不会存储私钥，并且密钥对以后无法检索。

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

这种方法涉及两个步骤：在本地生成密钥对，然后将公钥添加到账户门户。

在本地生成密钥对

在本地生成密钥对时，请使用一种支持的算法。TinyMCE AI 不支持对称加密算法，例如 HS256。Tiny 建议使用 RS256 算法。以下算法是支持的：

• RS256

• RS384

• RS512

• PS256

• PS384

• PS512

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

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

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

一旦在本地生成了公钥，请使用账户门户的 JWT 密钥部分的“导入公钥”选项，地址为：Tiny 账户 - JWT 密钥。

JWT 配置要求

本节解释了 JWT 身份验证需要进行哪些配置，无论是使用托管服务（如 AWS 或 Azure JWT 服务）还是设置手动端点。

有关 JWT 要求、声明和权限的完整信息，请参阅 JWT 身份验证。

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

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

图 1. JSON Web Token 调用流程

当用户打开 TinyMCE AI 时：

1. TinyMCE AI 代表用户请求一个已签名的 JWT。

2. 如果您的 JWT 端点授权该用户，您的 JWT 端点将向 TinyMCE AI 发送一个 JWT，以认证该用户。

3. 该 JWT 包含一个 sub（subject，主题）声明，用于标识用户。此用户标识符用于将对话历史、AI 生成的内容以及其他用户特定数据锁定到各个用户，确保隐私性和数据隔离性。

4. 当用户发出请求（例如开始聊天对话、请求 AI 操作或提交审核）时，JWT 将随请求一起发送，以表明该用户已获得授权。该 JWT 使用存储在 AI 服务上的公钥进行验证。

5. AI 服务发送响应，指示请求成功（或在必要时指示未授权）。

JWT 端点要求

TinyMCE AI 的 JSON Web Token (JWT) 端点需要满足以下条件：

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

• 用户身份验证：一种验证用户身份以及他们是否应有权访问 TinyMCE AI 的方法。

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

• 端点或服务器生成包含令牌的 JSON 响应。TinyMCE AI 会将该令牌随请求提交给 AI 服务。

TinyMCE AI 所需的 JWT 声明

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

aud （必需）

类型： String

aud 是一个区分大小写的字符串，必须与已启用 TinyMCE AI 插件的有效 API 密钥匹配。

sub （必需）

类型： String

sub 声明标识用户。这应该是发出请求的用户的的唯一标识符。有关长度限制和会话要求，请参阅负载属性。

iat （必需）

类型： Number

iat 代表签发时间戳，以秒数指定。例如，要将签发时间设置为当前时间戳，请将签发时间计算为当前时间戳除以 1000。

示例

"iat" => time(),  // 签发时间戳

exp （必需）

类型： Number

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

示例

"exp" => time() + (60 * 10),  // 过期时间（10 分钟）

auth （必需）

类型： Object

auth 对象包含 AI 特定的权限，用于控制用户可以访问哪些功能。

以下示例授予对对话、推荐的代理模型以及系统操作和审核的访问权限。有关可用权限的完整列表，请参阅 权限。

示例

auth: {
  ai: {
    permissions: [
      "ai:conversations:read",
      "ai:conversations:write",
      "ai:models:agent",
      "ai:actions:system:*",
      "ai:reviews:system:*"
    ]
  }
}

有关可用权限的完整列表以及配置用户访问权限的最佳实践，请参阅 权限。

设置 JWT 端点

以下部分介绍如何手动创建 JWT 端点。如果使用托管的 JWT 服务（例如 AWS 或 Azure），请根据上述要求进行配置，并跳转到“配置 TinyMCE”部分。

服务器设置 (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", // 替换为实际的 API 密钥
    "sub" => "user-id", // 替换为实际的用户标识符
    "iat" => time(), // 签发时间戳
    "exp" => time() + 60 * 10, // 过期时间（10 分钟）
    // 权限控制用户可访问的 AI 功能。详见权限页面以获取完整信息。
    "auth" => array(
        "ai" => array(
            "permissions" => array(
                "ai:conversations:read",
                "ai:conversations:write",
                "ai:models:agent",
                "ai:actions:system:*",
                "ai:reviews:system:*"
            )
        )
    )
);

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());
}
?>

JWT 有效载荷包含一个 auth.ai.permissions 数组，用于定义用户可访问的 AI 功能。根据需求调整这些权限。有关可用权限的更多详细信息，请参阅 权限。

配置 TinyMCE

网页（index.html）

在创建 index.html 文件的根目录内，添加 HTML 设置代码。

<!DOCTYPE html>
<html>
<head>
  <title>{productname} with {pluginname}</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: 'tinymceai',
      toolbar: 'tinymceai-chat tinymceai-quickactions tinymceai-review',
      // tinymceai_token_provider 从 `/jwt.php` 端点获取令牌。
      // 本演示不验证用户会话；它模拟一个已认证的用户。在返回令牌之前请集成您的身份验证。
      tinymceai_token_provider: () => {
        return fetch('http://localhost:3000/jwt.php', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
        }).then(response => response.json());
      },
    });
  </script>
</head>
<body>
  <h1>{pluginname} Demo</h1>
  <textarea>
    欢迎使用 {productname}！尝试聊天、快速操作和审查等 AI 功能。
  </textarea>
</body>
</html>

模型配置

可以使用 tinymceai_default_model 和 tinymceai_allow_model_selection 来配置模型选择。有关详细信息，请参阅 聊天模型配置。模型访问权限由 JWT 权限控制；有关可用模型权限的信息，请参阅 模型权限，有关可用模型的列表，请参阅 AI 模型。

示例：将模型选项添加到 JWT 设置

tinymce.init({
  selector: 'textarea',
  plugins: 'tinymceai',
  toolbar: 'tinymceai-chat tinymceai-quickactions tinymceai-review',
  tinymceai_default_model: 'agent-1',
  tinymceai_allow_model_selection: true,
  // 本演示不验证用户会话；它模拟一个已认证的用户。在返回令牌之前请集成您的身份验证。
  tinymceai_token_provider: () => {
    return fetch('http://localhost:3000/jwt.php', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
    }).then(response => response.json());
  },
});

配置与运行

配置步骤

添加 API 密钥

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

• HTML 脚本源和 JWT 有效载荷中的 API 密钥应相同

添加私钥

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

• 确保它是 PKCS8 格式

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

配置 AI 权限

• 根据需求调整 JWT 有效载荷中的 auth.ai.permissions 数组

• 有关可用权限和最佳实践的信息，请参阅 权限

配置模型选择（可选）

• 如果需要，将 tinymceai_default_model 和 tinymceai_allow_model_selection 添加到编辑器配置中

• 有关详细信息，请参阅模型配置

运行项目

1. 启动服务器：

   php -S localhost:3000

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

3. 应显示以下内容：

   • TinyMCE 编辑器

   • 工具栏中的 AI 功能按钮（tinymceai-chat、tinymceai-quickactions、tinymceai-review）