Viestit-palvelun viranomaisliittymän ohjelmointiohje. Java-esimerkki

Transkriptio

1 Viestit-palvelun viranomaisliittymän ohjelmointiohje Java-esimerkki

2 V.01 OHJELMOINTIOHJE V (8) DOKUMENTINHALLINTA Omistaja Laatinut Lasse Pynnönen, VRK Valtori/VIA Tarkastanut Hyväksynyt VERSION HALLINTA versionro mitä tehty pvm/henkilö 0.1 Vanhan dokumentin (Digia 2.0, ) tiedot tuotu uudelle pohjalle ja uudelle versioinnille Hannu Korkeala

3 V.01 OHJELMOINTIOHJE V (8) Sisällysluettelo 1 Yleistä Testiympäristö Tarvittavat asennukset ja käännökset (lyhyt ohje) Kuvaus ohjelmasta ja kasausohjeet Ohjelman kääntäminen Ohjelman ajaminen komentotiedostolla Versiohistoria, viittaukset ja termistö Versiohistoria Viittaukset Termistö... 8

4 V.01 OHJELMOINTIOHJE V (8) 1 Yleistä Tämä dokumentti on tarkoitettu helpottamaan liittymistä viestit-palveluun, sen tarjoamien viranomaisrajapintojen kautta. Esimerkki on mahdollisimman yksinkertainen, Javalla toteutettu client ja sen oleellisin osa on allekirjoituksen luominen lähetettävään viestiin. Esimerkkiä voidaan käyttää myös testiviestien lähettämiseen Valtorin integraatiotestiympäristöön. Javan lisäksi ei muille ohjelmointikielille toistaiseksi ole tehty vastaavaa esimerkkiä! Ohjeistus on tarkoitettu tekniselle henkilölle, joka on toteuttanut integraatioita aiemmin, tuntee tekniset peruskäsitteet sekä yleisesti käytetyt työkalut. Ohjeistus ei opasta yksityiskohtaisesti jokaista tarvittavaa tehtävää. Itse viestit-palveluun liittymisestä löytyy tietoa esuomi.fi -sivustolta (viite 1). Lähetettäessä SOAP sanomia VIA palveluväylän kautta viestit-palvelun rajapintoihin, tulee lähetettyjen sanomien olla oikein allekirjoitettuja. Allekirjoitus tehdään käyttämällä WS-Security Signaturea, jossa on sekä Body, että Timestamp -osan allekirjoitus. Ilman allekirjoitusta olevat, väärin muodostetut, tai vanhentuneet allekirjoitukset hylätään ja viestien lähetys ei onnistu. Tätä ohjetta ja esimerkkiä voidaan käyttää sellaisenaan kokeilemaan, että yhteys ja allekirjoituksen muodostus VIA suuntaan onnistuu. Tässä ohjeessa ei kuitenkaan oteta kantaa viestien sisältöön tai tekniseen ympäristöön (VIA, Viestit) eikä palvelun osoitteisiin, vaan ne on kuvattu esuomi.fi -sivustolla sijaitsevissa muissa dokumenteissa (viite 1). On huomioitavaa, että viestin lähetyksen epäonnistuminen voi olla myös jokin muu kuin tekninen ongelma, esim. viestin sisältöön liittyvä (lähetetään viestiä esim. päällekkäisellä tunnisteella tai väärällä viranomaistunnuksella). Esimerkkitoteutus on purettavissa oleva zip-tiedosto nimeltä: ViestitWSClient.zip 2 Testiympäristö Esimerkkisovellus on toteutettu ja testattu seuraavanlaisessa ympäristössä: Käyttöjärjestelmä Windows 10, 64-bit (testattu myös CentOS 7 Linux 64- bit) Java (TM) SE Runtime Environment (build 1.8.0), 64-bit

5 V.01 OHJELMOINTIOHJE V (8) 3 Tarvittavat asennukset ja käännökset (lyhyt ohje) ViestitWSClientExample kasataan ja testataan mavenilla. Ennen kasaamista: Varmista että käytössäsi on Java 7 tai 8 versio ja JAVA_HOME viittaa ko. versioon. Varmista että käytössäsi on Apache Maven tai uudempi, se on asennettu oikein ja vastaa komentoriviltä käskyyn mvn. Pura ViestitClientExample.zip valitsemaasi hakemistoon ja avaa command prompt / terminaali ko. hakemistoon. Pura zip, mene hakemistoon ViestitWSClientExample ja anna käsky: mvn clean install: C:\temp\ViestitWSClientExample>mvn clean install Jos kaikki menee ok, lopuksi tulee seuraavan tyyppinen viesti: [INFO] [INFO] BUILD SUCCESS [INFO] [INFO] Total time: s [INFO] Finished at: T06:05:05Z [INFO] Jos ensimmäinen clean install epäonnistuu, aja perään mvn install. Käännösvirheiden sattuessa tms. tarkista ensin, että kaikki java ja maven konfiguraatiot ovat kunnossa. Voit myös kokeilla testiviestin lähettämistä ajamalla esim../sendhaeasiakkaita.sh (Windowsissa.bat -pääte). Katso lisää kohdasta 4.

