Nastavení připojení k EWP síti

Připojení do EWP sítě probíhá přes tzv. "manifest". Instituce na svém serveru zveřejní soubor (manifest), který obsahuje základní informace, cesty k jednotlivým zveřejněným API a certifikáty pro komunikaci. 

Návod na připojení

Následující text obsahuje návod na připojení do EWP sítě. Základní kroky jsou stejné, jak pro připojení do testovací DEV EWP sítě, tak do produkční EWP sítě. Postup se liší až v závěrečném kroku, ve kterém instituce žádá o připojení do zvolené sítě. 

Návod obsahuje základní informace pro první připojení k síti EWP. Pokud již škola byla připojena přes jiného poskytovatele a vyměňovala přes síť EWP data, je potřeba domluvit migraci existujících dat, aby zůstala v síti EWP správně dostupná.

Nastavení parametrů

Nejprve je nutné nastavit parametry v databázi.

Identifikační údaje:

• EWP_ERASMUS_CHARTER - Obsahuje identifikátor Erasmus Charter (EUC, ECHE, atd.). Např. 12345-EPP-1-2014-1-CZ-EPPKA3-ECHE. Od roku 2021 se kód změnil na "Proposal Number", které najdete uvedené v dokumentu na stránce Higher education institutions holding an ECHE. Např. 101012323
  
• EWP_ERASMUS_PIC - Devítimístný Personal Identifier Code (PIC).
• EWP_ERASMUS_SCHAC - Povinný identifikátor v EWP síti, který jednoznačně identifikuje organizaci. Je vytvořen podle jména internetové domény, kterou má organizace registrovanou. Např. zcu.cz pro Západočeskou univerzitu.
• EWP_ERASMUS_PREDCHOZI_SCHAC - Obsahuje seznam dříve používaných SCHAC ID, které byly uvedeny v parametru EWP_ERASMUS_SCHAC. Aktuálně není potřeba vyplnit, protože dřívější SCHAC ID neexistovalo.

Konfigurace:

• EWP_ZVEREJNENA_API - Umožňuje nastavit, která API se budou v EWP síti používat. Aktuálně je dostupná pouze podmnožina vybraných API.
  

V budoucnu mohou další parametry přibývat. 

Volba certifikátu

Aplikace pro svůj provoz potřebuje certifikát pro TLS ověření klienta. V základní konfiguraci aplikace používá certifikát, který se na serveru již nachází. Pokud tento certifikát použít nechcete, můžete si jej změnit. Stačí si nechat vystavit nový certifikát, nejlépe podepsaný certifikační autoritou, a následně ho umístit na server k již existujícímu serverovému certifikátu. V konfiguračním souboru je následně nutné nastavit k tomuto certifikátu cestu. Napiště nám do RT, jak se soubor s certifikátem jmenuje a my Vám jeho použití nastavíme. 

To samé platí o RSA šifrovacích klíčích, které aplikace používá k HTTP podepisování požadavků a odpovědí při výměně dat mezi klienty. V základní konfiguraci aplikace používá klíče, které patří k certifikátu serveru. Pokud si pro komunikaci připravíte certifikát nový, budou se pro HTTP podepisování používat i nové RSA klíče. Jejich použití je také nutné nastavit v konfiguračním souboru.

Nastavení firewallu

Aktuálně je doporučeno, aby komunikace v síti EWP probíhala na standardním portu 443. Proto speciální nastavení firewallu již není pravděpodobně potřeba.

Pokud máte přístup na standardní port omezen, je možné nastavit přístup pouze k EWP části webových služeb přes server, který bude komunikaci na server s webovými službami filtrovat a EWP komunikaci zpřístupní. Pro více informací a konzultaci nás kontaktujte přes RT.

Jednotlivá API budou přistupná na portu 8843 (pozor neplést s portem 8443). Proto je nutné tento port ve firewallu povolit pro příchozí komunikaci. Povolení portu je nutné nastavit jak pro stroj, kde běží modul WS, tak i případně v centrálním firewallu, pokud je používán.

Na portu 8843 bude dočasně zveřejněn už jen manifest. Ostatní API jsou přesunuta na standardní port 443.

Jelikož nikde není specifikováno, na kterých portech by měla komunikace probíhat, mohou různé instituce používat různé porty. Obecně lze použité porty zjistit z katalogu na stránce https://dev-registry.erasmuswithoutpaper.eu/ (příp. https://registry.erasmuswithoutpaper.eu/) Aktuálně většina institucí komunikuje na standardních portech a existují jen čtyři další porty, na kterých komunikace probíhá. Nicméně další porty mohou přibývat, a proto zde nemůžeme vystavit seznam, podle kterého byste si mohli povolit ve firewallu porty pro odchozí komunikaci, pokud tuto komunikaci omezujete.

Test nastavení

Je vhodné otestovat, zda je vše nastaveno správně. Do prohlížeče je možné zadat URL manifest souboru a podívat se, zda se vrátí XML soubor s identifikačními údaji univerizity a zveřejněnými API.

<url_webu>/ws/services/ewp/manifest

Dále je možné funkčnost ověřit na jednom ze základních API. Základní informace o instituci nevyžadují autentizaci. Proto je možné do prohlížeče zadat URL podle následujícího vzoru a podívat se, zda se vrátí data o instituci.

<url_webu>/ws/services/ewp/institutions?hei_id=<EWP_ERASMUS_SCHAC>

Připojení k síti EWP

Připojení k EWP síti probíhá přes tzv. Registrační portál (RP), který umožňuje spravovat připojení k síti EWP. Existuje ve dvou instancích - testovací pro DEV síť EWP a produkční pro ostrou síť EWP.

Nový Registrační portál aktuálně nahrazuje původní:

Nastavení přístupu do RP

Přístup do obou RP je pro instituce přes MyAcademicID (které je nadstavbou nad eduGAIN). Na své škole si musíte zvolit zástupce, který bude spravovat EWP připojení přes RP (tzv. EWP administrátor). Níže je shrnutí základních informací, podrobné informace naleznete v dokumentu od strany 21.

EWP administrátor potřebuje, aby systém do RP po přihlášení vracel:

• Některou z položek pro jednoznačnou identifikaci uživatele
  
  • Persisten NameID
  • eduPersonPrincipalName
  • eduPersonTargetID
  • eduPersonUniqueId
  • eduPersonOrcid
  • subject-id
  • pairwise-id
• eduPersonAssurance - jen pokud je poskytováno pouze eduPersonPrincipalName
• Některou z položek, která obsahuje jméno uživatele
  
  • cn
  • displayName
  • sn + givenName
• mail - pro zasílání notifikací
• schacHomeOrganization - identifikátor instituce (musí shodovat s hodnotou parametru EWP_ERASMUS_SCHAC)
• eduPersonScopedAffiliation
• eduPersonEntitlement - atribut, který je přidelený pouze roli EWP administrátor, jeho hodnota musí být urn:geant:erasmuswithoutpaper.eu:ewp:admin

Po nastavení uvedených parametrů se může EWP administrátor do RP přihlásit. Po kliknutí na tlačítko Login as HEI se mu zobrazí výběr instituce. Následně se přihlásí do systému své univerzity a potvrdí parametry, které jsou do RP předávány.

Následně se mu zobrazí RP, kde může potvrdit manifest, který jsme tam nahráli (jako poskytovatel Vašeho připojení k síti EWP) a který budete v síti EWP používat. A prohlédnout si, která API jsou do sítě již připojena.