Externí systémy PRO ELEKTRONICKÉ podepisování dokumentů

V průbehu let 2018 - 2019 bylo implementováno propojení na externí systém umožňující elektronické podepisování PDF dokumentů. Externí systém má být co možná nejjednodušší a určený pouze k účelu (hromadného) elektronického podepisování.

V rámci CRP projektu byla oslovena firma Marbes Consulting, která na zákazku implementovala tento modul. IS/STAG je připraven případně podporovat i jiné takové moduly, aktuálně ale existuje pouze jedna implementace, která je popsána na této stránce.

Tento modul je těsně spjat s modulem pro tvorbu hromadné korespondence, který je popsán na vedlejší stránce.

Stručný návod pro běžné uživatele je k dispozici na stránce Zákazníci / Elektronické podepisování.

Úvod

Externí aplikace je navržena tak, aby v budoucnu sloužila zákazníkovi jako centrální podepisovací aplikace. Tedy aby nebyla těsně navázána jen na IS/STAG, ale aby byla napojitelná na libovolný systém a libovolné škole.

Z toho plynou některé podmínky, které jsme po dodavateli při vývoji aplikace chtěli:

• Aplikace nebude řešit vlastními prostředky přihlašování a ověřování uživatelů (např. Shibboleth a podobně). Přihlášení zprostředuje klientský systém dané aplikace (např. IS/STAG) přes WS API aplikace, viz dále.
• Aplikace nebude napojená na evidenci uživatelů (např. LDAP, IdM, ...) - bude si pro své účely udržovat svoji databázi, která ale bude dynamicky vznikat tak, jak budou přicházet požadavky z klientských systémů. S uživateli bude aplikace "komunikovat" přes emaily (v rámci obecnosti)
  • Poznámka: Nicméně aplikace obsahuje REST API na tvorbu/úpravu uživatelských kont - to mohou zákazníci použít na vlastní způsob řízení identit
  • Aplikace je již na několika školách napojena např. na Shibboleth (přihlašování uživatelů) či na IdM (správa uživ. kont v aplikaci)

Prezentace

Následující prezentace obsahují popis fungování celého procesu hromadné tvorby dokumentů a jejich podepisování:

• Prezentace ze semináře CRP 2019 (listopad 2019) - prezentace s nahraným komentářem, zdrojová prezentace.

Obsah

1. Obecný popis tohoto propojení, možnosti
2. Způsob a podmínky nasazení
3. Konfigurace IS/STAG
4. Instalace a konfigurace externí aplikace
5. Sledování chyb v propojení s externí aplikací

Obecný popis tohoto propojení, možnosti

Propojení IS/STAG a aplikací pro elektronické podepisování je realizováno v následujícím rozsahu:

• IS/STAG slouží jako vstupní bod do externí aplikace
  • V portálu na záložce IS/STAG / Reporty je záložka "Elektronické podepisování".
  • Jak je popsáno v úvodu, IS/STAG zprostředkovává přihlášení "svých" uživatelů do aplikace. Chce-li tedy uživatel do aplikace, IS/STAG od aplikace (na pozadí přes WS API) získá pro dané uživatelské jméno přihlašovací URL a na to uživatele přesměruje.
    • V okamžiku, kdy uživatel vstupuje poprvé do podepisovací aplikace, nakonfiguruje IS/STAG základní nastavení - připraví údaje o uživ. kontu a vyrobí výchozí "podpisové konfigurace", viz. dále kapitola o konfiguraci
• Zasílání dokumentů k podpisu
  • Z IS/STAG lze zaslat dokumenty k podpisu prostřednictvím formulářů hromadné korespondence (ve Windows klientovi IS/STAG, formuláře HK0010, HK0020 a HK0030), kde uživatel zaškrtne volbu "Elektronicky podepsat". Dokumenty nejprve projdou modulem hromadné korespondence a poté, co uživatel dávku v tomto modulu dokončí (kliknutím na tlačítko "Dokončit"), dojde k přesunu dokumentů do modulu k podepsání.
  • Z IS/STAG lze zasílat dokumenty k podpisu i z nového reportovacího modulu v portálu, funkcionalita je k dispozici zhruba od srpna 2021 ve vývojové verzi aplikace.
  • Zároveň lze dokumenty vkládat i ručně přímo přes GUI aplikace firmy Marbes
