Tekniskt ibruktagande

Läs först presentationen av tjänsten på sidan Tjänstebeskrivning. De funktioner som tjänsten erbjuder behandlas i avsnittet Funktioner. På sidan Teknisk beskrivning kan ni läsa mer om hur Suomi.fi-meddelanden fungerar i praktiken och vilka gränssnittsalternativ det finns för att använda Suomi.fi-meddelanden.

Utöver den allmänna introduktionen ska er organisation säkerställa att de tekniska ramvillkoren för användningen av Suomi.fi-meddelanden uppfylls. Observera åtminstone följande:

• Suomi.fi-meddelanden innehåller inget användargränssnitt för organisationer. Endast slutanvändare erbjuds gränssnitt till tjänsten.
• Er organisation eller den leverantör ni valt ska ha ett system som kan skicka meddelanden.
• Er koppling ska vara implementerad på ett informationssäkert sätt. I REST-gränssnittet används informationssäkra krypteringsalgoritmer enligt TLS-protokollet, för vilka stöd måste finnas i de system ni använder. I framtiden kommer vi att kräva stöd för TLS 1.3-kryptering i systemen. Vi rekommenderar att ni möjliggör stöd för TLS 1.3 i era system redan nu.
• För att skicka ett elektroniskt meddelande ska er organisation känna till mottagarens personbeteckning eller FO-nummer, som används för att rikta meddelandet till rätt elektroniska brevlåda.
• När ni skickar papperspost ska er organisation känna till mottagarens adressuppgifter, eftersom det inte finns någon integration i Suomi.fi-meddelanden i befolknings- eller företagsdatasystemets register som innehåller adressuppgifter.
• Autentisering av REST-anrop sker via en autentiseringstoken som kan erhållas från REST-gränssnittet med er organisations inloggningsuppgifter (användarnamn och lösenord). Det tillfälliga lösenord som er organisation tilldelas ska bytas innan användning av REST-gränssnittet. Vi rekommenderar att lösenordsbytet automatiseras via en regelbunden process. Autentiseringstokenet har en begränsad giltighetstid och måste uppdateras vid behov.

Eventuella kontakter till Myndigheten för digitalisering och befolkningsdata sköts som en del av den administrativa ibruktagningsprocessen. Delta vid behov i möten om ibruktagning tillsammans med de personer som ansvarar för administrationen av ibruktagandet.

Identifiera systemens nuläge samt vilka ändringar eller integrationer som krävs för att börja använda Suomi.fi-meddelanden.

Stöd dem som ansvarar för administrationen av ibruktagandet i projektberedningen.

Lämna tekniska uppgifter för ibruktagandet

Lämna in de tekniska uppgifter som behövs för ibruktagandet, såsom IP-adresser, som stöd för det Administrativt ibruktagande.

I steg 3 i det administrativa ibruktagandet, Ansök om användningstillstånd och fyll i serviceuppgiftsblanketten, anger organisationen på serviceuppgiftsblanketten de IP-adresser som används i test- och produktionsmiljön. Utifrån dessa uppgifter gör Myndigheten för digitalisering och befolkningsdata de nödvändiga IP-öppningarna.

Användningen av Suomi.fi-meddelanden är möjlig endast från IP-adresser som anmälts i förväg och godkänts

Användningen av gränssnitten för Suomi.fi-meddelanden förutsätter att anslutningarna upprättas från IP-adresser som organisationen har anmält i förväg. Organisationen ska i samband med ibruktagandet anmäla alla offentliga IP-adresser från vilka trafiken syns för gränssnitten i Suomi.fi-meddelanden.

Om organisationens trafik till exempel går via en NAT- eller proxyserver är den IP-adress som ska anmälas inte nödvändigtvis adressen för en enskild arbetsstation eller server. Till Suomi.fi-meddelanden ska den offentliga IP-adress anmälas från vilken trafiken syns som inkommande anslutningar till gränssnitten för Suomi.fi-meddelanden.

