Tekninen käyttöönotto
Tällä sivulla kerrotaan teknisestä näkökulmasta, mitä vaatimuksia Suomi.fi-viestien käytölle on ja mitä toimenpiteitä Suomi.fi-viestien käyttöönotto pitää sisällään. Voitte lukea lisää käyttöönoton hallinnollisista vaiheista Hallinnollinen käyttöönotto -sivulla.
Huomaattehan, että käyttöönottoprosessi koskee pääasiassa Suomi.fi-viestien REST-rajapintaa. Muiden rajapintojen käyttöönoton vaiheet voivat erota alla kuvatusta.
Lukekaa ensin palvelun esittely Palvelukuvaus-sivulta. Palvelun tarjoamia toiminnallisuuksia käsitellään Toiminnallisuudet -osiossa. Tekninen kuvaus -sivulta voitte lukea lisää siitä, miten Suomi.fi-viestit toimii käytännössä ja mitä rajapintavaihtoehtoja Suomi.fi-viestien käytölle on.
Yleisen tutustumisen lisäksi organisaationne tulee varmistaa, että Suomi.fi-viestien käyttämisen tekniset reunaehdot täyttyvät. Huomioikaa vähintään seuraavat seikat:
- Suomi.fi-viestit ei sisällä käyttöliittymää organisaatioille. Palveluun tarjotaan käyttöliittymiä vain loppukäyttäjille.
- Organisaatiollanne tai valitsemallanne toimittajalla tulee olla viestien lähetykseen kykenevä järjestelmä.
- Liityntänne tulee olla tietoturvallisesti toteutettu. REST-rajapinnassa käytetään tietoturvallisia TLS-protokollan salausalgoritmeja, joille käyttämistänne järjestelmistä tulee löytyä tuki. Tulevaisuudessa edellytämme järjestelmiltä tukea TLS 1.3 ‑salaukselle. Suosittelemme mahdollistamaan TLS 1.3 ‑tuen järjestelmissänne jo nyt.
- Sähköisten viestien lähettämiseksi organisaatiollanne tulee olla tiedossa vastaanottajan henkilö- tai Y-tunnus, jonka avulla viesti kohdennetaan oikeaan sähköiseen postilaatikkoon.
- Paperipostia lähettäessä organisaatiollanne tulee olla tiedossa vastaanottajan osoitetiedot, sillä Suomi.fi-viesteissä ei ole integraatiota väestö- tai yritystietojärjestelmän osoitetietoja sisältävään rekisteriin.
- REST-pyyntöjen autentikaatiossa käytetään autentikaatiotokenia mikä voidaan hakea REST-rajapinnasta organisaation tunnuksella ja salasanalla. Organisaationne väliaikainen salasana tulee vaihtaa ennen käyttöä REST-rajapinnan kutsulla. Salasanan vaihtamiseen suosittelemme automatisoitua säännöllistä prosessia. Autentikaatiotoken vanhenee ja pitää päivittää tarvittaessa.
Mahdolliset yhteydenotot Digi- ja väestötietovirastoon (DVV) hoidetaan osana hallinnollista käyttöönottoprosessia. Osallistukaa tarvittaessa käyttöönottoa käsitteleviin tapaamisiin yhdessä käyttöönoton hallinnosta vastaavien henkilöiden kanssa.
Tunnistakaa järjestelmienne nykytilanne sekä mitä muutoksia tai integraatioita niihin vaaditaan Suomi.fi-viestien käytön aloittamiseksi.
Tukekaa käyttöönoton hallinnosta vastaavia henkilöitä projektin valmistelussa.
Toimittakaa käyttöönoton tekniset tiedot
Toimittakaa käyttöönoton tekniset tiedot, kuten IP-osoitteet, hallinnollisen käyttöönoton tueksi.
Hallinnollisen käyttöönoton vaiheessa, 3. Hakekaa käyttölupaa ja täyttäkää palvelutietolomake, organisaatio ilmoittaa palvelutietolomakkeella testi- ja tuotantoympäristössä käytettävät IP-osoitteet, joiden perusteella DVV tekee tarvittavat IP-avaukset.
Suomi.fi-viestien käyttö on mahdollista vain ennalta ilmoitetuista ja hyväksytyistä IP-osoitteista
Suomi.fi-viestien rajapintojen käyttö edellyttää, että yhteydet muodostetaan organisaation ennalta ilmoittamista IP-osoitteista. Organisaation tulee ilmoittaa käyttöönoton yhteydessä kaikki ne julkiset IP-osoitteet, joista sen liikenne näkyy Suomi.fi-viestien rajapinnoille.
Jos organisaation liikenne kulkee esimerkiksi NAT- tai proxy-palvelimen kautta, ilmoitettava osoite ei tällöin välttämättä ole yksittäisen työaseman tai palvelimen osoite. Suomi.fi-viesteille täytyy ilmoittaa se julkinen IP-osoite, josta liikenne näkyy Suomi.fi-viestien rajapinnoille saapuvana yhteytenä.
Yhteydet sallitaan vain ennalta ilmoitetuille osoitteille. Jos et ole varma, mikä IP-osoite tulee ilmoittaa, tarkista asia oman organisaatiosi verkkoasiantuntijalta tai järjestelmätoimittajalta.
Ilmoita IP-osoitteet erikseen testi- ja tuotantoympäristölle
Testi- ja tuotantoympäristöille ilmoitetaan niiden käyttämät IP-osoitteet erikseen. Testi- ja tuotantoympäristöt kannattaa toteuttaa mahdollisimman samankaltaisesti, jotta testauksessa havaitut toiminnallisuudet vastaavat mahdollisimman hyvin tuotantoympäristöä. Ympäristöt kannattaa kuitenkin toteuttaa mahdollisimman erillisinä, vaikka joissakin tapauksissa ne voivat käyttää samaa julkista IP-osoitetta.
Tarvittaessa voidaan avata myös IP-osoitealueita
Yksittäinen IP-osoite on ensisijainen vaihtoehto. Jos organisaatiolla on käytössä useita lähdeosoitteita, esimerkiksi QA-ympäristössä kehitystä varten, useiden yksittäisten osoitteiden sijaan voidaan avata rajattu IP-osoitealue. Tietoturvasyistä avattavan IP-alueen tulee olla mahdollisimman rajattu. Erittäin laajoja osoitealueita ei yleensä voida hyväksyä.
Suomi.fi-viestien testi- ja tuotantoympäristöissä pyritään rajaamaan hyväksytyt IP-osoitteet ja IP-alueet vain niihin, joista palvelua tosiasiallisesti käytetään.
- Esimerkiksi hyvin laajoja /16-tason osoitealueita ei yleensä voida sallia.
DVV tekee IP-avaukset
Lomakkeiden palauttamisen jälkeen DVV tekee avaukset toimittamillenne IP-osoitteille testi- ja tuotantoympäristöön.
Testiympäristön osoite on api.messages-qa.suomi.fi ja sen käyttöohjeet on kuvattu testiympäristön rajapintadokumentaatiossa https://api.messages-qa.suomi.fi/api-docs Avautuu uuteen ikkunaan.(englanniksi).
Tuotantoympäristön osoite on api.messages.suomi.fi ja sen käyttöohjeet on kuvattu tuotantoympäristön rajapintadokumentaatiossa https://api.messages.suomi.fi/api-docs/Avautuu uuteen ikkunaan. (englanniksi).
Saatte tunnukset
Kun IP-avaukset on tehty, DVV toimittaa salatulla sähköpostilla organisaatiollenne testihenkilötunnukset, järjestelmätunnuksen (systemId), palvelutunnuksen (serviceId) sekä testiympäristön väliaikaisen salasanan.
Testiympäristön käyttöönotto
Vaihtakaa ensin vastaanottamanne väliaikainen salasana organisaationne valitsemaan salasanaan ja varmistakaa sen jälkeen tunnusten toimivuus.
Väliaikainen salasana tulee vaihtaa organisaationne valitsemaan salasanaan seuraavasti:
- Autentikoitukaa saamienne tunnusten avulla testiympäristön token-päätepisteessä. Päätepisteen osoite on api.messages-qa.suomi.fi/v1/token.
- Username on vastaanottamanne järjestelmätunnus (systemId) ja password on vastaanottamanne väliaikainen salasana.
- Päätepiste palauttaa teille autentikaatiotokenin.
- Vaihtakaa väliaikainen salasana haluamaanne salasanaan testiympäristön change-password-päätepisteessä vaiheessa 2. saamanne autentikaatiotokenin avulla. Päätepisteen osoite on api.messages-qa.suomi.fi/v1/change-password.
- Säilökää valitsemanne salasana tietoturvallisesti.
Voitte testata tunnusten toimivuutta näin:
- Autentikoitukaa QA-ympäristön token-päätepisteessä. Päätepisteen osoite on api.messages-qa.suomi.fi/v1/token.
- Username on vastaanottamanne järjestelmätunnus (systemId) ja password on valitsemanne salasana.
- Päätepiste palauttaa teille autentikaatiotokenin.
- Käyttäkää saamaanne autentikaatiotokenia jonkin toisen QA-ympäristön päätepisteen kutsumiseen. Esimerkiksi päätepiste events palauttaa koodin 200, jos tunnukset toimivat.
Nyt pääsette rakentamaan liityntää ja testaamaan sitä testiympäristössä.
Huomaattehan, että kaikkien rajapinnan päätepisteiden käyttö vaatii yllä kuvatulla tavalla saadun autentikaatiotokenin, sekä testiympäristössä että tuotantoympäristössä.
Jos organisaationne haluaa ottaa tulostus-, kuoritus- ja jakelupalvelun (TKJ-palvelu) käyttöön, tutustukaa Hallinnollinen käyttöönotto -sivun kohtaan 3 sekä Tulostus-, kuoritus- ja jakelupalvelun käyttöönotto -sivuun. TKJ-palvelun toimittaja Posti Messaging Oy toimittaa paperipostitukseen tarvittavat tunnukset organisaatiollenne kirjeitse.
Tässä vaiheessa tapahtuu tekninen kehitys.
Toteuttakaa mahdolliset integraatiot tai muutokset omaan asiointijärjestelmäänne organisaationne tekemien määrittelyjen mukaisesti. Jos liitytte valmisohjelmiston välityksellä, huolehtikaa implementaatiosta yhdessä kyseisen ohjelmiston tuottajan kanssa. Tutustukaa teknisiin kuvauksiin Testiympäristön rajapintadokumentaatiossa (api.messages-qa.suomi.fi, englanniksi)Avautuu uuteen ikkunaan..
Suosittelemme, että toteutatte muutokset yksi rajapinta kerrallaan ja testaatte toteutusta jo kehityksen yhteydessä. Lisäksi toteutuksessa kannattaa ottaa huomioon mahdolliset verkkovirheet ja hetkelliset katkot niin, että lähetätte viestin riittävän monta kertaa ja riittävän pitkään uudestaan.
Testausvaiheessa varmistetaan, että Suomi.fi-viestit toimii kokonaisuutena käytössänne kuten pitääkin. Organisaationne tulee testata kaikki liitynnälleen olennaiset testitapaukset ja niiden vaiheet.
Ohjeet erilaisille testitapauksille on koottu Testausohjeet -sivulle. Testaus tehdään käyttämällä Digi- ja väestötietoviraston organisaatiollenne toimittamia testihenkilötunnuksia.
Huomaattehan, että testiympäristöön ei tule lähettää aineistoja, jotka sisältävät henkilötietoja tai salaista tietoa. Testiympäristö on kaikkien yhteisessä käytössä.
Jos teette suorituskykytestausta isolla volyymilla ja teillä on tarvetta suuremmalle määrälle testihenkilötunnuksia tai Y-tunnuksia, tutustukaa suorituskyvyn ohjeisiin ja olkaa tarvittaessa yhteydessä osoitteeseen viestit-kayttoonotot@dvv.fi.
Valmisratkaisuja käytettäessä keskustelkaa toimittajanne kanssa tarvittavasta testauksen laajuudesta. Organisaationne vastuulla on varmistaa liitynnän asianmukainen testaus.
Tukekaa hallinnollista käyttöönottoa tarkistuslistan täyttämisessä. Varmistakaa, että olette huomioineet kaikki käyttöönoton oleelliset asiat tutustumalla tarkistuslistaan huolellisesti. Tarkistuslista löytyy Hallinnollisen käyttöönoton kohdasta 6. Palauttakaa tarkistuslista ja siirtykää tuotantokäyttöön.
Tarkistettuaan organisaation palauttaman tarkistuslistan, DVV toimittaa tuotantoympäristön salasanan tarkistuslistalla ilmoitettuun osoitteeseen.
Salasana tulee vaihtaa change-password päätepisteellä.
- Aikaisemmin vastaanottamanne järjestelmätunnus (systemId) ja palvelutunnus (serviceId) toimivat edelleen myös tuotantoympäristössä.
Tuotantoympäristön osoite on api.messages.suomi.fi. Sen kuvaukset on koottu Tuotantoympäristön rajapintadokumentaatioon (api.messages.suomi.fi, englanniksi)Avautuu uuteen ikkunaan..
Varmistakaa koko palveluputken toimivuus myös tuotantoympäristössä aidolla datalla. Tuotantoympäristössä ette voi enää käyttää testihenkilötunnuksia testien tekemiseen, joten rajoittakaa tuotannon toimivuuden todentaminen välttämättömiin testeihin.
Suomi.fi-viestien tekninen käyttöönotto on nyt valmis.
Voitte aloittaa palvelun käytön tuotantoympäristössä.
Suomi.fi-viestien käyttöön vaadittu tekninen työ ei pääty käyttöönottoon. Organisaationne tulee myös huolehtia liitynnän teknisestä ylläpidosta koko sen elinkaaren ajan.
Suosittelemme vaihtamaan REST-rajapinnan salasanan vähintään puolen vuoden välein, mieluiten useamminkin. Organisaationne kannattaakin automatisoida salasanan vaihto. Tutustukaa tarkempiin ohjeisiin Tekninen ylläpito -sivulla.