• Práce v externí aplikaci
  
  • Externí aplikace se zobrazí v novém okně či záložce prohlížeče
  • Umožňuje náhled na dávky dokumentů k podepsání a další činnosti - viz popis k aplikaci
• Práce s výslednými PDF dokumenty
  • Výsledné dokumenty lze stáhnout ručně z GUI aplikace
  • V případě, že jste ve formuláři v IS/STAG zaškrtli, že chcete nechat dokumenty přenést do spisové služby, tak modul po úspěšném podepsání dokáže PDFka zaslat zpět do IS/STAG (a ten je obratem odešle do spisovky jako přílohu k příslušným písemnostem)
  • Výsledné PDF dokumenty zůstávají k dispozici v externí aplikaci (dokud dávky neuzavřete nebo nesmažete)
  • Dávku lze označit za hotovou - tím dojde k jejímu uzavření. V případě, že chcete takto vygenerované dokumenty nechat poslat rovnou do spisové služby, dojde v tuto chvíli k jejich odeslání do IS/STAG, který je umí následně předat spisovce.

Zjednodušení přístupu k podepisovací aplikaci

Tip: Pokud si na své škole chcete zavést nějakou doménovou adresu určenou k elektronickému podepisování, třeba "https://podpis.SKOLA.cz" a chtěli byste, aby se přes tuto doménu uživatel mohl dostat přímo do portálu IS/STAG do sekce IS/STAG / Reporty / Elektronické podepisování ... a tudíž by ho to ihned přesměrovalo do externí podepisovací aplikace (onen krok přes portál IS/STAG je nutný kvůli přenosu / případně založení uživatelské identity), vytvořte si onu doménu a nechte její server přesměrovávat klienty na následující adresu portálu IS/STAG: https://portal.SKOLA.cz/StagPortletsJSR168/CleanUrl/reports/sign . Takto to má implementováno například JČU.

Způsob a podmínky nasazení

Vývoj vznikl v rámci CRP a tudíž je k dispozici všem zúčastněným školám stejně jako modul hromadné korespondence. V případě zájmu postupujte podle návodu uvedeného na stránce o modulu externí hromadné korespondence.

Konfigurace IS/STAG

Tato kapitola popisuje kroky nutné pro konfiguraci IS/STAG tak, aby byl napojen na systém webové hromadné korespondence.

Spammer - automatické zprávy - pro administrátory IS/STAG

Silně doporučujeme administrátorům, aby si v aplikaci na portálu IS/STAG "Automatické zprávy (spammer)" (sekce IS/STAG) zapnuli odběr zpráv "Přenos dat s jinými systémy - chybová hlášení". Budou jim pak každý den chodit seznamy chyb, které se staly při komunikaci s jinými systémy během uplynulého dne/víkendu. Případné detaily zaslaných informací si pak mohou dohledat v aplikaci na portálu, viz. kapitola o monitoringu propojení s externími systémy.

Parametry IS/STAG

• HK_WEB = "AP" (na úrovni REK). Hodnota "P" znamená právě i ono "Podepisování". Tento parametr nastavit až jako POSLEDNÍ věc konfigurace, tímto parametrem se propojení zapíná!
• HK_MARBES_URL = "https://stag-doc.SKOLA.cz/uni" (na úrovni REK) - Nastavte URL adresu, na které je aplikace od firmy Marbes nasazena. Typicky to bude adresa "https://stag-doc.SKOLA.cz/uni".
• HK_PODPIS_PECET = A / N - v další kapitole je popsána nutná konfigurace externí aplikace, jendou z věcí je i to, zda aplikace je nakonfigurovaná pro použití elektronické pečeti, tj. zda ji vůbec podporuje. IS/STAG potřebuje vědět, zda má o pečeť žádat - nastavení tohoto parametru říká, zda externí aplikace pečetění podporuje.
• HK_PODPIS_CAS_RAZITKO = A / N - ten samý princip jako u pečeti, týká se vkládání časového razítka
• HK_PODPIS_CAS_RAZITKO_PECETI = A / N - ten samý princip jako u pečeti, týká se vkládání časového razítka na pečeť.

Poznámka: škrtnuté parametry v průběhu srpna 2021 nahradily následující číselníky:

Číselníky IS/STAG

Pozor - tato kapitola již byla aktualizována a popisuje stav, který je platný od ledna 2022 pro novou verzi Marbes aplikace vydané právě na začátku roku 2022!