Anslutningar tillåts endast från adresser som anmälts i förväg. Om du är osäker på vilken IP-adress som ska anmälas, kontrollera saken med den egna organisationens nätverksexpert eller systemleverantör.

Anmäl IP-adresserna separat för test- och produktionsmiljön

De IP-adresser som används i test- respektive produktionsmiljön ska anmälas separat. Det rekommenderas att test- och produktionsmiljöerna genomförs så likartat som möjligt, så att de funktioner som observeras vid testningen motsvarar produktionsmiljön så väl som möjligt. Miljöerna bör dock hållas så separata som möjligt, även om de i vissa fall kan använda samma offentliga IP-adress.

Vid behov kan även IP-adressintervall öppnas

En enskild IP-adress är det primära alternativet. Om organisationen använder flera källadresser, till exempel i en testmiljö för utvecklingsändamål, kan ett begränsat IP-adressintervall öppnas i stället för flera enskilda adresser.
Obs! Av informationssäkerhetsskäl ska det IP-intervall som öppnas vara så begränsat som möjligt. Mycket omfattande adressintervall kan i regel inte godkännas.

I test- och produktionsmiljöerna för Suomi.fi-meddelanden eftersträvas att begränsa godkända IP-adresser och IP-intervall till endast de adresser från vilka tjänsten faktiskt används.

• Till exempel kan mycket omfattande adressintervall på /16-nivå i regel inte tillåtas.

DVV gör IP-öppningarna

Efter att blanketterna har lämnats in, öppnar MDB test- och produktionsmiljön för de IP-adresser ni skickat.

Testmiljöns adress är api.messages-qa.suomi.fi och dess bruksanvisningar beskrivs i Testmiljöns gränssnittsdokumentation (api.messages-qa.suomi.fi, på engelska)Öppnas i ett nytt fönster..

Produktionsmiljöns adress är api.messages.suomi.fi och dess bruksanvisningar beskrivs i produktionsmiljöns gränssnittsdokumentation (api.messages.suomi.fi, på engelska)Öppnas i ett nytt fönster..

Ni får behörigheterna

När IP-öppningarna har gjorts skickar MDB testpersonbeteckningar, systemkod (systemId), servicekod (serviceId) och testmiljöns tillfälliga lösenord till er organisation via krypterad e-post.

Ta testmiljön i bruk

Byt först det tillfälliga lösenord ni fått till ett lösenord som organisationen själv väljer och säkerställ därefter att behörigheterna fungerar.

Det tillfälliga lösenordet ska bytas till det lösenord som er organisation valt på följande sätt:

1. Autentisera testmiljön token-slutpunkten med hjälp av de koder ni fått. Slutpunktens adress är api.messages-qa.suomi.fi/v1/token. Username är den systemkod (systemId) som ni tagit emot och password är det tillfälliga lösenord ni tagit emot.
2. Slutpunkten returnerar autentiseringstokenen till er.
3. Byt det tillfälliga lösenordet till önskat lösenord vid testmiljöns change-password-slutpunkt i fas 2 med hjälp av den autentiseringstoken ni fått. Slutpunktens adress är api.messages-qa.suomi.fi/v1/change-password.
4. Förvara det lösenord ni valt på ett datasäkert sätt.

Ni kan testa att ert lösenord fungerar så här:

1. Autentisera QA-miljön på token-slutpunkten. Slutpunktens adress är api.messages-qa.suomi.fi/v1/token. Username är den systemkod (systemId) som ni tagit emot och password är det lösenord ni valt.
2. Slutpunkten returnerar autentiseringstokenen till er.
3. Använd den autentiseringstoken ni fått för att anropa någon annan slutpunkt i QA-miljön. Till exempel slutpunkten events returnerar koden 200 om koderna fungerar.

Nu kan ni bygga anslutningen och testa den i testmiljön.

Observera att användningen av alla slutpunkter i gränssnittet kräver autentiseringstoken som erhållits på det sätt som beskrivs ovan, både i testmiljön och i produktionsmiljön.