6 V.01 OHJELMOINTIOHJE V (8) 4 Kuvaus ohjelmasta ja kasausohjeet Ohjelman lähdekoodit ovat tiedostossa: ViestitWSClientExample.zip Avaa komentotulkki / terminaali ja pura unzipilla asennuspaketti tyhjään hakemistoon: c: cd \ mkdir Esim cd Esim unzip ViestitWSClientExample.zip cd ViestitWSClientExample 4.1 Ohjelman kääntäminen Ohjelma käännetään mavenilla: mvn clean install Kääntämisen yhteydessä ajetaan junit -testi, joka testaa vain signaturen muodostamista. Toinen junit -testi lähettää testiviestin IT1-ympäristöön. Katso com.st.example.tests.signtest.java testappjustsigning() ja testappcallserviceit1(). Nykyinen ohjelmaversio lukee arvoja System-properteista. Halutessasi voit myös käyttää crypto.properties tiedostoa. Sen käyttö pitää aktivoida erikseen koodista. Kutsuosoitetta voit halutessasi muuttaa editoimalla tiedostoa ViranomaispalvelutWSInterface.wsdl (xml -resources haarassa) ja suorittamalla uudelleenkäännöksen. Muista myös lisätä osoitteet saataville esim. hosts -tiedostoon ja varmistaa että yhteys VIA palveluun toimii, jotta lähetys on mahdollista. Tarvittaessa lisää myös sertifikaatti Javan käyttämään TrustStoreen (esim. cacerts). VIA palauttama vastaussanoma tulostuu putkelle. Paluusanomat on kuvattu esuomi.fi -sivustolla. Koodi jossa viestin muodostus (allekirjoitus) tehdään on sijoitettu luokkaan com.st.example.test.testclient ja on sieltä vapaasti kopioitavissa omiin tarpeisiin. Oleellista on, että allekirjoitus suoritetaan Body ja Timestamp osille. Muodostettava viesti voi kohdistua myös muihin operaatioihin (viranomaispalveluissa tai paluukanavassa), kunhan lahetaviesti = false. Ohjelma muodostaa allekirjoituksen myös näille muille operaatioille, mutta lähetys on toteutettu vain viranomaispalveluihin.

7 V.01 OHJELMOINTIOHJE V (8) 4.2 Ohjelman ajaminen komentotiedostolla HaeTilatieto-sanoman ajo it1-ympäristöön:./sendhaetilatieto.sh Komentotiedostosta näkee ohjelman parametrit: java -Djavax.net.debug= -Djavax.net.ssl.trustStore=./trust.jks -Djavax.net.ssl.keyStore=./id.jks -Dsigner.username=vvptestid -Dsigner.password=changeit -DlahetaViesti=true -jar target/viestitwsclientexample-1.0-snapshot-jar-with-dependencies.jar./examplemessage_haetilatieto.txt $1 Java system property-määritykset -Djavax.net.ssl.trustStore=./trust.jks on luottamus-keystore. -Djavax.net.ssl.keyStore=./id.jks on identity-keystore -Dsigner.username=vvptestid identity alias -Dsigner.password=changeit identityn salasana -DlahetaViesti=true (true=lahettää viestin false=ainostaan allekirjoitus) Ohjelman parametrit: -./examplemessage_haetilatieto.txt allekirjoitettava ja lähetettävä kutsu - URL kutsun osoite. Oletuksena IT1 -ympäristö, jolloin URI on raatiopalvelu.fi/asiointitilivvp/integraatiotesti/viranomaispalvelutwsinterface- Vaka Ohjelman ajoon on neljä eri komentotiedostoa: sendhaetilatieto.sh sendhaetilatietodebug.sh sendhaeasiakkaita.sh sendlisaakohteita.sh Komentotiedostossa sendhaetilatietodebug.sh on aktivoituna tls debug: -Djavax.net.debug=ssl:record:plaintext, jolla näkee tls-kättelyn sujumisen.

8 V.01 OHJELMOINTIOHJE V (8) 5 Versiohistoria, viittaukset ja termistö 5.1 Versiohistoria Versio Päiväys Tila Tekijä Kuvaus Draft TR, Digia Päivitetty 1.1 versio Draft TR Digia Testattu pakettia ja ohjetta Ehdotus TR, HP Digia Ehdotettu versio Valmis TR, digia Valmis versio 5.2 Viittaukset 5.3 Termistö 1) esuomi.fi sivusto: Liityntätyypit, Käyttöönotto, Tekninen aineisto Lyhenne/termi VIA Viestit -palvelu Viranomaisrajapinta Kuvaus Valtion yhteinen integraatiopalvelu Suomi.fi-viestit on julkishallinnon organisaatioiden keskitetty viestioperaattoripalvelu kansalaisille ja yrityksille. SOAP-rajapinta viranomaisviestien lähetykseen kansalaisille