Nápověda
předešlá kapitolana rozcestníknásledující kapitola
Externí aplikace
Nejprve si uveďme několik pojmů:
Certifikát spisové služby – při komunikaci aplikace spisové služby s jednou (obvykle svou) schránkou se využívá zabezpečený protokol HTTPS. Klient – spisová služba – se při navazování SSL spojení prokáže svým certifikátem. Přihlašovací server ISDS ověřuje platnost klientského certifikátu a identifikuje pomocí něho spisovou službu. Nepoužívá se přihlašovací jméno.
Certifikát pro hostovanou spisovou službu – platí informace z předchozího odstavce, pouze s rozdílem, že jedna aplikace obsluhuje více datových schránek a správci těchto schránek musí jednotlivě přístup povolit
Certifikát pro Přístupové rozhraní – platí technická informace o přihlášení, s rozdílem, že v tomto případě aplikace obsluhuje cizí schránky pod konkrétním uživatelským účtem osoby, která k tomu svolila.
Systém ISDS akceptuje pro přihlašování komerční certifikáty vydané těmito akreditovanými certifikačními autoritami:
- PostSignum - http://postsignum.cz/
- ICA - http://www.ica.cz
- eIdentity - http://www.eidentity.cz/
- Národní CA - https://www.narodni-ca.cz/
Protože budete k registraci potřebovat tzv. PEM (textový) formát, informujte se u své autority na možnost stažení v tomto formátu. Vždy se jedná o certifikáty komerční (na rozdíl od podpisových – ty použít nelze). Postup vytvoření klíčů a získání certifikátů se řídí certifikační politikou jednotlivých vydavatelů certifikátů.
Pouze v prostředí Veřejného testu ISDS lze použít také testovací komerční certifikáty autority PostSignum nebo I.CA.
Není možné použít stejný certifikát pro jeden typ služby u různých schránek.
Certifikát spisové služby
Pro registraci certifikátu spisové služby k dané datové schránce je třeba mít k dispozici certifikát ve formátu PEM a být přihlášen jako administrátor této schránky nebo oprávněná osoba.
Ujistěte se, zda soubor certifikátu je formátu PEM – to je textový soubor obsahující text „-----BEGIN CERTIFICATE-----“ následovaný několika řádky kódovaných informací (BASE64) a poté samostatným řádkem „-----END CERTIFICATE-----“.
V případě, že tomu tak není, je Váš soubor certifikátu v tzv. binárním formátu DER. Ten je třeba převést do formátu PEM. Pod Windows toho lze docílit importem do úložiště certifikátů a následným exportem ve formátu „Base-64 kódovaný certifikát X. 509 (*. CER)“.
- Pod záložkou Nastavení klepněte na odkaz Externí aplikace a pak spusťte příkaz Certifikát spisové služby.
- V okně vpravo klepněte na tlačítko Zaregistrovat certifikát.
- Pomocí schránky zkopírujte obsah souboru certifikátu do vstupního okénka Obsah certifikátu.
- Stiskem tlačítka Zaregistrovat certifikát formulář odešlete k registraci.
- Po stisku tlačítka se zobrazí stránka s detaily certifikátu pro kontrolu. Pokud vložíte certifikát, jemuž zbývá do konce platnosti méně, než 30 dní objeví se výrazný červený nápis:
Platnost certifikátu končí za <N> dní. Opravdu jej chcete použít pro komunikaci s ISDS? - Jestliže je vše v pořádku, znovu stiskněte tlačítko Zaregistrovat certifikát.
Po úspěšné registraci certifikátu se indikátor u položky Certifikát spisové služby změní na nápis Aktivní se zeleným zatržítkem. V okně vpravo se vypíšou údaje o certifikátu včetně data jeho exspirace. Od této chvíle může spisová služba nebo jiná aplikace přistupovat s využitím tohoto certifikátu do této datové schránky bez zadávání uživatelských přístupových údajů.
Pokud byste chtěli certifikát vymazat – například z důvodu ukončení jeho platnosti – klepněte na červenou položku smazat vypsanou u popisu certifikátu vpravo.
Pomocí tlačítka Zaregistrovat certifikát můžete registrovat jiný certifikát.
Certifikát hostované spisové služby
Pokud jste poskytovatel služby Hostovaná spisová služba, je třeba zaregistrovat ke své schránce (tj. schránce poskytovatele) certifikát, kterým bude služba přistupovat k datovým schránkám svých klientů. Postupujte podobně jako v případě registrace systémového certifikátu spisové služby.
Pro registraci certifikátu hostované spisové služby v systému ISDS je třeba mít k dispozici certifikát ve formátu PEM a být přihlášen jako administrátor schránky (nebo oprávněná osoba), která náleží poskytovateli – organizaci, spravující hostovanou spisovou službu (tedy ne schránek, do nichž se bude přistupovat).
Ujistěte se, zda soubor certifikátu je formátu PEM – to je textový soubor obsahující text „-----BEGIN CERTIFICATE-----“ následovaný několika řádky kódovaných informací (Base64) a poté samostatným řádkem „-----END CERTIFICATE-----“.
V případě, že tomu tak není, je Váš soubor certifikátu v tzv. binárním formátu DER. Ten je třeba převést do formátu PEM. Pod Windows toho lze docílit importem do úložiště certifikátů a následným exportem ve formátu „Base-64 kódovaný certifikát X. 509 (*. CER)“.
- Pod záložkou Nastavení klepněte na odkaz Externí aplikace a pak spusťte příkaz Certifikát hostované spisové služby.
- V okně vpravo klepněte na tlačítko Zaregistrovat certifikát.
- Pomocí schránky Windows zkopírujte obsah souboru certifikátu do vstupního okénka Obsah certifikátu.
- Stiskem tlačítka Zaregistrovat certifikát formulář odešlete k registraci.
- Po stisku tlačítka se zobrazí stránka s detaily certifikátu pro kontrolu.
- Jestliže je vše v pořádku, znovu stiskněte tlačítko Zaregistrovat certifikát.
Pokud jste poskytovatelem služby Hostovaná Spisová Služba, zaregistrovali jste certifikát, kterým budete přistupovat k datovým schránkám klientů. Nepoužívejte tuto stránku, pokud chcete některé z Hostovaných Spisových Služeb umožnit přístup ke své schránce. Příslušné nastavení zajistíte příkazem Hostované spisové služby.
Po úspěšné registraci certifikátu se indikátor u položky Certifikát hostované spisové služby změní na nápis Aktivní se zeleným zatržítkem. V okně vpravo se vypíšou údaje o certifikátu včetně data jeho exspirace. Od této chvíle může hostovaná spisová služba přistupovat s využitím tohoto certifikátu do datových schránek svých klientů (po jejich svolení) bez zadávání uživatelských přístupových údajů.
Pokud byste chtěli certifikát vymazat – například z důvodu ukončení jeho platnosti – klepněte na červenou položku smazat vypsanou u popisu certifikátu vpravo.
Pomocí tlačítka Zaregistrovat certifikát můžete registrovat druhý a další certifikáty.
Hostované spisové služby
Zde může administrátor schránky nebo oprávněná osoba povolit či odebrat přístup ke své datové schránce vybraným poskytovatelům služby Hostovaných spisových služeb. K povolení přístupu Vás může vyzvat pouze administrátor takové datové schránky, u níž je provedena registrace k této službě.
- Pod záložkou Nastavení klepněte na odkaz Externí aplikace a pak spusťte příkaz Hostované spisové služby.
- Zadejte ID schránky, které povolíte přístup do své schránky a stiskněte tlačítko POVOLIT PŘÍSTUP. Tuto akci provádějte pouze na vyzvání administrátora protější schránky.
Pokud není schránka zvoleného ID poskytovatelem hostované spisové služby, zobrazí se o tom informace a volba je odmítnuta.
Pokud je zadaná schránka poskytovatelem hostované spisové služby, provede se registrace a záznam se objeví v tabulce.
Pokud byste chtěli přístup hostované spisové služby zakázat, klepněte na červenou položku ZAKÁZAT PŘÍSTUP vypsanou u jejího popisu vpravo.
Pomocí tlačítka POVOLIT PŘÍSTUP můžete povolit k Vaší schránce přístup druhé a další hostované službě (ale takové řešení nemá kromě testování praktický význam).
Jiné externí aplikace (Přístupové rozhraní)
Tato služba umožňuje pro aktuální účet povolit nebo odebrat přístup externí aplikaci poskytovatele, která využívá tzv. Přístupové rozhraní datových schránek podle § 14a zákona č. 300/2008 Sb. Postupujte přesně podle návodu konkrétního poskytovatele.
- Pod záložkou Nastavení klepněte na odkaz Externí aplikace a pak spusťte příkaz Jiné externí aplikace.
- V okně vpravo zadejte ID schránky, ze které povolíte externí aplikaci přístup do své schránky a stiskněte tlačítko POVOLIT PŘÍSTUP. Tuto akci provádějte pouze na vyzvání administrátora protější schránky.
Pro poskytovatele externí aplikace se vygeneruje unikátní kód a zobrazí v okně. Tento kód si poznamenejte a podle pokynů poskytovatele služby mu jej předejte. V případě potřeby je možné vygenerovat nový kód opětovnou registrací na tomto místě.
POZOR: Předáním kódu poskytovateli služby udělujete jeho aplikaci souhlas získat informace o Vaší schránce a o Vás jako jejím uživateli, včetně Vašich osobních dat (jméno, příjmení, datum narození a adresa bydliště). Externí aplikaci poskytovatele služby také udělujete souhlas získat z této datové schránky obsah datových zpráv, a to i s osobními údaji, které v nich mohou být uvedeny.
Po úspěšné registraci externí aplikace se indikátor u položky Jiné externí aplikace změní na nápis Aktivní se zeleným zatržítkem. V okně vpravo se vypíšou údaje o zaregistrované aplikaci.
Pokud byste chtěli přístup externí aplikaci zakázat, klepněte na červenou položku Zakázat přístup vypsanou u jejího popisu vpravo.
Pomocí tlačítka Povolit přístup můžete povolit k Vaší schránce přístup druhé a další externí aplikaci s Přístupovým rozhraním (ale takové řešení nemá kromě testování praktický význam).
Poznámka: povolit přístup do své schránky externí aplikaci používající přístupové rozhraní je možné i jednodušším způsobem (pomocí Autentizačního rozhraní ISDS). Tento postup je používán např. u Portálu občana.
Pokud byste uvažovali o využití Přístupového rozhraní u své aplikace, je nutno kontaktovat Správce ISDS postupem popsaným zde. Registrace se neprovádí v klientském portálu.
Autentizační služba / Odesílací brána
Odesílací brána je komponentou ISDS, umožňující schválení či zamítnutí konceptu (návrhu) datové zprávy i její fyzické odeslání přímo ze schránky uživatele, v okně portálu otevřeném z externí aplikace. Odesílatel (uživatel schránky) tak může rozhodnout, zda datovou zprávu, připravenou externí aplikací, odešle nebo nikoliv. Autentizační služba je rozšíření Odesílací brány (dostupné pouze pro subjekty OVM), které umožňuje nejen poslat zprávu, ale hlavně externí aplikaci získat informace o schránce a uživateli, který se přihlásí do přihlašovací stránky ISDS, vyvolané z externí aplikace. Autentizační služba nemusí Odesílací bránu používat.
Přesnější popis a rozhraní pro vývojáře je součástí Provozního řádu ISDS.
Odesílací brána lze zaregistrovat pod kteroukoliv schránkou, Autentizační služba jen pod schránkou OVM. Popisována bude registrace Autentizační služby, registrace Odesílací brány je obdobná, jen jsou některá pole vynechána (bude upozorněno v textu). Nutná podmínka pro dokončení registrace je mít připravený komerční přihlašovací certifikát ve formátu PEM (textový formát).
Pokud chcete zaregistrovat pod svou schránkou Odesílací bránu / Autentizační službu, proveďte následující kroky:
- Pod záložkou Nastavení klepněte na odkaz Externí aplikace a pak spusťte příkaz Odesílací brána nebo Autentizační služba (nabídka je dána typem schránky). Dále bude popisována pouze Autentizační služba.
- V okně vpravo stiskněte tlačítko Zaregistrovat novou autentizační službu.
Otevře se tříkrokový formulář (u Odesílací brány jen dvoukrokový), ve kterém zadáte všechny potřebné parametry.
Pro vývojáře externích aplikací, kteří chtějí využívat Odesílací bránu nebo Autentizační službu, existuje technická dokumentace, popisující mj. i význam následujících parametrů.
V prvním kroku formuláře je třeba zadat základní parametry služby:
Kromě názvu služby (pole Název služby) a návratové hodnoty adresy URL (pole Návratové URL) a adresy, kam má být řízení přesměrováno při chybě přihlášení (pole URL při chybě) je třeba zadat i časovou platnost konceptu datové zprávy pro Odesílací bránu – tu nabízí na výběr Platnost konceptu: 30 minut, 60 minut (výchozí volba), 90 minut a 120 minut. Standardně přihlašovací stránka služby nabízí také přihlášení pomocí portálu Identita občana (tj. NIA) – pokud si nepřejete tuto volbu nabízet (zejména proto, že ji nabízíte samostatně vedle přihlášení do ISDS), zaškrtněte příslušný přepínač.
Dále jsou dvě editační položky, povinné (ze zákona) pro Autentizační službu. Stručně popište důvod, proč a nač požadujete po uživateli osobní údaje, a také, jak dlouho je hodláte uchovávat. Podle těchto textů se může uživatel rozhodnout, zdali Vaší aplikaci data svěří či nikoliv. Nesmyslné nebo zjevně nesprávné údaje mohou být důvodem, proč správce ISDS službu zablokuje.
Ve druhém kroku (pouze pro Autentizační službu) se vybírají jednotlivé atributy uživatele, který se přihlásil, a jeho datové schránky. Tyto údaje předá Autentizační služba externí aplikaci. Stejně jako v předešlém kroku – vybrané atributy musí odpovídat charakteru aplikace, správce může (a měl by) kontrolovat jejich rozsah.
Tlačítkem Vybrat vše si můžete ulehčit klikání v případě, že požadujete větší množství údajů.
Poslední z údajů – Odkaz na záznam o uživateli v Registru obyvatel – je výrazně složitější na zpracování: vyžaduje komunikaci s IS základních registrů na straně ISDS i na straně Vaší aplikace pro překlad tohoto kódu na AIFO Vaší organizace. Pokud s ISZR nekomunikujete, nezatrhávejte jej, výrazně urychlíte odezvu Autentizační služby.
V třetím kroku se zadává komerční certifikát, pomocí něhož bude Vaše aplikace komunikovat s ISDS.
Potřebný certifikát se zadává do okénka Obsah certifikátu zkopírováním jeho textové PEM podoby, a to stejně jak je popsáno na jiných místech této dokumentace; například v kapitole Registrace systémového certifikátu pro spisové služby.
Po stisku tlačítka VLOŽIT CERTIFIKÁT se zobrazí detaily registrovaného certifikátu v čitelné podobě. Současně se zkontroluje validita zápisu a v případě chyby se zobrazí vysvětlující komentář. Stiskněte znovu tlačítko REGISTROVAT. Tím je registrace u konce, získá unikátní ID, které budete používat při komunikaci s ISDS. Službu je možné okamžitě používat (po naprogramování protistrany ve Vaší aplikaci).
Vrátíte se zpět na stránku se seznamem registrací (pod jednou schránkou jich může být více, ale s různými certifikáty). Významný je sloupec Stav: pouze hodnota Aktivní znamená, že je služba funkční, může být neaktivní z více důvodů, zejména blokování správcem v případě nějakého sporu. Ve sloupci Typ je vidět typ registrace: OB = Odesílací brána, AS = Autentizační služba, možné způsoby jsou „OB“ nebo „OB + AS“.
Odesílací brána bezprostředně po registraci není ještě aktivní. Klepnutím na tlačítko Možnosti se otevře příkazová nabídka se třemi příkazy:
- Aktivovat – aktivuje bránu, takže od této chvíle ji bude možné používat. Příkaz se změní na Deaktivovat. Služba může být neaktivní z více důvodů, některé nemůžete ovlivnit. Pokud se stav nezmění na Aktivní, zeptejte se správce.
- Upravit – umožní upravit parametry registrované služby, zejména vyměnit certifikáty, kterým se blíží exspirace (nejčastější důvod nefunkčnosti služby!), lze ale i změnit texty či název služby. Změna parametrů probíhá ve stejných třech (resp. dvou) krocích jako u registrace služby. Jediná změna je u certifikátů – protože je možno zadat více než jeden, je zde možnost vidět seznam vložených.
- Odregistrovat – zruší nevratně registraci služby a vymaže její popis.
Tlačítkem Zaregistrovat novou … můžete zaregistrovat druhou, případně další brány/služby.
Správa certifikátů
Nejčastějším důvodem pro editaci fungující služby je každoroční výměna certifikátů. Je dovoleno (a je rozumné) vkládat další s přesahem platnosti, přihlašovat se lze kterýmkoliv z nich. Staré, již exspirované, je možno mazat. Tlačítkem přidat nový certifikát se otevře okno pro vložení certifikátu, popsané výše při registraci.