Om er organisation vill ta i bruk utskrifts-, kuverterings- och distributionstjänsten (TKJ-tjänsten), bekanta er med punkt 3 på sidan Administrativt ibruktagande samt sidan Ibruktagande av utskrifts-, kuverterings- och distributionstjänsten. Leverantören av utskrifts-, kuverterings- och distributionstjänsten Posti Messaging Oy skickar de användarnamn som behövs för papperspost till er organisation per brev.

I det här skedet sker själva den tekniska utvecklingen.

Genomför eventuella integrationer eller ändringar i ert eget ärendehanteringssystem enligt de specifikationer som er organisation gjort. Om ni ansluter er via ett färdigprogram, se till implementeringen tillsammans med programproducenten i fråga. Bekanta er med de tekniska beskrivningarna i Testmiljöns gränssnittsdokumentation (api.messages-qa.suomi.fi, på engelska)Öppnas i ett nytt fönster..

Vi rekommenderar att ni genomför ändringarna ett gränssnitt i taget och testar genomförandet redan i samband med utvecklingen. Dessutom lönar det sig att beakta eventuella nätfel och tillfälliga avbrott i genomförandet så att ni skickar meddelandet tillräckligt många gånger och tillräckligt länge på nytt.

I testfasen säkerställs att Suomi.fi-meddelanden fungerar som helhet i er användning. Er organisation ska testa alla testfall och deras faser som är väsentliga för anslutningen.

På sidan Testanvisningar finns anvisningar för olika testfall. Testningen görs genom att använda de testpersonbeteckningar som Myndigheten för digitalisering och befolkningsdata har levererat till er organisation.

Observera att material som innehåller personuppgifter eller sekretessbelagd information inte ska skickas till testmiljön. Testmiljön är gemensam för samtliga.

Om ni utför prestationstest med stor volym och har behov av ett större antal testpersonbeteckningar eller FO-nummer, kontakta viestit-kayttoonotot@dvv.fi.

När ni använder färdiga lösningar ska ni diskutera omfattningen av den testning som behövs med er leverantör. Er organisation ansvarar för att säkerställa att anslutningen testas på behörigt sätt.

Stöd det administrativa ibruktagandet genom att hjälpa till att fylla i checklistan. Säkerställ att ni har beaktat alla väsentliga faktorer i ibruktagandet genom att noggrant gå igenom checklistan. Checklistan finns på sidan Administrativt ibruktagande under punkt 6. Lämna in checklistan och gå över till produktionsbruk.

Efter att ha granskat den checklista som organisationen lämnat in skickar MDB lösenordet till produktionsmiljön till den adress som angetts i checklistan.

Lösenordet ska bytas ut via slutpunkten change-password.

• Den systemkod (systemId) och servicekod (serviceId) ni tidigare tagit emot fungerar fortfarande även i produktionsmiljön.

Produktionsmiljöns adress är api.messages.suomi.fi. Beskrivningarna har sammanställts i produktionsmiljöns gränssnittsdokumentation (api.messages.suomi.fi, på engelska)Öppnas i ett nytt fönster..

Säkerställ att hela servicelinjen fungerar även i produktionsmiljön med äkta data. I produktionsmiljön kan ni inte längre använda testpersonbeteckningar för att utföra tester, så begränsa verifieringen av produktionens funktion till nödvändiga tester.

Det tekniska ibruktagandet av Suomi.fi-meddelanden är nu klart.

Ni kan börja använda tjänsten i produktionsmiljön.

Det tekniska arbete som krävs för att använda Suomi.fi-meddelanden avslutas inte med ibruktagandet. Er organisation ska också sörja för det tekniska underhållet av anslutningen under hela dess livscykel.

Vi rekommenderar att er organisation byter lösenordet för REST-gränssnittet minst var sjätte månad, helst oftare. Vi rekommenderar därför att ni automatiserar lösenordsbytet. Bekanta er med närmare anvisningar på sidan Tekniskt underhåll.