튜토리얼: React와 함께 Doconut 뷰어를 안전하게 임베드하기 – 엔드 투 엔드
문서 뷰어를 안전하게 임베드하려면 ASP.NET Core 애플리케이션에 미들웨어 코드를 복사하는 것만으로는 충분하지 않습니다. 통합 과정에서는 인증, 문서 접근, 세션 관리, 렌더링, 주석, 검색, 인쇄 및 감사 로그에 대한 명확한 경계를 정의해야 합니다.
엔터프라이즈 수준의 문서 중심 포털—예를 들어 DMS, CRM, 법률 검토 또는 엔지니어링 도면 애플리케이션—은 원본 파일을 애플리케이션 경계 뒤에 보관해야 합니다. Doconut은 PDF, Office, CAD, 이미지 문서에 대한 서버‑사이드 뷰잉 모델을 지원하며, React 프런트엔드가 사용자 인터페이스를 제공할 수 있습니다.
이 튜토리얼은 신뢰할 수 있는 아키텍처에 초점을 맞추고 있으며, SDK 버전마다 달라질 수 있는 패키지 이름, 옵션 속성, 메서드 시그니처 및 엔드포인트 경로는 의도적으로 다루지 않습니다. 정확한 등록 및 API 세부 정보를 위해 라이선스 버전에 맞는 공식 문서를 사용하십시오.
1️⃣ 단계 1 – ASP.NET Core 및 React 프로젝트 준비
코드를 작성하기 전에 개발 환경이 기본 요구 사항을 충족하는지 확인하십시오:
| 요구 사항 | 권장 버전 |
|---|---|
| .NET 런타임 | .NET 6 또는 이후 버전 |
| ASP.NET Core | 6.0+ |
| IDE | 지원되는 .NET 개발 환경 |
| 프런트엔드 (선택 사항) | 프로젝트와 호환되는 React 애플리케이션 |
- 새 ASP.NET Core Web API 프로젝트 생성
dotnet new webapi -n DocPortal
cd DocPortal
-
라이선스가 부여된 Doconut 종속성 추가 – 정확한 패키지 이름, 버전, 네이티브 종속성 및 라이선스 로드 지침은 해당 Doconut 릴리스의 공식 문서를 참조하십시오. 무관한 튜토리얼에 나온 패키지나 래퍼를 가정하지 마세요.
-
React 애플리케이션 준비 – 뷰어를 React를 통해 제공하려면 팀에서 이미 승인한 프런트‑엔드 설정을 사용하십시오. React 애플리케이션은 문서화되지 않은 서드‑파티 래퍼가 아니라 자체 인증 API에 의존하도록 유지합니다.
-
초기 상태 커밋 – 대부분의 엔터프라이즈 팀은 라이선스 또는 보안 설정을 변경할 때 서명된 커밋을 요구하는 Git 정책을 적용합니다.
이제 문서화된 Doconut 서버 통합을 위한 깔끔한 솔루션이 준비되었습니다.
2️⃣ 단계 2 – 서버 통합을 안전하게 구성
프로젝트에 적용된 정확한 Doconut 버전에 제공된 지침에 따라 뷰어를 등록하십시오. 미들웨어 순서, 서비스 등록, 라이선스 초기화 및 구성 속성 이름은 버전‑특정 세부 사항이며 검증되지 않은 예제에서 복사해서는 안 됩니다.
SDK 버전에 관계없이 ASP.NET Core 애플리케이션은 다음 제어를 강제해야 합니다:
- 문서를 열기 전에 인증 – 뷰어 세션은 절대 애플리케이션의 신원 계층을 우회해서는 안 됩니다.
- 서버에서 문서 식별자를 해석 – 브라우저가 제공하는 임의의 물리 파일 경로가 아니라 애플리케이션 수준의 문서 ID를 받아야 합니다.
- 모든 작업에 권한 부여 – 보기, 주석, 검색, 다운로드 및 인쇄는 각각 다른 권한이 필요할 수 있습니다.
- 비밀을 소스 컨트롤 외부에 보관 – 라이선스, 연결 문자열, 암호화 자료는 승인된 비밀 관리 메커니즘에 저장합니다.
- 요청 제한 적용 – 업로드, 문서 크기, 타임아웃 및 속도 제한을 뷰어 워크플로 주위에 적절히 설정합니다.
- 보안 이벤트 기록 – 문서 내용이나 민감 토큰을 로그에 남기지 않으면서 접근 결정 및 문서 작업을 기록합니다.
모든 SDK 설정은 버전별 구성으로 취급하십시오. 프로덕션에 적용하기 전에 공식 레퍼런스에서 의미를 확인하세요.
3️⃣ 단계 3 – 애플리케이션 서비스 뒤에서 문서 세션 격리
Doconut 전용 상호작용은 전용 애플리케이션 서비스 안에 격리해야 합니다. Viewer 클래스에 대한 언급은 아키텍처 수준에서 유용하지만, 생성자 시그니처, 문서 열기 메서드, 캐시 요구 사항 및 라이선스 탐지 동작은 설치된 버전의 문서에서 확인해야 합니다.
보안 서비스 경계는 다음을 수행해야 합니다:
- 인증된 사용자와 애플리케이션 수준 문서 식별자를 수신합니다.
- 요청된 작업에 대한 사용자의 권한을 확인합니다.
- 승인된 서버‑사이드 저장소에서 문서를 조회합니다.
- 문서 세션을 시작하도록 문서화된 뷰어 API에 요청합니다.
- 클라이언트에 최소한의 불투명 세션 정보만 반환합니다.
- 보존 및 캐시 정책에 따라 세션을 해제하거나 만료합니다.
브라우저는 물리적 저장 경로, 라이선스 데이터, 내부 캐시 키 또는 원본 문서에 대한 무제한 참조를 절대 받아서는 안 됩니다.
4️⃣ 단계 4 – 주석, 검색 및 제어된 인쇄 활성화
주석, 검색, OCR 및 제어된 인쇄 기능은 라이선스된 Doconut 구성에 포함되어 있고 설치된 버전에서 지원되는 경우에만 활성화하십시오. 메서드 이름, 지속 형식 또는 옵션 클래스를 추측하지 마세요.
- 주석 – 어떤 역할이 마크업을 생성, 편집, 보기 또는 삭제할 수 있는지 정의합니다. 주석 상태는 SDK 버전별 지속성 가이드와 자체 감사 요구 사항에 따라 저장합니다.
- 검색 및 OCR – OCR이 필요한 문서 유형, 추출된 텍스트 보관 위치 및 인덱스 유지 기간을 설정합니다. 검색 결과는 문서 데이터로 취급하고 적절히 권한을 부여합니다.
- 제어된 인쇄 – 페이지 제한, 워터마크 정책, 승인 규칙 및 감사 이벤트를 애플리케이션 수준에서 정의한 뒤, 이를 문서화된 인쇄 기능에 매핑합니다.
이러한 작업은 문서 세션을 담당하는 동일한 애플리케이션 서비스 뒤에 두어 컨트롤러를 얇게 유지하고 비즈니스 규칙을 테스트 가능하게 합니다.
5️⃣ 단계 5 – React 프런트엔드 연결
React 애플리케이션은 저장 경로나 내부 문서 서비스에 직접 연결하지 말고, 인증된 ASP.NET Core API를 호출해야 합니다. 비즈니스 행동을 중심으로 자체 리소스‑지향 API 계약을 정의하고, SDK‑특정 엔드포인트 이름을 공개 클라이언트 계약에 포함시키지 마세요.
전형적인 상호작용 흐름은 다음과 같습니다:
- 사용자가 애플리케이션 내에서 이미 표시된 문서를 선택합니다.
- React가 문서의 애플리케이션 ID를 사용해 뷰어 세션을 요청합니다.
- ASP.NET Core가 요청을 인증하고, 문서에 대한 권한을 확인한 뒤, 뷰어 세션을 조정합니다.
- React는 뷰어 표시를 위해 필요한 최소 정보만 받습니다.
- 주석, 검색 및 인쇄 요청은 인증된 애플리케이션 API를 통해 반환됩니다.
- 서버는 감사 이벤트를 기록하고, 적절한 시점에 세션을 만료합니다.
React UI에서는 세션 상태를 단기간 유지하고, 권한 오류를 명시적으로 처리하며, 민감한 값을 영구적인 브라우저 저장소에 두지 않도록 하세요. 또한 내부 경로나 예외 세부 정보를 노출하지 않는 로딩 및 오류 상태를 제공해야 합니다.
이러한 분리로 렌더링 및 문서 제어는 서버에서 수행되고, React는 프레젠테이션 및 인터랙션에만 집중할 수 있습니다.
결론
Doconut 통합을 안전한 ASP.NET Core 애플리케이션 서비스 뒤에 배치함으로써, React 인터페이스를 문서화되지 않은 SDK 세부 사항에 결합하지 않고도 PDF, Office, CAD 및 이미지 워크플로를 위한 문서 포털을 구축할 수 있습니다. 인증, 권한 부여, 세션 수명 주기, 검색, 주석, 인쇄 및 감사 정책은 모두 애플리케이션 설계의 명시적인 부분으로 남게 됩니다.
.NET 프로젝트에서 Doconut을 평가할 준비가 되셨나요? 공식 패키지, 라이선스 및 API 문서를 사용하고, 위에서 제시한 아키텍처 및 보안 체크리스트를 구현에 적용하십시오.