세션 및 보안

문서 세션 및 접근 제어

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는 새 토큰을 해당 요청의 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 스위치에만 의해 제어됩니다 — 기본값은 false이며 모든 세션에 적용됩니다. 문서별로 해제할 방법은 없으며, UnsafeMode = true 로 설정하면 전역적으로 바인딩이 비활성화됩니다.

접근 권한 및 인증된 사용자

UnsafeMode가 false인 경우, UseDoconut()은 DocumentAccessMiddleware를 페이지 미들웨어 앞에 자동으로 삽입합니다. 두 번 등록하지 않도록 주의하십시오. 요청에 토큰이 포함되면, 문서를 열 때 기록된 접근 권한 부여를 조회하고 다음 조건이 모두 충족될 때만 허용합니다:

  1. 토큰에 대한 권한 부여가 존재함,
  2. 권한이 만료되지 않음(권한 수명 = 문서의 TimeOut),
  3. 요청한 ASP.NET 세션 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(기본값)를 유지하십시오 — 이 전역 스위치가 토큰을 세션에 바인딩합니다.
  • AddSession()을 등록하고 Doconut 미들웨어 브랜치 전에 app.UseSession()을 호출하십시오.
  • 세션 쿠키 정책이 위젯의 요청에 쿠키를 포함하도록 설정하십시오(SameSite, HTTPS 등).
  • 사용자가 문서를 떠날 때 CloseDocument를 호출하여 메모리와 보안을 모두 해제하십시오.
  • 토큰을 로그에 남기거나 공유하지 말고, 단기간 자격 증명으로 취급하십시오.

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