Samouczek: Bezpieczne osadzenie przeglądarki Doconut w React – od początku do końca
Bezpieczne osadzenie przeglądarki dokumentów wymaga więcej niż skopiowanie fragmentu middleware do aplikacji ASP.NET Core. Integracja musi określić wyraźne granice dla uwierzytelniania, dostępu do dokumentów, zarządzania sesjami, renderowania, adnotacji, wyszukiwania, drukowania i rejestrowania zdarzeń audytu.
Przedsiębiorstwa budujące portale skoncentrowane na dokumentach — takie jak DMS, CRM, przegląd prawny czy aplikacje do rysunków inżynierskich — muszą również przechowywać oryginalne pliki poza granicą aplikacji. Doconut obsługuje model przeglądania po stronie serwera dla dokumentów PDF, Office, CAD i obrazów, podczas gdy interfejs React może zapewnić warstwę prezentacji.
Ten samouczek koncentruje się na niezawodnej architekturze i celowo unika nazw pakietów, właściwości opcji, sygnatur metod oraz ścieżek endpointów, które mogą różnić się w zależności od wersji SDK. Korzystaj z oficjalnej dokumentacji odpowiadającej Twojej licencjonowanej wersji, aby uzyskać dokładne informacje o rejestracji i szczegółach API.
1️⃣ Krok 1 – Przygotowanie projektów ASP.NET Core i React
Zanim napiszesz jakikolwiek kod, upewnij się, że Twoje środowisko programistyczne spełnia podstawowe wymagania:
| Wymaganie | Zalecana wersja |
|---|---|
| .NET runtime | .NET 6 lub nowszy |
| ASP.NET Core | 6.0+ |
| IDE | Wspierane środowisko programistyczne .NET |
| Front‑end (opcjonalnie) | Aplikacja React kompatybilna z Twoim projektem |
- Utwórz nowy projekt ASP.NET Core Web API
dotnet new webapi -n DocPortal
cd DocPortal
-
Dodaj licencjonowane zależności Doconut – Uzyskaj dokładne nazwy pakietów, wersje, zależności natywne oraz instrukcje ładowania licencji z oficjalnej dokumentacji dla Twojej wersji Doconut. Nie zakładaj, że pakiet lub wrapper przedstawiony w niepowiązanym samouczku ma zastosowanie do Twojej wersji.
-
Przygotuj aplikację React – Jeśli przeglądarka ma być prezentowana przez React, użyj konfiguracji front‑endu już zatwierdzonej przez Twój zespół. Utrzymuj aplikację React zależną od własnego uwierzytelnionego API, a nie od nieudokumentowanych wrapperów firm trzecich.
-
Zatwierdź początkowy stan – Większość zespołów korporacyjnych wymusza politykę Git, która wymaga podpisanego commita przy każdej zmianie dotyczącej licencjonowania lub ustawień bezpieczeństwa.
Teraz masz czyste rozwiązanie gotowe do integracji serwera Doconut zgodnie z dokumentacją.
2️⃣ Krok 2 – Bezpieczna konfiguracja integracji serwera
Zarejestruj przeglądarkę, korzystając z instrukcji dostarczonych dla dokładnej wersji Doconut w Twoim projekcie. Kolejność middleware, rejestracje usług, inicjalizacja licencji oraz nazwy właściwości konfiguracyjnych są szczegółami specyficznymi dla wersji i nie powinny być kopiowane z niezweryfikowanych przykładów.
Niezależnie od wersji SDK, otaczająca aplikacja ASP.NET Core powinna wymuszać następujące kontrole:
- Uwierzytelnij przed otwarciem dokumentu – Sesja przeglądarki nigdy nie może ominąć warstwy tożsamości aplikacji.
- Rozwiązuj identyfikatory dokumentów po stronie serwera – Akceptuj identyfikator dokumentu na poziomie aplikacji, a nie dowolną fizyczną ścieżkę pliku podaną przez przeglądarkę.
- Autoryzuj każde działanie – Przeglądanie, adnotacje, wyszukiwanie, pobieranie i drukowanie mogą wymagać różnych uprawnień.
- Przechowuj tajemnice poza kontrolą wersji – Przechowuj licencje, ciągi połączeń i materiały szyfrujące w zatwierdzonym mechanizmie zarządzania sekretami.
- Stosuj limity żądań – Ustaw odpowiednie limity dla przesyłania, rozmiaru dokumentu, czasu oczekiwania i szybkości w ramach przepływu pracy przeglądarki.
- Rejestruj zdarzenia bezpieczeństwa – Loguj decyzje o dostępie i akcje na dokumentach, nie zapisując treści dokumentów ani wrażliwych tokenów w logach.
Traktuj wszystkie ustawienia SDK jako wersjonowaną konfigurację. Zweryfikuj ich znaczenie w oficjalnej dokumentacji przed włączeniem ich w środowisku produkcyjnym.
3️⃣ Krok 3 – Izolacja sesji dokumentów za pomocą usługi aplikacji
Umieść interakcje specyficzne dla Doconut w dedykowanej usłudze aplikacji. Odwołania do klasy Viewer są przydatne na poziomie architektonicznym, ale sygnatury konstruktorów, metody otwierania dokumentów, wymagania dotyczące pamięci podręcznej i zachowanie wykrywania licencji muszą pochodzić z dokumentacji Twojej zainstalowanej wersji.
Bezpieczna granica usługi powinna:
- Otrzymać uwierzytelnionego użytkownika oraz identyfikator dokumentu na poziomie aplikacji.
- Sprawdzić uprawnienia użytkownika do żądanej akcji.
- Rozwiązać dokument z zatwierdzonego magazynu po stronie serwera.
- Poprosić udokumentowane API przeglądarki o utworzenie sesji dokumentu.
- Zwrócić jedynie minimalne, nieprzejrzyste informacje o sesji wymagane przez klienta.
- Zwalnić lub wygaszyć sesje zgodnie z polityką przechowywania i pamięci podręcznej.
Przeglądarka nigdy nie powinna otrzymywać fizycznej ścieżki przechowywania, danych licencji, wewnętrznego klucza pamięci podręcznej ani nieograniczonego odwołania do oryginalnego dokumentu.
4️⃣ Krok 4 – Włączenie adnotacji, wyszukiwania i kontrolowanego drukowania
Adnotacje, wyszukiwanie, OCR i kontrolowane drukowanie powinny być włączane tylko wtedy, gdy są uwzględnione w licencjonowanej konfiguracji Doconut i obsługiwane przez zainstalowaną wersję. Unikaj zakładania nazw metod, formatów trwałości czy klas opcji.
- Adnotacje – Zdecyduj, które role mogą tworzyć, edytować, wyświetlać lub usuwać oznaczenia. Przechowuj stan adnotacji zgodnie z wytycznymi dotyczącymi trwałości dla Twojej wersji SDK oraz własnymi wymaganiami audytowymi.
- Wyszukiwanie i OCR – Określ, które typy dokumentów wymagają OCR, gdzie przechowywany jest wyodrębniony tekst i jak długo indeksy pozostają dostępne. Traktuj wyniki wyszukiwania jako dane dokumentu i autoryzuj je odpowiednio.
- Kontrolowane drukowanie – Zdefiniuj limity stron, politykę znaków wodnych, zasady zatwierdzania i zdarzenia audytu na poziomie aplikacji, a następnie dopasuj te wymagania do udokumentowanych możliwości drukowania.
Umieść te operacje za tą samą usługą aplikacji używaną do sesji dokumentów, aby kontrolery pozostały lekkie, a reguły biznesowe testowalne.
5️⃣ Krok 5 – Połączenie front‑endu React
Aplikacja React powinna wywoływać uwierzytelnione API ASP.NET Core, zamiast akceptować ścieżki przechowywania lub łączyć się bezpośrednio z wewnętrznymi usługami dokumentów. Zdefiniuj własny kontrakt API oparty na zasobach wokół działań biznesowych i unikaj publikowania nazw endpointów specyficznych dla SDK jako części publicznego kontraktu klienta.
Typowa sekwencja interakcji wygląda następująco:
- Użytkownik wybiera dokument już widoczny w aplikacji.
- React żąda sesji przeglądania, używając identyfikatora dokumentu w aplikacji.
- ASP.NET Core uwierzytelnia żądanie, autoryzuje dokument i koordynuje sesję przeglądarki.
- React otrzymuje jedynie informacje niezbędne do wyświetlenia przeglądarki.
- Żądania adnotacji, wyszukiwania i drukowania są zwracane przez uwierzytelnione API aplikacji.
- Serwer rejestruje zdarzenia audytu i wygasa sesję w odpowiednim momencie.
W interfejsie React utrzymuj stan sesji krótkotrwały, obsługuj niepowodzenia autoryzacji w sposób explicite, unikaj umieszczania wrażliwych wartości w trwałym magazynie przeglądarki oraz zapewnij stany ładowania i błędów, które nie ujawniają wewnętrznych ścieżek ani szczegółów wyjątków.
To rozdzielenie utrzymuje renderowanie i kontrolę dokumentów po stronie serwera, podczas gdy React pozostaje odpowiedzialny za prezentację i interakcję.
Podsumowanie
Umieszczając integrację Doconut za bezpieczną usługą aplikacji ASP.NET Core, możesz zbudować portal dokumentów dla przepływów PDF, Office, CAD i obrazów bez łączenia interfejsu React z nieudokumentowanymi szczegółami SDK. Uwierzytelnianie, autoryzacja, cykl życia sesji, wyszukiwanie, adnotacje, drukowanie i polityka audytu pozostają wyraźnymi elementami projektu aplikacji.
Gotowy, aby ocenić Doconut w swoim projekcie .NET? Użyj oficjalnego pakietu, licencjonowania i dokumentacji API dla wybranej wersji, a następnie zastosuj powyższą architekturę i listę kontrolną bezpieczeństwa w swojej implementacji.