Následující číselníky IS/STAG se týkají elektronického podepisování a defakto říkají studijní agendě, jaké možnosti má škola zprovozněny na straně podepisovací aplikace a jaké možnosti má tudíž nabízet uživatelům v GUI IS/STAG. Podporované možnosti prosím řiďte ve formuláři "Seznam domén" tak, že budete nastavovat PLATNOST těchto záznamů. Vždy nechte prosím platný záznam s klíčem "Z" (žádný / žádná - prostě možnost nezvolit nic). Nezapomeňte, že musí být platná alespoň jedna možnost (kromě Z) u podpisu/pečeti, jinak IS/STAG bere, že podepisování není v systému nakonfigurováno a dokumenty k podpisu nezasílá!

• SPIS_ELEKTRONICKY_PODPIS - číselník říkající, jaké typy el. podpisů externí aplikace podporuje.
• SPIS_ELEKTRONICKA_PECET - číselník říkající, jaké typy el. pečetí externí aplikace podporuje.
• SPIS_ELEKTRONICKE_RAZITKO - číselník říkající, jaké typy razítek externí aplikace podporuje.

V těchto číselnících je dále potřeba nastavit následující atributy (kromě položek s klíčem Z, tam to nemá smysl):

• Pomocná hodnota 2: V ní musí být uvedena jedna ze tří následujících hodnot: "NONE", "GUARANTEED", "QUALIFIED". Tyto hodnoty jsou dále předány přes rozhraní do aplikace Marbes a určují, jaký typ příslušného podepisovacího prostředku má být použit. Úzce to tedy souvisí s konfigurací externí aplikace.
• Pomocná hodnota 3: Podporována u číselníků _PODPIS a _PECET. Slouží k možnosti napevno "přebít" vybrané časové razítko v případě nutnosti. Pokud je v této pomocné hodnotě 3 uvedena nějaká hodnota, která odpovídá existujícími a platnému klíči v doméně SPIS_ELEKTRONICKE_RAZITKO, pak se v případě použití daného podpisu napevno použije časové razítko podpisu uvedené v této pomocné hodnotě 3. To samé v případě použití daného typu pečeti se napevno použije časové razítko pečeti uvedené v této pomocné hodnotě.
  Jinými slovy: Potřebujete-li z nějakého důvodu u nějakého typu podpisu (či pečeti) napevno přebít použité časové razítko (tj. změnit to, co si uživatel vybral v GUI), nastavte pomocnou hodnotu 3.
• Pořadí - prosím nezapoměňte mít nastavené pořadí, podle pořadí se pak nabízí možnosti uživatelům ve formulářích. Doporučujeme nechat položky "Z" (žádná / žádné) s pořadím 1, aby se nabízely jako první

Konfigurace modulu webových služeb IS/STAG

Stejné jako viz modul externí hromadné korespondence plus následující. V souboru ws-config.properties lze konfigurovat:

# Je-li Marbes aplikace napojena na CESNET HSM modul, musi zde byt uveden format uzivatelskeho ID, ktere aplikace
# do CESNET HSM posila. Toto ID vychazi z uzivatelskeho jmena, ktere je dane parametrem "hk_marbes_hsm_id_username_type"
# a lze k nemu pridat nejaky prefix / postfix. Prikladem mozneho nastaveni je napriklad "{0}@jcu.cz" - namisto {0} aplikace doplni username

hk_marbes_hsm_id_username_type = stag | orion | orion-identifikator | ucitele-identifikator | ucitele-idc
hk_marbes_hsm_id_format = {0}@SKOLA.CZ


# Emailova adresa, ktera na skole funguje jako nejaka "prazdna zumpa", kam lze posilat maily a nic se nestane.
# Marbes aplikace totiz email vyzaduje a my v nekterych pripadech ale nechceme, aby nekomu neco posilala (treba
# pokud dochazi k peceteni dokumentu primo pro studenta, napr. potvrzeni o studiu - prace v Marbes aplikaci pak probiha pod fiktivnim uzviatelem)
hk_marbes_null_email_address = devnull@skola.cz

# Default: false - zda vubec vytvaret podpisove profily uzivatelu. Na skolach, ktere maji napojeno na IDM tohle nechat false
#hk_marbes_alter_sign_user_profiles = false

