会话与安全

文档会话和访问控制

一个 Doconut 令牌标识一个打开的文档。如果任何携带该令牌的请求被处理,获取它的人就可以读取所有页面。本页解释文档会话包含什么、它的存活时间,以及 DocImage.axd 如何决定谁可以查看其页面——在单服务器和 Web 农场中。

文档会话包含的内容

每次成功的 OpenDocumentAsync 都会创建一个会话,保存在内存中:

  • 已加载的格式查看器 — 持有已解析文档的引擎实例,
  • 每页状态 — 旋转、翻转以及用户在小部件中应用的注释数据,
  • 可选的 搜索索引,在第一次搜索时构建(或从预构建的 .srh 文件加载),
  • 来自 DocOptions.Watermark 的会话 水印。

生命周期

会话在 滑动窗口 中过期:DocOptions.TimeOut 分钟(默认 60),每次呈现令牌的请求都会重置。当会话结束——因过期或因 CloseDocument(token) ——其文档引擎被释放,内存立即被清理。

csharp
// 一次性预览的短期会话
var token = await viewer.OpenDocumentAsync(path, new DocOptions { TimeOut = 10 });

使用已过期令牌的请求会收到显示 Document session not found. Please re-open document. 的错误图片。页面必须重新打开文档以获取新令牌。在单服务器上,回收应用程序池也会结束所有会话。

页面仅向打开它们的会话提供服务

使用 UnsafeMode = false —— 默认设置 —— 打开文档时会通过在该会话中写入 secure-{token} 条目,授予 打开请求的 ASP.NET 会话 访问权限。DocImage.axd 本身需要会话状态,并且仅在请求的会话持有该条目时才提供页面。任何其他浏览器呈现相同令牌时会收到显示 You Are Not Authorized To View This Page. 的错误图片。

csharp
Doconut.DoconutHost.Initialize(options =>
{
    // false(默认):DocImage.axd 仅向打开它的 ASP.NET 会话提供页面
    // 文档。处理程序自行请求会话状态;它只需要站点不要
    // 在 Web.config 中关闭会话状态。
    options.UnsafeMode = false;
});

三个实际后果:

  • 打开端点需要会话状态。 MVC 控制器和 Web Forms 页面默认拥有会话状态。自定义 IHttpHandler 除非实现了 System.Web.SessionState.IRequiresSessionState,否则没有会话。没有会话的打开操作没有可授予的内容,因此查看器在每个页面上显示 “您无权查看此页面。”
  • 会话状态必须保持开启。 在 Web.config 中的 <sessionState mode="Off" /> 会同时禁用授予和检查,导致所有页面被拒绝。
  • 浏览器必须发送会话 Cookie。 小部件的请求是同源的,因此会自动携带 ASP.NET_SessionId。没有 Cookie 桶的客户端——脚本、服务器到服务器的调用、剥离 Cookie 的跨域设置——会被拒绝。这正是该功能的工作方式。

UnsafeMode = true 关闭检查:任何携带令牌的请求都会被服务。这是针对每个文档的全局开关,没有每文档的覆盖。保持它为 false。

撤销

CloseDocument(token) 不仅仅是释放内存:它会从当前请求的会话中移除 secure-{token} 条目并撤销令牌,从而立即拒绝已关闭的令牌。

Web 农场:签名票据

在农场中,后续请求可能落在从未见过该文档的服务器上,或不同的工作进程中,拥有自己的 ASP.NET 会话。会话授予无法随之传递。分布式模式用绑定到浏览器的 签名票据 替代它:每个节点共享一个文档会话存储和一个签名密钥,DocImage.axd 在票据对该令牌、该浏览器以及——当用户已登录时——该用户有效时接受请求。

该设置在每个节点上都是相同的:

csharp
// Global.asax.cs - Application_Start
// 集群密钥:至少 32 字节,在每个节点上相同,且不放入源代码管理。
byte[] farmKey = Convert.FromBase64String(Environment.GetEnvironmentVariable("DOCONUT_FARM_KEY"));

Doconut.DoconutHost.Initialize(
    options => options.UnsafeMode = false,     // 仅当此为 false 时才运行票据检查
    services => services.AddDoconutDistributed(d =>
    {
        d.Store             = CloudLocation.FileShare;
        d.FileShareRootPath = @"\\fileserver\doconut-shared";  // 每个节点都能访问的文件夹
        d.SigningKey        = farmKey;                          // 至少 32 字节,在每个节点上相同
    }));

打开端点随后在打开之前将票据绑定到浏览器,并随令牌一起返回票据:

  • 设置 DocOptions.BrowserId = DoconutFarmBinding.EnsureBrowserId(System.Web.HttpContext.Current, securityOptions) —— 它会发放与票据绑定的 doconut-client Cookie —— 并且 DocOptions.UserId = DoconutFarmBinding.ResolveUserId(System.Web.HttpContext.Current);
  • 在 OpenDocumentAsync 之后,返回与令牌一起的 viewer.AccessToken;
  • 在页面中,将两者传递给小部件:objViewer.View(token, access)。

从经典的 web-farm 标志(IsWebfarm 与 ExportToPng)迁移?迁移 逐步展示了更改过程。

将签名密钥保留在源代码控制之外:它既用于签署票据,也用于加密共享存储中的文档。使用不同密钥的节点会拒绝其他节点签发的所有票据。

使用真实浏览器或保持 Cookie 的脚本测试农场。没有 doconut-client Cookie 的客户端不会收到 401 的响应:它会收到状态为 200、约 2 KB 的 “未授权” 错误图片,而真实页面的大小是数十到数百千字节。

生产检查清单

  • 保持 UnsafeMode = false(默认)。
  • 从拥有会话状态的请求打开文档,且永不关闭会话状态。
  • 确保会话 Cookie 能到达 DocImage.axd(同源、HTTPS、允许的 SameSite 策略)。
  • 在农场中,使用分布式模式,并使用所有节点共享的单一签名密钥。
  • 当用户离开文档时调用 CloseDocument —— 可提升内存和安全性。
  • 永不记录或共享令牌;将其视为短期凭证。

此页面对您有帮助吗?