세션 및 보안

문서 세션 및 접근 제어

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

문서 세션이 보유하는 내용

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

  • 로드된 포맷 뷰어 (구문 분석된 문서를 보유하는 문서 엔진 인스턴스),
  • 페이지별 상태 — 회전, 뒤집기 및 위젯에서 사용자가 적용하는 주석 데이터,
  • 선택적 검색 인덱스, 첫 검색 시 지연 로드되며(또는 웹 팜 시나리오에서 사전 구축된 .srh 파일에서 로드됨),
  • 세션 워터마크 (DocOptions.Watermark에서 가져온).

수명

세션은 슬라이딩 윈도우 방식으로 만료됩니다: DocOptions.TimeOut 분(기본 60분)이며 토큰을 제시하는 모든 요청마다 재설정됩니다. 세션이 만료되거나 CloseDocument(token)에 의해 퇴출될 때, 퇴출 콜백이 문서 엔진을 해제하고 관련 메모리를 즉시 해제합니다.

csharp
// A short-lived session for a one-shot preview
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()는 접근 미들웨어를 건너뛰며 핵심 마커 검사도 비활성화됩니다.

폐기

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

프로덕션 체크리스트

  • UnsafeMode = false(기본값) 유지 — 이 전역 스위치가 토큰을 세션에 바인딩합니다.
  • Doconut 미들웨어 분기 전에 AddSession()를 등록하고 app.UseSession()를 호출하세요.
  • 세션 쿠키 정책이 위젯 요청이 쿠키를 전송하도록 허용하는지 확인하세요(SameSite, HTTPS).
  • 사용자가 문서를 떠날 때 CloseDocument를 사용하세요 — 메모리와 보안 모두에 이점이 있습니다.
  • 토큰을 절대 로그하거나 공유하지 마세요; 짧은 수명의 자격 증명으로 취급하십시오.

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