verimatrixinc/content-proxy

Content Proxy 镜像文档

镜像概述和主要用途

Content Proxy 是一个基于 ExpressJs 的应用镜像，旨在作为访问内容授权 JSON Web 令牌 (JWT) 的代理服务。它包含默认的权限检查中间件（默认始终返回 true，即所有设备都有权访问内容）和令牌生成中间件（用于生成访问内容的 JWT）。默认权限检查提供了示例实现，用户可根据需求自定义覆盖。

核心功能和特性

• 内容授权代理：作为访问内容授权 JWT 的代理服务，处理权限验证和令牌生成请求
• 默认权限检查：内置默认权限检查中间件，始终返回 true，允许所有设备访问所有内容
• 令牌生成：提供令牌生成中间件，生成用于访问内容的 JWT
• 可扩展性：支持自定义权限检查中间件，用户可替换默认实现以满足特定业务需求
• 环境变量配置：通过环境变量灵活配置服务参数，如端口、发行者、受众等

使用场景和适用范围

• 快速部署内容授权代理服务，用于开发或测试环境
• 作为自定义权限检查系统的基础框架，减少从零开发的工作量
• 需要临时授权机制的场景，默认权限检查可快速启用基础授权功能

使用方法和配置说明

基本运行（仅需必填配置）

bash
docker run \
  --env OPERATOR_KEY_ID="[key-id]" \
  --env OPERATOR_ISSUER="[issuer]" \
  --env OPERATOR_AUDIENCE="[audience]" \
  verimatrixinc/content-proxy

带可选配置的运行

bash
docker run \
  --env OPERATOR_KEY_ID="[key-id]" \
  --env OPERATOR_ISSUER="[issuer]" \
  --env OPERATOR_AUDIENCE="[audience]" \
  --env SERVER_PORT="80" \
  --env DEFAULT_ENTITLEMENT_ENABLED="true" \
  verimatrixinc/content-proxy

配置参数说明

必填环境变量

• OPERATOR_KEY_ID：用于保护令牌的密钥标识符
• OPERATOR_ISSUER：令牌的发行者标识符
• OPERATOR_AUDIENCE：令牌的目标受众标识符

可选环境变量

• SERVER_PORT：服务运行端口，默认值：80
• DEFAULT_ENTITLEMENT_ENABLED：是否启用默认权限检查，启用时始终返回 true，默认值：true

密钥管理

本镜像不包含内置的密钥管理功能，用户需自行确保私钥和密钥的安全。以下是使用 AWS Secrets Manager 进行密钥管理的示例：

AWS Secrets Manager 示例

通过 AWS SDK 从 Secrets Manager 获取密钥：

javascript
import * as AWS from "aws-sdk";

export async function getAwsSecret(secretId: string): Promise<string> {
  const secretsManager = new AWS.SecretsManager();
  const value = (await secretsManager.getSecretValue({ SecretId: secretId }).promise()).SecretString;

  if (!value) {
    throw new Error("无法从 Secrets Manager 获取值");
  }

  return value;
}

获取的密钥值为 JSON 对象，格式如下：

json
{
  "privateKey": "some private key",
  "secret": "some secret"
}

解析后用于调用令牌生成中间件：

javascript
fetchSecrets(config.get<string>('secretId')).then(secret => {
  const secretObj = JSON.parse(secret);
  app.use(tokenGenerator({ privateKey: secretObj.privateKey }));
  // 服务器启动逻辑
});

默认权限检查（Default Entitlement Check）

默认权限检查是一个中间件，提供自定义权限检查的基础框架。默认情况下，它始终成功并允许所有设备访问所有内容。

实现位置

中间件位于 /middleware/default 目录下，实现文件为 index.ts。

启用条件

当 DEFAULT_ENTITLEMENT_ENABLED 设为 true 时启用：

javascript
if (config.get<boolean>("defaultEntitlement.enabled")) app.use(defaultEntitlement());

请求要求

若启用默认权限检查，请求需包含查询参数 _vdis（设备 ID）和 subject（内容 ID），无论其值如何，请求均会成功。

自定义建议

用户可在 /middleware 目录下创建自定义权限检查中间件，并按照默认中间件的实现方式集成到服务中。

推荐和测试负载场景

请参考 负载测试场景和建议文档。

本地开发

环境要求

• node
• yarn
• 可选：https://github.com/nvm-sh/nvm%EF%BC%88%E7%94%A8%E4%BA%8E%E7%AE%A1%E7%90%86 Node 版本）

本地运行服务器步骤

bash
nvm use  # 使用正确的 Node 版本
yarn install  # 安装依赖
yarn start  # 使用 nodemon 启动服务器

./src 目录下的文件更新会触发服务器重启。

配置方式

配置通过 "config" npm 包 管理，支持设置默认变量，并可通过环境变量或按环境覆盖配置。