会话与安全
文档会话和访问控制
一个 Doconut 令牌标识一个打开的文档。如果任何携带该令牌的请求被处理,获取它的人就可以读取所有页面。本页解释文档会话包含什么、它的存活时间,以及 DocImage.axd 如何决定谁可以查看其页面——在单服务器和 Web 农场中。
文档会话包含的内容
每次成功的 OpenDocumentAsync 都会创建一个会话,保存在内存中:
- 已加载的格式查看器 — 持有已解析文档的引擎实例,
- 每页状态 — 旋转、翻转以及用户在小部件中应用的注释数据,
- 可选的 搜索索引,在第一次搜索时构建(或从预构建的
.srh文件加载), - 来自
DocOptions.Watermark的会话 水印。
生命周期
会话在 滑动窗口 中过期:DocOptions.TimeOut 分钟(默认 60),每次呈现令牌的请求都会重置。当会话结束——因过期或因 CloseDocument(token) ——其文档引擎被释放,内存立即被清理。
// 一次性预览的短期会话
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. 的错误图片。
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 在票据对该令牌、该浏览器以及——当用户已登录时——该用户有效时接受请求。
该设置在每个节点上都是相同的:
// 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-clientCookie —— 并且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—— 可提升内存和安全性。 - 永不记录或共享令牌;将其视为短期凭证。
此页面对您有帮助吗?