Inštalačná príručka popisuje komponent verzie 3.7.3, uistite sa, že čítate príručku verzie komponentu, ktorý používate.
Máme dobrú a zlú správu. Tá zlá správa je, že na zfunkčnenie tohto komponentu (alebo akejkoľvek inej integrácie na slovensko.sk) je nutné prejsť pomerne náročný proces s NASES a vypracovať množstvo dokumentácie. Tá dobrá správa je, že sme to skoro celé spravili za Vás a tento návod by mal úplne stačiť na to, aby ste komponent dostali do produkčnej prevádzky. Ak sa Vám to zdá zložité, ozvite sa nám emailom na [email protected] a radi pomôžeme.
Komponent slovensko.sk API je distribuovaný ako Docker kontajner, ktorý sa spúšťa štandardne, najľahšie cez docker-compose.
Pred prvým spustením je potrebné pripraviť si adresár, ktorý bude obsahovať:
- docker-compose.yml upravený podľa potreby,
- .env s doplnenými hodnotami premenných prostredia podľa potreby,
- všetky bezpečnostné súbory, ktoré komponent požaduje podľa upraveného
.envsúboru.
Pričom:
- ak potrebujete automatickú synchronizáciu eForm formulárov, musíte do súboru
docker-compose.ymlpridať službyclockaworkertak, ako je to v tomto docker-compose.yml súbore, - ak potrebujete podporu pre OBO autentifikáciu bez ÚPVS SSO na strane komponentu, musíte do súboru
.envpridať premennúSSO_PROXY_SUBJECTtak, ako je to v tomto .env súbore. - ak potrebujete podporu pre autentifikáciu cez ÚPVS SSO, musíte do súboru
.envpridať ďaľšie premenné tak, ako je to v tomto .env súbore.
Pozri časť Konfigurácia API komponentu.
Najskôr je potrebné inicializovať databázu cez:
docker-compose run web bundle exec rails db:create db:migrate
Potom je možné spustiť komponent:
docker-compose up
Komponent by mal bežať na porte 3000, stav je možné skontrolovať pomocou:
curl localhost:3000/health
Možnosti komponentu popisuje Špecifikácia API.
Log komponentu ide na štandardný výstup.
Najskôr je potrebné stiahnuť nový komponent:
docker-compose pull
Následne je možné komponent reštartovať:
docker-compose stop
docker-compose up --force-recreate
Na rozdiel od docker-compose restart toto reflektuje aj zmeny v rámci súboru docker-compose.yml.
Ukážka odoslania SKTalk správy a uloženia medzi odoslané správy v schránke
curl -H 'Authorization: Bearer API-TOKEN' -H 'Content-Type: application/json' -d '{ "message": SKTALK-MESSAGE }' localhost:3000/api/sktalk/receive_and_save_to_outbox
kde API-TOKEN je JWT vytvorený podľa Špecifikácie API a SKTALK-MESSAGE je valídna SKTalk správa s unikátnym MessageID (prípadne aj CorrelationID) a správne nastaveným SenderId a RecipientId.
V prípade potreby je možné vyskúšať komponet prevádzkovaný na strane Slovensko.Digital vo FIX prostredí:
-
komponent vo FIX prostredí je dostupný na URL
https://fix.slovensko-sk-api.staging.slovensko.digitalpozri aktuálny stav komponentu a špecifikáciu API nasadenej verzie.
Zoznam premenných prostredia a bezpečnostných súborov potrebných pre spustenie komponentu.
| Premenná | Popis | Hodnota |
|---|---|---|
RAILS_ENV |
Prostredie Rails aplikácie1 | development (predvolená), test, staging alebo production |
RAILS_CACHE_ID |
Identifikátor Rails Cache1 | jedinečný identifikátor (potrebná iba v prostredí kde beží viacero komponentov) |
LOG_LEVEL |
Úroveň logovania Rails aplikácie2 | debug (predvolená), info, warn, error alebo fatal |
SECRET_KEY_BASE |
Kľúč zabezpečenia Rails aplikácie5 | bezpečný reťazec |
TIME_ZONE |
Časové pásmo Rails aplikácie | Europe/Bratislava (predvolená) alebo UTC a pod. |
UPVS_ENV |
Prostredie ÚPVS2 | fix (predvolená), dev alebo prod |
UPVS_LOG_LEVEL |
Úroveň logovania ÚPVS komunikácie3 | trace, debug, info (predvolená), warn, error alebo off (predvolená ak RAILS_ENV=test alebo UPVS_ENV=prod) |
UPVS_KS_SALT |
Soľ hesla k úložisku certifikátov6 | bezpečný reťazec (potrebná iba ak UPVS_ENV=prod) |
UPVS_PK_SALT |
Soľ hesla k privátnemu kľúču v úložisku certifikátov6 | bezpečný reťazec (potrebná iba ak UPVS_ENV=prod) |
EFORM_SYNC_SUBJECT |
Subjekt ukazujúci na STS certifikát pre automatickú synchronizáciu eForm formulárov7 | {sub} (potrebná iba pre eForm Sync) |
SSO_SP_SUBJECT |
Subjekt ukazujúci na SP certifikát pre podpisovanie pri autentifikácii cez ÚPVS SSO8 | {sub} (potrebná iba pre ÚPVS SSO) |
SSO_PROXY_SUBJECT |
Subjekt ukazujúci na STS certifikát pre OBO prístup pri autentifikácii cez ÚPVS SSO9 | {sub} (potrebná pre OBO autentifikáciu) |
LOGIN_CALLBACK_URL |
Základná URL, na ktorú može byť používateľ presmerovaný po úspešnom prihlásení | bezpečná URL (potrebná iba pre ÚPVS SSO) |
LOGOUT_CALLBACK_URL |
Základná URL, na ktorú može byť používateľ presmerovaný po úspešnom odhlásení | bezpečná URL (potrebná iba pre ÚPVS SSO) |
STS_HEALTH_SUBJECT |
Subjekt ukazujúci na STS certifikát pre kontrolu spojenia s ÚPVS STS | {sub} (potrebná iba pre STS Health) |
1 Rails Environment Settings
2 Integračný manuál ÚPVS IAM, pozri časť 1.
3 Debugging Rails Applications
4 Logback Architecture
5 Reťazec vygenerovaný príkazom rails secret
6 Reťazec dlhý aspoň 40 znakov
7 Nastavenie premennej zapína automatickú synchronizáciu eForm formulárov
8 Nastavenie premennej zapína podporu pre autentifikáciu cez ÚPVS SSO
9 Nastavenie premennej zapína podporu pre OBO autentifikáciu
| Súbor | Popis | Podpora ÚPVS SSO/ OBO autentifikácie vypnutá |
|---|---|---|
security/api_token_{RAILS_ENV}.public.pem |
Verejný kľúč pre verifikáciu API tokenov1 | |
security/obo_token_{RAILS_ENV}.private.pem |
Privátny a verejný kľúč pre generovanie a verifikáciu OBO tokenov2 | Nepotrebný |
security/sso/upvs_{UPVS_ENV}.metadata.xml |
Metadáta IDP3 | Nepotrebný |
security/sso/{SSO_SP_SUBJECT}_{UPVS_ENV}.metadata.xml |
Metadáta SP3 | Nepotrebný |
security/sso/{SSO_SP_SUBJECT}_{UPVS_ENV}.keystore |
Úložisko SP certifikátu pre podpisovanie5,6 | Nepotrebný |
security/sts/{SSO_PROXY_SUBJECT}_{UPVS_ENV}.keystore |
Úložisko STS certifikátu pre OBO prístup5,6 | Nepotrebný |
security/sts/{sub}_{UPVS_ENV}.keystore |
Úložisko STS certifikátu4,5,6 | |
security/tls/upvs_{UPVS_ENV}.truststore |
Úložisko TLS certifikátov7,8 |
1 Kľúč vygenerovaný príkazom openssl genrsa -out api_token_development.private.pem 2048 a openssl rsa -in api_token_development.private.pem -pubout -out api_token_development.public.pem
2 Kľúč vygenerovaný príkazom openssl genrsa -out obo_token_development.private.pem 2048
3 Metadáta IDP / SP musia byť zaregistrované v prostredí ÚPVS, pozri časť 6.
4 Hodnota SUB claim z API tokenu nahrádza výraz {sub} v názve súboru
5 Certifikát v úložisku musí byť zaregistrovaný v prostredí ÚPVS, pozri časť 6.
6 Heslo k úložisku a heslo k privátnemu kľúču v prostredí ÚPVS FIX je password. Pozor, tieto heslá v prostredí ÚPVS PROD sú SHA1 podľa vzorov {UPVS_KS_SALT}:{sub} (pre heslo k úložisku) a {UPVS_PK_SALT}:{sub} (pre heslo k privátnemu kľúču) v hexadecimálnom formáte
7 Certifikát v úložisku pre prostredie ÚPVS DEV sa dá získať napr. cez echo | openssl s_client -servername 'vyvoj.upvs.globaltel.sk' -connect 'vyvoj.upvs.globaltel.sk:443' | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > upvs_dev.crt
8 Heslo k úložisku v prostredí ÚPVS DEV, FIX a PROD je password
Pokyny k žiadosti o zriadenie prístupu je možné nájsť iba v častých otázkach na stránke NASES v otázke Kde získam prístup do Partner Framework Portálu?. Samotnú žiadosť je možné nájsť iba vyhľadávaním na internete. V čase písania návodu je platný tento link.
Odporúčame si prístup zriadiť, kedže sa na partner framework portáli, okrem dokumentácie, nachádzajú aj informácie o plánovaných odstávkach a ďalšom rozvoji ÚPVS.
Je potrebné si zvoliť skratku projektu, ktorá sa bude používať pre účely komunikácie s NASES. Názov môže obsahovať len veľké písmená, bez diakritiky a medzier, a musí byť unikátny. My sme napríklad použili názov PODAAS, ten je už obsadený.
Stiahnite si šablónu dohody o integračnom zámere z partner framework portálu a upravte podľa potreby. Pozor, treba sa uistiť, že používate aktuálnu šablónu NASES, pretože tie sa v čase menia.
Do názvu súboru doplňte skratku Vášho projektu, IČO Konzumenta a DIZ vo formáte Microsoft Word priložte ako prílohu k emailu:
Adresát: [email protected]
Predmet: {project} – FIX – DIZ – Žiadosť – Revízia dohody o integračnom zámere – v1
Dobrý deň,
týmto zasielam na revíziu DIZ nového projektu.
Prosím o potvrdenie, že žiadosť ste zaevidovali.
Ďakujem.
Po schválení DIZ je potrebné DIZ vytlačiť 3x, podpísať a zaslať poštou (alebo osobne doručiť) do NASES na adresu:
Národná agentúra pre sieťové a elektronické služby
Tower 115
Pribinova 4195/25
811 09 Bratislava
Požiadajte o vytvorenie infraštruktúrneho prepojenia emailom (do textu doplňte názov projektu a vyberte jednu z možností Govnet/Internet):
Adresát: [email protected]
Predmet: {project} - FIX/PROD - INFRA - Žiadosť - Pridelenie adresného rozsahu
Dobrý deň,
týmto žiadam pre projekt {projekt} - {nazov-projektu} o pridelenie adresného rozsahu pre tunel do FIX prostredia a zaslanie potrebného XLS pre špecifikáciu komunikácie. Komunikácia bude prebiehať cez Govnet / Internet.
Ďakujem.
NASES Vám zašle naspäť XLS dokument, ktorý bude treba doplniť nasledovne:
- V prvej záložke Základné údaje nájdete
Pridelený koordinovaný rozsah pre služby v tuneloch ES:napríklad100.66.0.128/28. Od tohto rozsahu sa odvíjajú nasledujúce nastavenia. - V prvej záložke vyplňte potrebné kontaktné údaje pre externý subjekt (to ste Vy)
- V tretej záložke Integračné a aplikačné endpointy vyplňte všetky riadky stĺpca
Rozhranie ES TunelIPtak, že pre FIX prostredie uvediete piatu adresu rozsahu (t.j. pre rozsah100.66.0.128/28to bude100.66.0.128 + 5=100.66.0.133) a pre PROD prostredie desiatu adresu rozsahu100.55.0.128 + 10=100.66.0.138. - V tretej záložke Integračné a aplikačné endpointy následne označte červeným pozadím riadky s rozhraním
IAM-WS - 1.7, 2.0toto sa nepoužíva, ostatné riadky označte zeleným pozadím. Teda:schranka - EKR,UIR (URP, URZ - BPM),USR (SB-Ext. Zbernica)ajIAM-STS. - V štvrtej záložke GUI Endpointy Test-Fix povoľte prístup z internetu cez GUI pre Portal 1.7, 2.0, Prihlasenie IAM, Formulare, eFormulare, schranka - eDesk 1.7, 2.0.
- V štvrtej záložke GUI Endpointy Test-Fix do
IP GW ES pre povolenie pristupu ku GUI rozhraniam:uveďte verejnú IP adresu stroja, cez ktorý sa pristupovať k portálu pre účely testovania. - V piatej záložke DNS uveďte ako
IP ES Sitepre FIX tretiu adresu rozsahu (t.j. pre rozsah100.66.0.128/28to bude100.66.0.128 + 3=100.66.0.131) a pre PROD štvrtú adresu rozsahu (t.j. pre rozsah100.66.0.128/28to bude100.66.0.128 + 4=100.66.0.132) - V záložke IPsec LAN to LAN uveďte do
Remote VPN gateway IP address ( ES site )verejnú IP adresu stroja, kde bude bežať tento komponent (resp. koniec IPsec tunela)
Doplnený XLS dokument priložte ako prílohu k emailu:
Adresát: [email protected]
Predmet: {project} - FIX/PROD - INFRA - Žiadosť - Vytvorenie infraštruktúrneho prepojenia
Dobrý deň,
týmto žiadam o zriadenie tunela do FIX prostredia. Vyplnenú konfiguráciu posielam v prílohe.
Ďakujem.
Požiadajte o vytvorenie identít emailom:
Adresát: [email protected]
Predmet: {project} - FIX - IAM - Žiadosť - Zriadenie identít a zastupovanie
Dobrý deň,
týmto žiadam o vytvorenie testovacích identít 4x FO, 2x PO a 2x OVM, pričom prvé dve FO zastupujú PO a druhé dve FO zastupujú OVM.
Ďakujem.
Pre vytvorené identity vygenerujte STS certifikáty. Reťazec {sub} v názvoch súborov a aliasoch nahraďte vhodnou skratkou Vašej integrácie, podobne upravte hodnotu CN certifikátov, kde {cin} je IČO a {suffix} je identifikačné číslo organizácie v prípade ak ide o organizačnú zložku.
keytool -genkeypair -alias {sub} -keyalg RSA -keysize 2048 -sigalg sha512WithRSA -dname "CN=ico-{cin}_{suffix}" -validity 730 -keypass password -keystore {sub}_fix.keystore -storepass password
keytool -export -alias {sub} -keystore {sub}_fix.keystore -storepass password > {sub}_fix.crt
keytool -export -alias {sub} -keystore {sub}_fix.keystore -storepass password -rfc > {sub}_fix.pem
Vygenerované certifikáty je následne potrebné zaregistrovať vyplnením formuláru Zriadenie technického účtu a registrácia certifikátu v časti Môj profil – Technické účty a certifikáty, ktorý je dostupný po prihlásení testovacej identity (FO) na ÚPVS portál v zastúpení testovacej identity (PO alebo OVM), pre ktorú bude registrácia príslušného certifikátu vykonávaná, pozri Návod na využívanie služieb centrálneho registra autentifikačných certifikátov.
Ak potrebujete podporu pre podpisovanie podaní, požiadajte o pridelenie testovacieho KSC emailom, ku ktorému je potrebné priložiť vyplnenú žiadosť, ktorú nájdete v dokumente "Všeobecný popis integrácie" dostupnom na PFP:
Adresát: [email protected]
Predmet: {project} - FIX - CEP - Žiadosť - Vytvorenie a registrácia testovacieho KSC
Dobrý deň,
týmto zasielam žiadosť o vytvorenie a registráciu testovacieho KSC. Detailné informácie k certifikátu zasielam v prílohe.
Ďakujem.
Ak potrebujete podporu pre autentifikáciu cez ÚPVS SSO, podobne vygenerujte SP certifikáty pre šifrovanie a podpisovanie, certifikát určený pre šifrovanie sa musí odlišovať od certifikátu určeného pre podpisovanie. Následne vytvorte {sub}_fix.metadata.xml podľa súboru podaas_dev.metadata.xml, kde {sub} bude hodnota SSO_SP_SUBJECT, pričom treba nahradiť entityID, verejné klúče pre šifrovanie a podpisovanie (skopírovaním z PEM súborov) a endpointy, kde bude testovacia verzia bežať.
Vygenerované metadáta je následne potrebné zaregistrovať vyplnením formuláru Registrácia poskytovateľa služieb v časti Môj profil – Technické účty a certifikáty, ktorý je dostupný po prihlásení testovacej identity (FO) na ÚPVS portál v zastúpení testovacej identity (PO alebo OVM), pre ktorú bude registrácia príslušných metadát vykonávaná, pozri Návod na využívanie služieb centrálneho registra SP metadát.
Na základe konfigurácie tunela a infraštruktúrenho prepojenie je potrebné adekvátne tomu nastaviť sieťovú infraštruktúru. Ak sa váš server pripája k ÚPVS prostredníctvom IPSec tunela a nenachádza sa fyzicky v požadovanej podsieti, je potrebné nejakým spôsobom simulovať source_ip odchádzajúcich requestov - napríklad pomocou HAProxy.
Pokyny k nasadneiu nášho komponentu sa nachádzajú na začiatku tohto dokumentu.
Stiahnite si šablónu akceptačného protokolu z partner framework portálu a upravte podľa potreby. Pozor, treba sa uistiť, že používate aktuálnu šablónu NASES, pretože tie sa v čase menia. Testovanie je potrebné zrealizovať na FIX prostredí s využitím na FIX registrovaných integračných artefaktov a identít. Test cases v UAT dokumente musia obsahovať payloady volaní a taktiež relevantné screenshoty.
Do názvu súboru doplňte skratku Vášho projektu, IČO Konzumenta a UAT protokol vo formáte Microsoft Word priložte ako prílohu k emailu:
Adresát: [email protected]
Predmet: {project} – FIX – UAT – Žiadosť – Revízia akceptačného protokolu
Dobrý deň,
zasielam vypracovaný akceptačný protokol (v prílohe) na revíziu.
Prosím o potvrdenie, že žiadosť ste zaevidovali.
Ďakujem.
Po schválení UAT je potrebné UAT vytlačiť 3x, podpísať a zaslať poštou (alebo osobne doručiť) do NASES na adresu:
Národná agentúra pre sieťové a elektronické služby
Tower 115
Pribinova 4195/25
811 09 Bratislava
Pre prechod do produkčného prostredia je potrebné požiadať o otvorenie infraštruktúrneho tunela pre PROD. Žiadosť je potrebné mailom zaslať nasledovne:
Adresát: [email protected]
Predmet: {project} – PROD – INFRA – Žiadosť – Sprístupnenie tunela v PROD
Dobrý deň,
týmto žiadam pre projekt {projekt} - {názov-projektu} o sprístupnenie tunela do PROD prostredia. Infraštruktúrnu maticu posielam v prílohe.
Ďakujem.
Do prílohy, priložte inframaticu z bodu 3 doplnenú o PROD endpointy, ktoré musia byť v súlade so službami uvedenými v DIZ a riadne otestovanými v UAT protokole.
Následne bude potrebné zaregistrovať technický účet a v prípade využívania ÚPVS SSO aj metadáta Service Providera.