Viranomaisen ohje palveluun liittymiseksi
OHJE 2 (11) DOKUMENTINHALLINTA Omistaja Laatinut Mikko Väkiparta, Hannu Korkeala, Pertti Suomela Tarkastanut Hyväksynyt VERSIONHALLINTA Versionumero Mitä tehty Pvm / henkilö 0.1 Vanhan dokumentin tiedot siirretty uudelle pohjalle 15.9.2017 / Mikko Väkiparta 0.2 Tietojen päivitys 23.10.2017 / Mikko Väkiparta 0.3 Päivitetty ohjetta saatujen kommenttien perusteella 15.11.2017 / Mikko Väkiparta 0.4 Päivitetty ohjetta saatujen kommenttien perusteella 17.11.2017 / Mikko Väkiparta 0.5 0.6 Yhdistelty dokumentin Suomi.fi viestit ympäristöt v0.2 kanssa. Lisätty luku 2 käyttöönoton prosessista. Paljon korjauksia muuhun tekstiin 1.12.2017 / Henry Päivänsäde 19.1.2018 / Hannu Korkeala 0.7 Korjattu tekstiä erityisesti luvuissa 3 ja 4. 26.1.2018 / Pertti Suomela 0.8 Korjauksia ja muutosmerkintöjen poisto 31.1.2108 / Hannu Korkeala 0.9 Kolmas kuva luvussa 3.1 korjattu 12.2.2018 / Pertti Suomela 1.0 Paluukanavan konfiguroinnin muutos allekirjoittamattomasta allekirjoitettuun lisätty. 19.3.2018 / Pertti Suomela 1.0.1 Valtorin varmenteiden jakosivun osoite päivitetty 7.6.2018 / Pertti Suomela 1.1 Asiakas- ja palvelutietolomakkeen ohjeistus verkkolomakkeen mukaan, SanomaVarmenneNimikentän käytön ohjeistus / Pertti Suomela
OHJE 3 (11) Sisällysluettelo 1 Johdanto... 4 2 Käyttöönottoprosessi... 4 2.1 Käyttöluvan hakeminen... 5 2.2 Tietoliikenneavausten tekeminen... 5 2.3 Asiakas- ja palvelukohtaisten tietojen määrittely palveluliittymään... 6 2.4 Asiakkaan testaus... 6 3 Viranomaispalveluiden... 6 3.1 Palveluun liittyminen ja testaaminen... 6 3.2 Tuotantoympäristö... 9 4 Web Service -tietoliikenteen toteuttaminen... 9 4.1 Palvelinvarmenteet... 9 4.2 Kutsujen allekirjoittaminen ja varmenteet... 9 4.3 Viranomaisjärjestelmästä tarvittavat tiedot...10 4.3.1 Kutsun lähettävien palvelimien osoitteet...10 4.3.2 Viranomaistunnus ja siihen liitettävät raportointitiedot...10 4.3.3 Allekirjoitukseen käytetty varmenne...10 4.4 Paluukanavan...10 4.4.1 Palvelun rakenne...10 4.4.2 Viranomaisjärjestelmän palvelun tiedot... 11
OHJE 4 (11) SUOMI.FI VIESTIT -PALVELUN KÄYTTÖÖNOTTO 1 Johdanto 2 Käyttöönottoprosessi Suomi.fi Viestit -palveluun voidaan liittyä teknisesti kolmella eri liityntätavalla: sähköpostiliityntä integraatiorajapinnan käyttö (Web Service) ipost/sftp-liityntä Tämä dokumentti kuvaa luvussa 2 näille kaikille liityntätavoille yhteiset käyttöönoton vaiheet. Luvusta 2 eteenpäin käsitellään tarkemmin tietoja ja toimenpiteitä, jotka ovat välttämättömiä viranomaisille, jotta ne voivat ryhtyä käyttämään Suomi.fi Viestit -palvelua integraatiopalvelu VIA:n tarjoamien palveluiden avulla Web Service -rajapinnan kautta. Nämä dokumentin osat on tarkoitettu viranomaisjärjestelmiä kehittäville teknisille vastuuhenkilöille (esim. suunnittelijat ja arkkitehdit) sekä järjestelmistä viranomaisilla vastaaville henkilöille. Web Service -rajapinta jakaantuu lähettävän organisaation kannalta kahteen eri kokonaisuuteen eli viestin lähettämistä ja muita asiakasviraston suorittamia operaatioita koskevaan Viranomaispalvelut-rajapintaan ja vastaanottamista koskevaan Paluukanava-rajapintaan. Näitä vastaavat rajapintakuvaukset ovat saatavilla esuomi.fi:ssä. Paluukanavan -osuudessa oletetaan, että samaiselle viranomaistunnukselle on tehty, tai tehdään samanaikaisesti viranomaispalveluiden osalta. Käyttöönottoprosessista on yleinen kuvaus esuomi.fi:ssä kohdassa https://esuomi.fi/palveluntarjoajille/viestit/kayttoonoton-vaiheet/. Tässä kuvataan a viraston ja VRK:n keskinäistä yhteyttä edellyttävien tehtävien ja vaiheiden näkökulmasta. Näiden lisäksi virastolla on omaan projektiinsa liittyviä suunnitteluja toteutustehtäviä. Viestien käyttöönotosta vastaavat VRK:n henkilöt tavoittaa osoitteesta viestit-kayttoonotot@vrk.fi. Varsinaisen projektin käynnistäminen edellyttää tapaamista Viestien henkilöstön ja asiakasviraston välillä. Se on välttämätön, jotta voidaan varmistua, että asiakasvirastolla on riittävä tieto Viestit-palvelusta ja sen toiminnasta ja että esim. valittu liityntätapa soveltuu liitettävään palveluun. Samoin haluttu aikataulu on syytä nostaa esiin. Palaveri voidaan sijoittaa myöhempään ajankohtaan esim. jos käyttöluvan saaminen on tärkeintä selvittää ensin tai muusta vastaavasta syystä. On kuitenkin huomattava, että valtiovarainministeriö edellyttää käyttöönoton rahallisen tuen hakemusta jätettäessä, että käyttöönotosta on riittävällä tasolla sovittu VRK:n kanssa.
OHJE 5 (11) 2.1 Käyttöluvan hakeminen Asiakasviraston kannalta Suomi.fi-viestien projekti jakaantuu neljään erilliseen tehtävään: 1 käyttöluvan hakeminen liitettäville palveluille 2 tietoliikenneavausten tekeminen 3 asiakas- ja palvelukohtaisten tietojen määrittely palveluliittymään 4 asiakkaan suorittama testaus Nämä tehtävät eivät ole välttämättä peräkkäisiä vaan niitä voidaan ainakin avausten ja määrittelyjen osalta edistää rinnakkainkin. Samoin testaamiseen voidaan antaa asiakkaalle mahdollisuus vaikka esim. käyttölupaa ei olisi vielä haettu. Käyttölupahakemus tehdään verkkolomakkeella https://esuomi.fi/palveluntarjoajille/viestit/kayttoonotto/. Lomakkeen yhteydessä on sen täyttämiseen liittyviä ohjeita, joihin kannattaa tutustua huolella. Lomakkeessa määritellään palvelu tai palvelut, joiden liittämisen lupaa haetaan. On mahdollista ja jopa suositeltavaa hakea samalla lupaa useammalle palvelulle, vaikka niitä kaikkia ei oltaisi heti teknisesti liittämässä Viestit-palveluun. Palvelujen kuvauksissa on toivottavaa, että noudatettaisiin mahdollisimman tarkoin samaa jaottelua ja nimeämistä, mitä virasto on käyttänyt kuvatessaan palveluja Palvelutietovarantoon. On mahdollista, että käyttölupahakemuksen käsittelijät tekevät lisätiedusteluja hakemuksessa mainitulle yhdyshenkilölle. Päätös käyttöluvasta toimitetaan hakijan mainitsemaan sähköpostiosoitteeseen sekä Viestit-käyttöönotolle. Käyttöluvan saatuaan asiakasvirasto voi itse harkita lähteekö käyttöönoton toteutukseen saman tien tai odottaako myöhempää hetkeä. Käyttöluvan voi siis hakea ns. myöhempää käyttöä varten. 2.2 Tietoliikenneavausten tekeminen Kun päätetään VRK:n ja asiakasviraston välillä käynnistää, tarvitaan ensimmäiseksi tietoliikenneavauksia. Kun liityntätavaksi on valittu sähköposti (SMTP), tarvittavat tiedot voidaan kysyä ja toimittaa sähköpostilla. Tietoliikenteen kannalta riittää tieto viraston sähköposti-domainista sekä sen varmistaminen, että sen ja Viestit-palvelun välille saadaan toteutettua TLS-salattu liikennöinti. Tämä voi edellyttää viestintää VRK:n toimittajan ja asiakasviraston ja mahdollisesti sen it-toimittajan kesken. Yleensä toteutus on nopea ja usein salaustoiminnallisuus on jo valmiina olemassa. Muiden liityntätapojen osalta tarvitaan useampia tietoja sekä varmenteiden vaihtoa. Nämä tehdään excel-pohjaisella lomakkeella VIA_Tietoliikenneavaukset.xls, jonka Viestien toimittaa sähköpostilla asiakasvirastolle. Lomakkeelta löytyvät ohjeet sen täyttämiseen ja palautusosoite. Valtori ja VIA-palvelu kuittaavat avaustoimenpiteet tehdyksi, jonka jälkeen asiakas voi kokeilla yhteyden aukioloa. Kaikentyyppisten avausten keston osalta kannattaa varautua ainakin viikon odotusaikaan.
OHJE 6 (11) 2.3 Asiakas- ja palvelukohtaisten tietojen määrittely palveluliittymään 2.4 Asiakkaan testaus Tietoliikenneavaukset eivät kuitenkaan vielä riitä testausyhteyden saamiseen, vaan tarvitaan itse Viesti-liittymään tehtäviä asiakas- ja palvelukohtaisia määrittelyjä, jotka asiakasorganisaatio täyttää verkkolomakkeella https://esuomi.fi/viestit-palvelun-asiakas-ja-palvelutietolomake. Lomakkeella asiakas mm. ottaa kantaa paluukanavan eli vastausten ja kuittausviestien käyttöön sekä vastausosoitteisiin. Lomake lähettää syötetyt tiedot VRK:n tiketöintijärjestelmään, josta asiakas saa ensin kuittauksen lomakkeen vastaanottamisesta ja myöhemmin määrittelyjen suorittamisesta. Kun määrittelyt on kuitattu tehdyksi, liityntä on periaatteessa valmis testattavaksi. Testaukseen siirryttäessä Viestit- toimittaa asiakkaalle testausohjeen, joka sisältää tarvittavat kohdeosoitteet sekä viestien vastaanottoliittymän osoitteet ja tunnistetiedot. Asiakas suorittaa perustestauksen itse käyttäen omia testitapauksiaan. Jos testauksessa ilmenee testiympäristöön tai tietoliikenteeseen liittyviä ongelmia, asiakas voi pyytää niihin apua viestitkayttoonotot@vrk.fi -osoitteen kautta. Testauksessa käytettäviä testi-henkilötunnuksia löytyy testausohjeesta. Viestien käyttöönotolta voi pyytää niitä tarvittaessa lisää. Tällä hetkellä ei voida viedä testiympäristöön asiakkaan toimittamia hetuja vaan pitää käyttää VRK:n toimittamia hetuja. Kun asiakastestiympäristön testaukset on saatu loppuun, voidaan vielä tehdä asiakkaan haluamassa laajuudessa tuotantoympäristön testauksia. Tuotantoympäristössä ei kuitenkaan ole testihenkilöitä vaan kaikki henkilöt ovat luonnollisia, joten testaus joudutaan käytännössä rajoittamaan perustoimintojen yksinkertaiseen testaamiseen. Tuotantoon siirtymisessä testatun palvelun osalta ei ole erityisiä byrokraattisia kiemuroita vaan asiakas ilmoittaa tuotantoaloituksen ajankohdan Viestit-käyttöönotoille, joka liittää palvelun palveluluetteloon ja ilmoittaa sidosryhmille kuten palvelun ylläpidolle ja käyttäjätuelle tuotannon alkamisesta. Asiakasorganisaation kannattaa suunnitella asiakaskuntansa tiedottaminen itse ja mielellään hyvissä ajoin. 3 Viranomaispalveluiden 3.1 Palveluun liittyminen ja testaaminen VRK tarjoaa Viestit-palvelun mm. WS/SOAP- ja SFTP-palveluina, joiden tietoliikenne kulkee Valtorin VIA-palvelun kautta. Viestit-palveluun voi siis kytkeytyä vain VIA:n kautta. VRK tarjoaa palvelujen kehitykseen testausympäristön ja tuotantoa varten tuotantoympäristön.
OHJE 7 (11) Palveluun liittyminen tapahtuu testausympäristön kautta alla olevan kuvan mukaisesti. Viestit-palvelun viranomaisrajapintojen testaaminen voidaan suorittaa kaksivaiheisesti: ilman sanomien allekirjoitusta ja allekirjoituksen kanssa. Vaiheiden testaaminen on mahdollista tehdä liittymisprosessissa rinnakkaisesti, jolloin integraation toteuttamisen kokonaisaika saadaan minimoitua. Molemmissa testauksen vaiheissa käytettävä Viestit-palvelun testiympäristö on sama ympäristö. Paluukanavan osalta käytetään samaa ympäristöä ja samoja vaiheita. Vaihe 1: testaaminen ilman allekirjoitusta o Kaikkiin WS-kutsusanomiin Viranomainen-elementtiin täytyy täyttää kenttä SanomaVarmenneNimi. Arvon on hyvä olla se sama, joka tulee olemaan myöhemmissä vaiheissa allekirjoitukseen käytettävän varmenteen Common Name (CN). o Käytettävän VIA-rajapinnan osoite (Viranomaispalvelun osalta): https://qat.integraatiopalvelu.fi/asiointitili/viranomaispalvelutwsinterfa cenonsigned IP: 192.49.232.194 Vaihe 2: allekirjoituksen testaaminen ja hyväksymistestaus o Kaikkiin WS-kutsusanomiin Viranomainen-elementtiin täytyy täyttää kenttä SanomaVarmenneNimi. Arvon on oltava sama, kuin mikä on allekirjoitukseen käytettävän varmenteen Common Name (CN). o Käytettävän VIA-rajapinnan osoite (Viranomaispalvelun osalta): https://qat.integraatiopalvelu.fi/asiointitili/viranomaispalvelutwsinterfa ce IP: 192.49.232.194 o Tässä osoitteessa testataan viranomaisjärjestelmän ja VIA:n välillä käytettävän WS-kutsujen allekirjoituksen toimivuus ja suoritetaan hyväksymistestaus integroitavalle järjestelmälle. o Kun asiakasorganisaatio haluaa siirtyä testaamaan allekirjoitettua paluukanavaa, sitä konfiguraatiomuutosta täytyy pyytää Viestit-käyttöönotosta osoitteesta viestit-kayttoonotot@vrk.fi.
OHJE 8 (11) Alla olevassa kuvassa on esitetty, kuinka viranomaisjärjestelmä lähettää sanoman VIA:n kautta Viestit-palvelun Viranomaispalvelut-rajapintaan QA-ympäristössä. Alla olevassa kuvassa on esitetty, kuinka Viestit-palvelu lähettää sanoman VIA:n kautta viranomaisjärjestelmän paluukanava-rajapintaan QA-ympäristössä. Konfiguroinnin muutos pitää pyytää Viestit-käyttöönotosta osoitteesta viestit-kayttoonotot@vrk.fi.
OHJE 9 (11) 3.2 Tuotantoympäristö Tuotantoympäristö on kokonaan erillinen ympäristö, johon kytkeydytään VIA:n PROympäristön kautta. Tuotantoympäristön kokoonpano on esitetty alla. Käytettävän VIA-rajapinnan osoite: https://pr0.integraatiopalvelu.fi:443/asiointitili/viranomaispalvelutwsinterface IP: 192.49.232.195 4 Web Service -tietoliikenteen toteuttaminen 4.1 Palvelinvarmenteet Yhteys VIA:n palvelimiin muodostetaan käyttämällä https-protokollaa. Palvelinten varmenteet ovat saatavilla Valtorin internet-sivuilta osoitteesta: https://valtori.fi/yhteinen-integraatioalustavia-julkiset-varmenteet. 4.2 Kutsujen allekirjoittaminen ja varmenteet Viranomaisjärjestelmän tulee allekirjoittaa lähettämänsä kutsusanomat ja VIA allekirjoittaa vastaavasti paluusanomat. Allekirjoitukset tulee tehdä X509V3 varmenteella jonka on myöntänyt jokin VIA:n hyväksymistä varmentajista. Hyväksyttyjen varmentajien lista, sekä
OHJE 10 (11) varmenteet, joilla VIA allekirjoittaa paluusanomat, ovat saatavilla osoitteessa https://valtori.fi/yhteinen-integraatioalusta-via-julkiset-varmenteet. Allekirjoitusvarmenteina ei voi käyttää domain-varmenteita (CN=*.domain.com). 4.3 Viranomaisjärjestelmästä tarvittavat tiedot Tässä luvussa kuvataan tietoliikenneavauksia varten tarvittavat tiedot viranomaisjärjestelmästä. Viestien henkilöstö VRK:ssa lähettää asiakkaalle VIA_Tietoliikenneavauksetlomakkeen, jonka asiakas palauttaa täytettynä VRK:lle. VRK lähettää lomakkeen edelleen Valtorille, joka suorittaa tietoliikenteen avaamiseen tarvittavat toimet. 4.3.1 Kutsun lähettävien palvelimien osoitteet Asiakas toimittaa VRK:lle VIA_Tietoliikenneavaukset-lomakkeella IP-osoitteet, joista viranomaispalveluiden kutsut tulevat. Tiedot on toimitettava samalla sekä viranomaisjärjestelmän testaus- että tuotantoympäristön osalta. 4.3.2 Viranomaistunnus ja siihen liitettävät raportointitiedot VIA tekee raportointia kutsussa olevan Viranomaistunnus-elementin sisällön perusteella. Viranomaistunnus on VRK:n luoma tunnus, joka liitetään asiakkaan tietoihin VIA:ssa. Viranomaistunnus muotoillaan asiakkaan VIA_Tietoliikenneavaukset-lomakkeelle täyttämästä organisaation nimestä. 4.3.3 Allekirjoitukseen käytetty varmenne Asiakas toimittaa VIA_Tietoliikenneavaukset-lomakkeella viranomaisjärjestelmästään niiden varmenteiden julkiset osat, joilla viranomaisjärjestelmä allekirjoittaa sanomat. Varmenteet on toimitettava sekä viranomaisjärjestelmän testaus- että tuotantoympäristön osalta. 4.4 Paluukanavan 4.4.1 Palvelun rakenne Viranomaisjärjestelmän paluukanavan onnistuu tämän luvun ohjeilla. Viestit-palvelu lähettää paluukanava-rajapinnan mukaisen sanoman viranomaisjärjestelmälle ja välissä toimiva VIA reitittää sen perille viranomaistunnus-elementin sisällön perusteella. VIA olettaa, että viranomaisjärjestelmään on toteutettu palvelu paluukanavan sanomien vastaanotolle, joka noudattaa VRK:lta saatavaa WSDL:ää. VIA allekirjoittaa lähettämänsä paluukanavan sanomat ja viranomaisjärjestelmä allekirjoittaa lähettämänsä vastaussanomat samaan tapaan kuin luvussa 4.2 on kuvattu.
OHJE 11 (11) 4.4.2 Viranomaisjärjestelmän palvelun tiedot Asiakas toimittaa viranomaisjärjestelmän paluukanavasta seuraavat tiedot VRK:lle edellä mainitulla VIA_Tietoliikenneavaukset-lomakkeella: Paluukanavapalvelun osoite, muotoa https://viranomainen.fi/paluukanava Palvelimien nimet ja IP-osoitteet Varmenteiden julkiset osat, joilla viranomaisjärjestelmä allekirjoittaa sanomat. Varmenteet ja osoitteet on toimitettava samalla sekä viranomaisjärjestelmän testi- että tuotantoympäristöjen osalta. Kuten luvussa on kuvattu, on syytä testata ensin allekirjoittamaton paluukanava ja sitten pyytää konfiguroinnin muutosta allekirjoitettuun paluukanavaan.