세션 및 보안

문서 세션 및 접근 제어

Doconut 토큰은 강력합니다: 이를 제시하는 사람은 열기 세션에 바인딩되지 않았다면 문서의 모든 페이지를 요청할 수 있습니다. 이 페이지에서는 세션이 무엇을 보유하고 있는지, 얼마나 오래 지속되는지, 그리고 기본적으로 UseDoconut()가 활성화하는 검증에 대해 설명합니다.

문서 세션이 보유하는 내용

각 성공적인 OpenDocumentAsync는 IMemoryCache에 하나의 세션을 생성합니다:

  • 로드된 포맷 뷰어 (구문 분석된 문서를 보유하는 문서 엔진 인스턴스),
  • 페이지별 상태 — 회전, 뒤집기 및 사용자가 위젯에서 적용하는 주석 데이터,
  • 선택적 검색 인덱스, 첫 번째 검색 시 지연 생성(또는 페이지가 공유 스토리지에서 제공될 때 미리 구축된 .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(기본값)를 사용하면, OpenDocumentAsync는 새 토큰을 열었던 HTTP 요청의 ASP.NET 세션에 바인딩하며, 해당 세션에 secure-{token} 마커를 기록합니다. 그 후 Doconut 미들웨어는 다른 브라우저 세션에 페이지 제공을 거부합니다:

  • 도난당한 토큰을 제시하는 다른 브라우저/세션 → 오류 이미지 You Are Not Authorized To View This Page.
  • 세션 미들웨어가 등록되지 않음 → HTTP 500 Session middleware not configured. Call UseSession() before UseDoconut().

이것이 Quick Start가 Doconut 분기 전에 AddSession() + app.UseSession()를 요구하는 이유입니다. 두 가지 실용적인 결과가 있습니다:

  • 클라이언트는 페이지 요청 시 ASP.NET 세션 쿠키를 전송해야 합니다. 쿠키를 제거하는 크로스 오리진 설정(또는 쿠키 저장소가 없는 API 클라이언트)은 검증에 실패합니다 — 이는 버그가 아니라 기능이 정상 작동하는 것입니다.
  • options.UnsafeMode = true는 바인딩을 완전히 비활성화합니다. 이는 제어된 시나리오(예: 서버 간 렌더링)를 위해 존재합니다; 프로덕션에서는 false 상태로 두세요.

토큰 바인딩은 이 전역 UnsafeMode 스위치에 의해만 제어됩니다 — 기본적으로 켜져 있습니다(UnsafeMode = false)이며 모든 세션에 적용됩니다. 문서별 옵트아웃은 없으며, UnsafeMode = true를 설정하면 바인딩이 전역적으로 비활성화됩니다.

접근 권한 및 인증된 사용자

UnsafeMode가 false이면, UseDoconut()는 페이지 미들웨어 앞에 DocumentAccessMiddleware를 자동으로 삽입합니다. 두 번 등록하지 마세요. 요청에 토큰이 포함되면, 문서가 열릴 때 기록된 접근 권한을 조회하고 다음 조건이 모두 충족될 때만 인증합니다:

  1. 토큰에 대한 권한이 존재함,
  2. 권한이 만료되지 않음(권한 수명 = 문서의 TimeOut),
  3. 요청하는 ASP.NET 세션 ID가 문서를 연 세션 ID와 일치함,
  4. 열었던 사용자가 인증된 경우, 요청하는 사용자의 NameIdentifier 클레임도 일치함.

실패 시 403을 반환합니다 — 페이지/썸네일 요청에서는 PNG 오류 이미지로, 그 외에는 일반 텍스트로 반환됩니다. 메시지와 토큰 쿼리 키는 DocumentSecurityOptions에서 가져오며(TokenQueryKey, 기본값 "token"; UnauthorizedMessage, 기본값 "You Are Not Authorized To View This Page."). 앱을 빌드하기 전에 ASP.NET Core DI를 통해 해당 옵션을 구성하세요. 세션 상태를 사용할 수 없으면 미들웨어는 HTTP 500 오류와 함께 차단됩니다: ASP.NET Session is required for Doconut document security.

csharp
builder.Services.Configure<Doconut.Security.DocumentSecurityOptions>(options =>
{
    options.TokenQueryKey = "token";
    options.UnauthorizedMessage = "You Are Not Authorized To View This Page.";
});

핵심 페이지 미들웨어는 문서를 제공하기 전에 secure-{token} 세션 마커를 검증합니다. UnsafeMode = true를 사용하면, UseDoconut()가 접근 미들웨어를 건너뛰고 핵심 마커 검증도 비활성화됩니다.

여러 노드에 걸친 보안

세션에 바인딩된 토큰은 페이지를 제공하는 노드가 문서를 연 요청도 함께 본 것으로 가정합니다. 여러 노드가 공유 스토리지에서 동일한 문서를 제공할 경우 이 가정이 깨집니다: 페이지 요청이 문서를 연 적이 없는 노드에 도달하면, 세션별 검증이 이를 거부합니다.

해답은 문서를 보호하지 않은 채 두는 것이 아닙니다. AddDoconutDistributedDocumentSecurity(...)를 통해 서명된 접근 티켓을 사용하면, 세션 검증을 각 노드가 독립적으로 검증할 수 있는 자격 증명으로 대체합니다. 전체 구성은 분산 배포에서 확인하세요.

폐기

CloseDocument(token)는 메모리를 해제할 뿐만 아니라 secure-{token} 마커를 제거하고 접근 권한을 폐기하여, 폐기된 토큰은 두 보안 계층에서 즉시 무효화됩니다.

프로덕션 체크리스트

  • 단일 노드에서 UnsafeMode = false(기본값)를 유지하세요 — 이 전역 스위치가 토큰을 세션에 바인딩합니다.
  • AddDistributedMemoryCache()(MVC 및 Razor Pages 앱에 이미 포함됨)와 AddSession()를 등록하고, Doconut 미들웨어 분기 전에 app.UseSession()를 호출하세요.
  • 세션 쿠키 정책이 위젯의 요청이 쿠키를 전송하도록 설정되어 있는지 확인하세요(SameSite, HTTPS).
  • 사용자가 문서를 떠날 때 CloseDocument를 사용하세요 — 메모리와 보안 모두에 이점이 있습니다.
  • 토큰을 절대 로그하거나 공유하지 마세요; 짧은 수명의 자격 증명으로 취급하세요.
  • 공유 스토리지에서 제공하고 있나요? 보호되지 않은 문서를 받아들이는 대신 서명된 접근 티켓으로 전환하세요.

이 페이지가 도움이 되었나요?