# Default: true. Rika, zda upravovat uzivatelsky profil uzivatele pokazde, kdyz do externi podepisovaci aplikace leze.
#hk_marbes_always_alter_sign_user_profile = true

# Jak predavat do Marbes aplikace "displayName". Default: PRIJMENI_JMENO_TITULY.
# Moznosti: PRIJMENI_JMENO_TITULY_LOGIN, PRIJMENI_JMENO_TITULY, PRIJMENI_JMENO, JMENO_PRIJMENI_TITULY, JMENO_PRIJMENI
#hk_marbes_display_name_format =

Možnosti položky hk_marbes_hsm_id_username_type  popsané detailně, tj. kde se příslušné hodnoty pak berou:

• stag - je to uživatelské jméno toho onoho konkrétního uživatele přímo v databázi IS/STAG. Bere se tedy z tabulky/položky ID_TABLE2.ID_NAME
• orion - je to "orion" uživatelské jméno, tedy to "externí", kterým se na většině velkých škol hlásí např. uživatel do portálu. Typicky je to to username, které píše do Shibbolethu a podobně. Bere se z tabulky/položky ORION_UCITELE.USERNAME
• orion-identifikator - Bere se z tabulky/položky ORION_UCITELE.IDENTIFIKATOR
• ucitele-identifikator - Bere se z tabulky/položky UCITELE.IDENTIFIKATOR
• ucitele-idc - Bere se z tabulky/položky ORION_UCITELE.IDC

Instalace a konfigUrace externí aplikace

POZOR NOVINKA OD ZAČÁTKU ROKU 2022 - O konfiguraci aplikace QSIGN se již zcela a plně starají školy ve spolupráci s dodavatelem - firmou Marbes Consulting - na základě servisní smlouvy. My zde ponecháváme STAROU dokumentaci jen pro úplnost, ale je již zcela bez záruky!

Stejné jako viz modul externí hromadné korespondence plus následující věci:

Konfigurace podepisování

Oficiální dokumentace k aplikace od firmy Marbes bohužel není k dispozici na nějakém stabilním trvalém URL - nicméně po přihlášení do běžící aplikace je v pravém horním rohu "otazníček". Na ten klikněte a dostanete se na web dodavatele do nápovědy k aplikaci. Detailní informace o konfiguraci (ty, které budete v této kapitole potřebovat) tam najdete v sekci "Administrátorská příručka / Instalace a konfigurace serveru".

Podstatné části, které si bude muset nakonfigurovat vždy každý zákazník sám, jsou uvedené na serveru, kde aplikace běží, v souboru /opt/tomcat/PORTAL-data/read-write/marbes/uni/WEB-INF/application.properties. Jde o věci týkající se:

Pečeti

# konfigurace pečeti, předpokládáme PKCS #12
podepisovani.certificate.path=<absolutní cesta k pečeti, např. *.p12, *.pfx>
podepisovani.certificate.password=<heslo k pečeti>

Časových razítek

# konfigurace TSA serveru (časové razítko)
podepisovani.tsa.url=<URL adresa serveru časového razítka>
podepisovani.tsa.account=<login přihlášení k časovému razítku>
podepisovani.tsa.password=<heslo k přihlášení k časovému razítku>
 
# přihlášení certifikátem k TSA
podepisovani.tsa.certificate.path= <absolutní cesta k certifikátu pro přihlášení k časovému razítku>
podepisovani.tsa.certificate.password= <heslo pro přihlášení k certifikátu>

# Napojeni na HSM
podepisovani.remsig.api.url=
podepisovani.remsig.login=
podepisovani.remsig.password=
 
# zapnutí HSM modulu
podepisovani.hsm.enabled=false

qsign.admin.mail=ADMIN@SKOLA.cz
qsign.admin.password=NEJAKE_SLOZITE_HESLO

Podpora na klientských stanicích

Sledování chyb v propojení s EXTERNím systémem hromadné korespondence

Přečtěte si prosím nejprve informace, které se tohoto tématu týkají obecně - na stránce o propojení s externími systémy. Případné chybové hlášky by měly být k dispozici prostřednictvím aplikace pro správu externích systémů jak je uvedeno za uvedeným odkazem. V každém případě - při problémech s propojením je třeba prostudovat i log soubory modulu webových sluzeb, protože ne všechny detaily a informace se přenášejí zpět do databáze IS/STAG.