Kysymyksiä ja vastauksia varmennepalvelusta

Tekniset kysymykset varmenteesta

Mitä y-tunnusta ja asiakasnimeä käytetään kohdassa GetCertificateRequest?

Ohessa esimerkki tästä kohdasta ja vastaus CustomerID:n kohdalla:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cer="http://certificates.vero.fi/2017/10/certificateservices">

<soapenv:Header/>

<soapenv:Body>

<cer:GetCertificateRequest>

<Environment>TEST</Environment>

<CustomerId>Tulorekisterin testaussopimus käsitelty viestin keinotekoinen y-tunnus</CustomerId>

<!--Optional:-->

<CustomerName>Tulorekisterin testaussopimus käsitelty viestin keinotekoinen asiakasnimi</CustomerName>

<RetrievalId>varmennepalvelusta saatu RetrivalId</RetrievalId>

</cer:GetCertificateRequest>

</soapenv:Body>

</soapenv:Envelope>

Suoritetaanko CSR:n (varmenteen allekirjoituspyynnön) sisältämille arvoille kuten common namelle tarkistuksia? Onko niille asetettu rajoitteita, esimerkiksi pitääkö CSR:n sisältämien tietojen olla varmennetta uusittaessa samat kuin alkuperäisessä varmenteessa, tai tuleeko näiden tietojen jollain tapaa vastata varmennetta hakevan yrityksen tietoja?

CSR:ää käytetään teknisesti vain julkisen avaimen toimittamiseen. Sen eheys tarkistetaan, mutta varsinaisia tietokenttiä ei hyödynnetä varmenteella. Tietojen käyttö muussa yhteydessä, kuten vianselvityksessä ei ole suljettu pois, joten olisi hyvä täyttää oikeat tiedot.

Mitkä ovat varmenteen allekirjoituspyynnön tiedot?

Varmenteen allekirjoituspyynnön (CSR) muodostamisvaiheessa kysytään varmennetta hakevan organisaation (Subject) tietoja. Näistä tiedoista kannattaa allekirjoituspyyntöön täyttää seuraavat organisaation tiedot:

  • Common Name (CN), merkitse keinotekoinen Y-tunnus
  • Organization (O), merkitse annettu asiakasyrityksen nimi
  • Country (C), merkitse FI

Tuotannossa käytetään yrityksen omia tietoja, testiympäristössä käytetään yritykselle annetun testiorganisaation tietoja.

Miksi saan virheilmoituksen tunnistautuessa? Käytössä on ladattu sertifikaatti (21.3.2018)

Pyynnöt näyttävät pysähtyvän XML-allekirjoituksen tarkistukseen. Myös aineistolle tehdään tarkistuksia, joten niistäkin tulisi virhe tuon jälkeen.

Pyynnössä olevat datat (ainakin CreatorId ja SenderId) kannattaa muuttaa vastaamaan varmenteessa olevaa Y-tunnusta.

XML-allekirjoituksen teosta on saatu toimivia ratkaisua, jotka ovat ohjeessa kuvatun käytännön mukaisia. Yksi ratkaisu on ollut toteuttaa Web Service -toteutukseen käsittelijä, joka juuri ennen kutsun lähtemistä suorittaa XML-allekirjoituksen toteutuksen.

Allekirjoituksen toteutus pääpiirteissään:

  • lue Soap-viestin sisältä Bodyn ensimmäinen lapsielementti ja muodosta siitä uusi XML-dokumentti
  • muodosta tästä uudesta dokumentista XML-allekirjoitus dokumentaation mukaisesti varmenteeseen liittyvällä avaimella
  • korvaa envelopen sisällä ollut Bodyn ensimmäinen lapsielementti tällä allekirjoitetulla versiolla siitä
  • muut mahdolliset ohjelmistokirjaston vaatimat toimenpiteet lähtevän viestin korvaamiseksi tällä allekirjoitetulla.

Miten tehdään CSR tiedon liittäminen signNewCertificate-operaatioon?

CertificateRequest-elementissä oleva base64-enkoodattu varmenteen allekirjoituspyyntö (CSR) syötettävä ilman alku- ja lopputageja:

-----BEGIN CERTIFICATE REQUEST-----
base64 enkoodattu CSR-----
END CERTIFICATE REQUEST-----

Miten tallennetaan getCertificate-operaatiosta saatu varmenne tiedostoon?

Mikäli vastaussanomassa saatava varmenne talletetaan manuaalisesti tiedostoon, tulee Certificate-elementissä oleva base64-enkoodattuun tietoon lisätä alku- ja lopputagit omille riveilleen, siten että varmenteen tieto jää niiden väliin:

-----BEGIN CERTIFICATE-----
base64 encoodattu varmenne
-----END CERTIFICATE-----

Miksi Web Service -palveluita käytettäessä tulee SSLHandshakeException-poikkeus (tulorekisterin ja varmennepalvelun rajapinta)?

Ongelma liittyy todennäköisesti asiakasohjelmiston käyttämään TLS/SSL-versioon ja niihin liittyviin kryptokirjastoihin. Tulorekisterin ja varmennepalvelun Web Service -rajapinnat käyttävät TLSv1.2:n mukaista protokollaa ja asiakasohjelmiston tulee käyttää samaa versiota. Tiedossa olevat ongelmat: 

  1. Java 7 ja sitä vanhemmat versiot → Päivitä käyttöön Java 8 tai uudempi.
  2. SoapUI OpenSource, versio 5.3.0 ja sitä vanhemmat käyttävät vanhentunutta Java-versiota. → Päivitä SoapUI versioon 5.4.0 tai päivitä/korvaa SoapUI:n paketoima Java versioon 8.

Mikä on varmennepalvelun osoite sidosryhmätestiympäristössä ja mihin palvelukutsut toimitetaan?

  • Dynaamisen WSDL:n voi noutaa osoitteesta https://pkiws-testi.vero.fi/2017/10/CertificateServices.wsdl
  • Sama WSDL ja XML skeemat on ladattavissa myös tulorekisterin sivustolta
  • Kun käytetään rajapintaa varmenteen hakuun, palvelun kutsut tulee lähettää osoitteeseen https://pkiws-testi.vero.fi/2017/10/CertificateServices

    – Tämä palvelun kutsu tulee tehdä HTTP POST -metodia käyttäen ja lisäksi tulee asettaa seuraavat HTTP-otsakkeet (headers)

    – Content-Type: text/xml;charset=UTF-8

    – SOAPAction: "getCertificate"

  • SOAPAction tulee olla kyseisen operaation action ja ne löytyvät WSDL-kuvauksesta.
    - SOAP-viestejä ei tyypillisesti voi lähettää nettiselaimella, ainakaan ilman lisäkkeitä (extensions ja plugins) vaan siihen tulee käyttää jotain SOAP-viestien lähettämiseen kykenevää ohjelmaa.

Mikä on SFTP-kanavan osoite? (21.3.2018)

Osoite on 131.207.14.21 ja se löytyy myös nimipalvelusta nimellä sftp-testi.tulorekisteri.fi, tuotannon osoite tulee olemaan sftp.tulorekisteri.fi.

Miten tunnistaudun SFTP-kanavassa? (3.4.2018)

SFTP-käyttäjätunnuksen muoto on esimerkiksi 0ac1ee931da7cf1ce_PW. Käyttäjätunnus lähetetään testauksen yhteyshenkilölle ja tekniselle yhteyshenkilölle sähköpostilla, kun testaava taho on noutanut testivarmenteen. SFTP-kanavassa tunnistautuminen tapahtuu SSH-autentikoinnilla siten, että käytetään käyttäjätunnusta sekä yksityistä avainta siitä avainparista, jota sidosryhmä on käyttänyt varmenteen allekirjoituspyynnön (CSR) allekirjoittamisessa. Salasanaa ei siis käytetä.

Mitkä ovat oikeat attribuutit signature-noodin käyttämisessä? (21.3.2018)

<CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />

<SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" />

<Reference URI="">

<Transforms>

<Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />

<Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />

</Transforms>

<DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />

Pitääkö uuden sertifikaatin luontia varten muodostaa jokaiselle asiakkaalle oma julkinen avain, yksityinen avain sekä PCKS#10-varmennepyyntö erikseen? Eikö riitä, että olisi vain yksi yhteinen julkinen/yksityinen avain sekä PCKS#10-varmennepyyntötiedosto, jota käytettäisiin kaikille asiakkuuksille? Tällöin asiakkaalle toimittamanne siirtotunnus ja kertakäyttösalasana riittäisivät asiakkuuden yksilöimiseen uuden varmenteen noutotunnuksen ja XML-allekirjoituksenne muodostamiseksi. (21.3.2018)

Jos kyseessä on tilitoimisto, niin tilitoimisto voi toimia omalla varmenteellaan ja muodostaa aineistot sekä ilmoittaa tiedot asiakkaiden puolesta. Jos kyse on puhtaasti aineistojen välittämisestä, niin kullekin asiakkaalle tulee muodostaa oma avainpari sekä varmenteen allekirjoituspyyntö, joista sitten muodostetaan varmenteet.

Onko teillä käytännön esimerkkiä / työkalua avainparin muodostamiseksi ja PCKS#10-varmennetiedoston luomiseksi ja julkisen avaimen liittämistä siihen? (21.3.2018)

Pyrimme julkaisemaan ohjeistuksen asiaan liittyen mahdollisimman pian.

Miten asiakkaiden omia julkisia/yksityisiä avaimia ja PCKS#10-varmennetiedostoja kannattaisi hallinnoida? (21.3.2018)

Hallinnointi on hyvin järjestelmä- ja ympäristökohtaista, asiakaskohtaisia ohjeita on hankala antaa. Hyvä idea on, että järjestelmää hallinnoiva taho on se, joka tekee avainparit ja varmenteen allekirjoituspyynnöt ja hallinnoi myös varmenteita.

Joko tämä testipenkin osoite https://pkiws-testi.vero.fi/DEV/2017/10/CertificateServices toimii? (11.5.2018)

Testipenkki on toiminnassa. Testipenkin rajapintaa käytetään kuten varmennepalvelun rajapintaa. Rajapinnan kutsu tulee tehdä siis käyttäen HTTP POST -metodia. Testipenkkipalvelun WSDL:n voi noutaa GET-metodilla osoitteesta https://pkiws-testi.vero.fi/DEV/2017/10/CertificateServices.wsdl

Varmenteen nouto

Kun noudetaan pyydettyä tai uusittua varmennetta GetCertificateRequest-pyynnöllä, ei saaduissa vastauksen virhekoodeissa vaikuta olevan koodia tilanteelle, jossa varmenteen luontipyyntö on vielä käsiteltävänä. (Varmennepalvelun yleiskuvauksen kuva 2 mainitsee käsittelyajan). Onko tälle tulossa jokin virhekoodi kuten ”varmennepyyntö käsiteltävänä”?

Tämä on vielä harkinnassa tuotantoympäristöön, mutta tällä hetkellä erillistä virhekoodia ei ole.

Mikä on käsittelyaika, kun noudetaan pyydettyä tai uusittua varmennetta GetCertificateRequest-pyynnöllä?

Dokumentaatiossa on määritelty varoaika 5 minuutiksi, mutta käytännössä aika on alle 30 sekuntia. Usein aika on selkeästi lyhyempi.

Miksi varmenteen nouto epäonnistuu?

Varmenteen nouto voi epäonnistua esimerkiksi väärän noutotunnuksen vuoksi (RetrievalId).

Varmenteen hakemisessa on otettava huomioon, että allekirjoituspyynnön (SignNewCertificate) saa tehdä siirtotunnuksilla (TransferId ja TransferPassword) vain yhden kerran. Varmenteen noudon (GetCertificate) voi tehdä samalla noutotunnuksella (RetrievalId) useita kertoja. Allekirjoituspyynnön ja noudon välillä on viive eli kannattaa odottaa jonkin aikaa.

Miten voin saada toisen henkilön tekniseksi yhteyshenkilöksi? Onko tarpeen tehdä uusi sopimus? (9.4.2018)

Uutta sopimusta ei tarvita, alkuperäisen sopimuksen allekirjoittanut henkilö voi ilmoittaa muutoksesta sähköpostilla osoitteeseen YHT_Tulorekisteri_testaus@vero.fi.

Jos varmennetta ei ehditä noutamaan kahden viikon kuluessa voiko hakuaikaa jatkaa? (9.4.2018)

Hakuaikaa ei voi jatkaa, mutta voidaan tehdä uusi varmennetilaus. Ilmoitus havaintolomakkeella. 

Tämän hetkistä testivarmennetta ei pysty yhdistämään privaattiavaimen kanssa. Onko mahdollista poistaa nykyinen testisertifikaatti ja tehdä varmennepyyntö uudestaan? (9.4.2018)

Testisertifikaattia ei ole mahdollista poistaa, mutta voidaan tehdä uusi varmennetilaus, jolloin saa siirtotunnukset uuden varmennepyynnön tekemistä varten. 

Olen saanut sähköpostiviestin, jossa on liitteenä linkki verkkosivuille, jonne minun tulisi antaa Pin-koodi. Tajusin, että ehkä puhelinnumeroni on väärin, jos se on muotoa 420 xxx xxx xxx. Valintanumero Tsekkiin on +420 tai 00420. Lähetin teille ilmoituksen myös verkkosivun kautta, mutta en voinut kirjoittaa mitään viestiä. Voisitteko korjata puhelinnumeroni 0042 xxx xxx xxx, jotta voin vastaanottaa Pin-koodin? (9.4.2018)

Puhelinnumero oli oikeassa muodossa, mutta kyseinen ulkomaalainen operaattori oli kieltänyt vastaanottamasta lähetettyä viestiä, mikä ilmeisesti johtuu siitä, että viesti ei tule tavallisesta puhelinnumerosta, vaan lähetyspalvelusta.

Mikäli havaitsette ongelmia turvasähköpostiviestissä tai SMS-viesteissä niin ottakaa yhteyttä havaintolomakkeella.

Työnantajan erillisilmoitus -dokumentaatiossa on työeläkelaitoksen yhtiötunnuksen kohdalla teksti: Tiedon on oltava sama kuin Eläkejärjestelynumero-tiedon kaksi ensimmäistä merkkiä. Kuitenkin koodistossa osa työeläkeyhtiöiden tunnuksista alkaa 5-merkkisellä tunnuksella. 

Jos tiedon on oltava yhtä aikaa koodiston mukainen PensionProvldCode sekä yhtenevä eläkejärjestelynumeron kahden ensimmäisen merkin kanssa, miten tällaisten viisimerkkisten koodien kanssa edetään? (9.4.2018)

Tässä on jäänyt päivittämättä työnantajan erillisilmoituksen dokumentaatio tältä osin. Palkkatietoilmoituksen skeemakuvauksessa sama kohta on kuvattu näin: Tiedon on oltava sama kuin Eläkejärjestelynumero-tiedon kaksi/viisi ensimmäistä merkkiä. 

Asia korjataan työnantajan erillisilmoituksen skeemadokumentaatioon seuraavassa versiossa.

Miten tilitoimisto / suora asiakas / loppuasiakas saa kertakäyttösalasanan ja siirtotunnuksen, kun käytössä on tekninen rajapinta? Tarvitseeko loppuasiakkaan valtuuttaa tilitoimistoa laisinkaan? (7.5.2018)

Tilitoimisto/loppuasiakas tekee palvelusopimuksen rajapinnan käyttämisestä tulorekisterin sähköisessä asiointipalvelussa ja ilmoittaa varmenteen yhteyshenkilön sopimusta tehtäessä.

Varmenteen yhteyshenkilö saa ilmoitettuun sähköpostiosoitteeseen turvasähköpostiviestin ja puhelimeensa PIN-koodin, jolla yhteyshenkilö avaa turvasähköpostiviestin mikä sisältää varmennepyyntöön liittyvät siirtotunnukset (TransferID ja TransferPassword). 

Tilitoimistolla tulee olla voimassaoleva toimeksiantosopimus ja valtuudet toimia asiakkaansa puolesta.  

Varmenne ja sidosryhmätestaus

Organisaatiomme haluaa käyttää useita eri varmenteita tulorekisterin sidosryhmätestauksessa. Tehdäänkö sidosryhmätestausta varten yksi testaussopimus jokaiselle varmenteelle?

Ei, jokainen organisaatio tekee yhden testaussopimuksen sidosryhmätestausta varten. Jos organisaatio tietää tarvitsevansa testauksessa useita varmenteita, tästä laitetaan pyyntö sen sähköpostin liitteeksi, jolla Verohallinnon tulorekisterihankkeelle lähetetään allekirjoitettu ja skannattu testaussopimus ja testausympäristön käyttöehdot. Liitteessä pitää yksilöidä tarvittavien varmenteiden lukumäärä javarmenteiden käyttötarkoitukset. Jos eri varmenteilla on eri tekniset yhteyshenkilöt, myös näiden tiedot on kerrottava.

Jos testaussopimus on jo hyväksytty tai testaus on jo meneillään, ohjelmistotalo voi pyytää useampia varmenteita havaintolomakkeella. Linkki havaintolomakkeeseen toimitetaan testaavalle organisaatiolle testaussopimuksen käsittelyn jälkeen. Havaintolomakkeella lähetetyssä pyynnössä pitää olla teknisen yhteyshenkilön tiedot, tarvittavan varmenteen tyyppi, keinotekoinen Y-tunnus (CustomerID) ja Y-tunnukseen liittyvä keinotekoinen organisaation nimi (CustomerName), jotka on toimitettu testaavalle organisaatiolle aikaisemmin.

Ohjelmistotalo käyttää kahta eri ohjelmistoa, joissa molemmissa on omat välityspalvelut. Molempia ohjelmistoja tullaan testaamaan, mutta ohjelmistojen testaus alkaa eri aikaan ja toista varmennetta tarvitaan vasta myöhemmin. Tekeekö ohjelmistotalo yhden testaussopimuksen vai kaksi eri sopimusta? Voiko varmenteita saada lisää myöhemmin?

Ohjelmistotalo tekee yhden sopimuksen ja voi samalla varmenteella testata eri ohjelmistoja. Jos ohjelmistotalolla on perusteltu tarve käyttää useampaa kuin yhtä varmennetta, pyynnön toisesta varmenteesta voi lähettää myöhemmässä vaiheessa havaintolomakkeella. Linkki havaintolomakkeeseen toimitetaan testaavalle organisaatiolle testaussopimuksen käsittelyn jälkeen.

Havaintolomakkeella lähetetyssä pyynnössä pitää olla teknisen yhteyshenkilön tiedot, tarvittavan varmenteen tyyppi, keinotekoinen Y-tunnus (CustomerID) ja Y-tunnukseen liittyvä keinotekoinen organisaation nimi (CustomerName), jotka on toimitettu testaavalle organisaatiolle aikaisemmin..

Tulorekisterihanke käsittelee havaintolomakkeella lähetetyn pyynnön kahden viikon aikana. Tekniselle yhteyshenkilölle toimitetaan uudet siirtotunnukset toisen varmenteen noutamiseksi. Siirtotunnukset ovat voimassa 14 vuorokautta. Uutta testaussopimusta ei tarvitse tehdä.

Kun varmenne haetaan testiympäristössä, kuinka kauan varmenteen hakemisen kertakäyttösalasana (OTP, TransferPassword) on voimassa?

Varmenteen hakemiseen tarvittavat siirtotunnukset ovat voimassa 14 vuorokautta.

Konsernimme alla on useampi ohjelmisto, joita meidän tarvitsee testata. Testausta tullaan tekemään eri aikoina ja eri ohjelmistojen kautta. Tarvitsemmekin siis kaksi varmennetta vaikka olemme yksi iso konserni. Kuinka meidän tulisi toimia? Voimmeko tehdä molemmille ohjelmistoille omat sidosryhmätestaussopimukset?

Konserni tekee yhden testaussopimuksen. Eri ohjelmistoille voi hakea eri varmenteita, jos sellaiseen on perusteltu tarve. Jos varmenteet haetaan ennen testauksen alkua, samaan aikaan, kun testaussopimus tehdään, organisaatio laatii vapaamuotoisen pyynnön ja liittää sen siihen sähköpostiin, jolla se lähettää tulorekisterihankkeelle testaussopimuksen ja testausympäristön käyttöehdot. Liitteessä pitää yksilöidä tarvittavien varmenteiden lukumäärä ja varmenteiden käyttötarkoitukset. Jos eri varmenteilla on eri tekniset yhteyshenkilöt, myös näiden tiedot on kerrottava.

Jos ohjelmistojen testaus aloitetaan eri aikoina, lähetetään pyyntö varmenteesta havaintolomakkeella. Havaintolomakkeella lähetetyssä pyynnössä pitää olla teknisen yhteyshenkilön tiedot, tarvittavan varmenteen tyyppi, keinotekoinen Y-tunnus (CustomerID) ja Y-tunnukseen liittyvä keinotekoinen organisaation nimi (CustomerName), jotka on toimitettu testaavalle organisaatiolle aikaisemmin.

Tuotantosopimusta ei voi tehdä ohjelmistotalo.Tuotannonaikainen varmenne myönnetään tilitoimistolle tai yritykselle. Loppuasiakas voi kuitenkin tuotannossa päättää, kuka voi toimia organisaation puolesta teknisenä yhteyshenkilönä ja teknisesti hallinnoida varmenteita.

Kuinka varmenteen uusiminen testataan? Varmenne on voimassa 2 vuotta ja sen voi uusia vasta 60 vrk ennen vanhenemista.

Tällä hetkellä varmenteen uusimista ei ole mahdollista testata, mutta pyrimme kehittämään toiminnallisuuksia siten, että myös varmenteen uusimista pystyisi testaamaan.

Kun varmenteen elinkaaren hallintaan liittyviä toiminnallisuuksia voi testata, tulorekisterihanke tiedottaa asiasta erikseen.

Voiko tekninen yhteyshenkilömme saada varmenteiden hakemiseen liittyvät viestit englanninkielisinä?

Teknisille yhteyshenkilöille lähetettävät varmennepalvelun viestit ovat kolmikielisiä (suomi, ruotsi ja englanti).

Tuleeko varmenteen sulkemiselle (revoke) rajapintaan oma pyyntö?

Tuotannossa pyyntö varmenteen sulkemisesta tehdään virka-aikana tulorekisteriviranomaiselle ja virka-ajan ulkopuolella helpdeskille.

Sidosryhmätestauksen aikana sulkemispyyntö tehdään tulorekisterin testausorganisaatiolle, jos on kyse testausta varten myönnetystä varmenteesta.

Ohjelmistotalolla ei ole suomalaista Y-tunnusta. Voiko se tehdä testaussopimuksen?

Kyllä voi, testaussopimuksen kohdassa Y-tunnus ilmoitetaan yrityksen ulkomainen tunniste.

Ohjelmistotalo haluaa testata matkakorvausten integraatiota tulorekisteriin. Pitääkö myös matkalaskujärjestelmästä toteuttaa tekninen rajapinta varmennepalveluun eli onko niin, että varmennetta ei toimiteta testausta varten muilla keinoilla kuin varmennepalvelun rajapinnan kautta? (Tuotantokäytössä varmenteen hakee toinen tiedon tuottajan tietojärjestelmä.)

Testauksen varmenne toimitetaan vain varmennepalvelun rajapinnan kautta.

Varmenteeseen liittyvä yksityinen avain on vain tulorekisteriin liittyvän ohjelmiston hallussa, joten asiakkaan on muodostettava se. Varmennepalvelun rajapinta on Web Service -rajapinta, joten varmenteen haku voidaan integroida tiiviisti osaksi asiakasohjelmistoa tai varmenteen nouto voidaan tehdä erillisillä Web Service -ohjelmistoilla kuten SoapUI tai Postman.

Mitä ajankohtaa Katre elää testauksen osalta? Elääkö Katren testikoneen päivämäärä esimerkiksi vuotta 2019 vai onko käytössä jokin muu tulevaisuuden ajankohta?

Kuluva päivä.

Testitapauksia tehdään monen eri ajankohdan tilanteeseen ja mietityttää onko rajoitteita sille, mille ajanjaksolle testitapauksia voidaan tuottaa?

Katso konfiguraatioasiakirja.

Onko esimerkiksi väliä sillä, että tuotamme samanaikaisesti vaikka tammikuun 2019 aineistoa ja helmikuun 2020 aineistoa?

Voitte tuottaa samanaikaisesti tammikuun 2019 aineistoa ja helmikuun 2020 aineistoa.

Mihin Y-tunnuksia pdf-listalla tarvitaan, sidosryhmätestauksessa, jos niitä vasten ei voi hakea varmennetta? (7.5.2018)

Jokaiselle testaavalle organisaatiolle toimitetaan 40 Y-tunnusta ja 200 henkilötunnusta. Sidosryhmät voivat itse valita, kuinka monta palkansaajaa kullakin Y-tunnuksellisella maksajalla on palkkatietoaineistossa. Myös henkilötunnukset voi liittää Y-tunnukseen omavalintaisesti. Testiasiakkaita saa tulorekisteri-hankkeelta tarvittaessa lisää. 

https://www.vero.fi/globalassets/tulorekisteri/liite1_testausohje.pdf

Voitte lisäksi ilmoittaa tulorekisterille rajatun määrän omia testitunnisteitanne, jotka haluatte lisättävän tulorekisterin sidosryhmätestaukseen

https://www.vero.fi/globalassets/tulorekisteri/liite7_ohje-testiaineiston-anonymisoinnista.pdf

Matkalaskujärjestelmässämme on samassa ympäristössä (palvelinohjelmat, tietokanta) useita juridisia yrityksiä, joilla on tuotannossa aikanaan oma sertifikaatti. Meidän pitää pystyä testaamaan tilannetta, jossa palkkatietoilmoitusaineistoja luova ohjelmamme käynnistyy ajastettuna ja löytää oikean varmenteen oikealta yritykseltä. Haluamme siis testata rinnakkaista palkkatietoilmoitusten muodostamista samasta tietokannasta, samalta palvelimelta, eri yrityksille. 

Haluamme siis käyttää tuossa pdf:ssä olevia Y-tunnuksia testiympäristössämme, hakea niille kullekin testisertifikaatin ja tuottaa tulorekisterin testiympäristöön palkkatietoaineistoja. Onko tämä mahdollista? (7.5.2018)

Valitettavasti voitte käyttää testivarmenteiden muodostamisessa ainoastaan teille jo lähetettyä keinotekoista Y-tunnusta (CustomerID) ja siihen liittyvää organisaation nimeä (CustomerName).

Voitte kuitenkin halutessanne muodostaa useita varmenteita tämän tietyn organisaation nimissä. Eli voitte tarvittaessa operoida useammalla varmenteella mutta niin, että varmenteen haltijana on alla olevassa viestissä mainittu organisaatio.

Koska testitunnisteita on käytössä rajallisesti, emme pysty antamaan teille useampia testivarmenneorganisaatioita.

Olette toimittaneet meille PDF-dokumentin testiorganisaatioista (Y-tunnukset) ja henkilöistä (henkilötunnukset). Testivarmenteen hakua varten meille annettu Y-tunnus ei ole meille toimitetulla listalla.

Mihin näitä Y-tunnuksia kyseisellä PDF-listalla tarvitaan sidosryhmätestauksessa, jos niiden avulla ei voi hakea varmennetta? (11.5.2018)

Jokaiselle testaavalle organisaatiolle toimitetaan 40 Y-tunnusta ja 200 henkilötunnusta. Tunnukset valitaan sattumanvaraisesti. Sidosryhmät voivat itse valita, kuinka monta palkansaajaa kullakin Y-tunnuksellisella maksajalla on. Myös henkilötunnukset voi liittää Y-tunnukseen omavalintaisesti.

Matkalaskujärjestelmässämme on samassa ympäristössä (palvelinohjelmat, tietokanta) useita juridisia yrityksiä, joilla on tuotannossa aikanaan oma varmenne. Meidän pitää pystyä testaamaan tilannetta, jossa ajastettuna käynnistetty palkkatietoilmoitusaineiston luontiohjelmamme löytää oikean varmenteen oikealta yritykseltä, eli rinnakkaisia palkkatietoilmoituksia muodostetaan samasta tietokannasta ja samalta palvelimelta mutta eri yrityksille. Haluamme siis käyttää tuossa PDF:ssä olevia Y-tunnuksia testiympäristössämme, hakea niille kullekin testivarmenteen ja tuottaa tulorekisterin testiympäristöön palkkatietoaineistoja. Onko tämä mahdollista? (11.5.2018)

Testivarmenteiden muodostamisessa voi käyttää vain teille jo lähetettyä keinotekoista Y-tunnusta (CustomerID) ja siihen liittyvää organisaationimeä (CustomerName). Voitte kuitenkin halutessanne muodostaa useita varmenteita tämän tietyn organisaation nimissä. Eli voitte tarvittaessa operoida useammalla varmenteella mutta niin, että varmenteen haltija on viestissä mainittu organisaatio. Testitunnuksia on rajallinen määrä, minkä vuoksi emme pysty antamaan teille useampia testiorganisaatioita.

Asiakkaamme varmasti tarvitsevat testausta useammalla kuin yhdellä maksajan Y-tunnuksella. Voiko konserni tehdä useamman testaussopimuksen yhtiötasolla, jolloin jokainen yhtiö saisi teiltä oman tunnuksen? (25.5.2018)

Vielä tällä hetkellä ei ole mahdollista tehdä useita testaussopimuksia yhtiötasolla, mutta tutkimme, voisiko sen jatkossa mahdollistaa.

Onko testausta varten mahdollista saada Y-tunnuksia, joissa käytetään maksajan omaa aliorganisaation tunnistetta? (25.5.2018)

Voitte käyttää niitä Y-tunnuksia, jotka olemme testausta varten teille toimittaneet. Jos haluatte käyttää maksajan oman aliorganisaation tunnistetta, voitte muodostaa tunnisteet itse. Eli kyseessä on maksajan oma koodisto, jota ei tarkisteta tulorekisterissä. Maksajan aliorganisaation tunnisteen tyyppi (koodistossa PayerSubOrgType) on 2 = Maksajan oma koodisto.

Varmenne tuotannossa

Voiko asiakkaalla olla useita varmenteita käytössä samaan aikaan? Asiakkaalla on käytössä useita ohjelmistoja.

Asiakkailla voi olla useita varmenteita samaan aikaan käytössä. Tuotantokäytön alkaessa asiakas voi tilata tulorekisterin sähköisessä asiointipalvelussa organisaatiolleen varmenteita. On myös mahdollista, että asiakas käyttää samaa varmennetta eri ohjelmistoissa.

Voiko asiakas hallinnoida varmenteita tulorekisteri.fi-sivulla, esimerkiksi ladata varmennetiedoston ja viedä sen haluamaansa ohjelmistoon?

Varmenteen muodostaminen tapahtuu teknisten ohjeiden mukaisesti .

Tuotannon aikana asiakas voi nähdä tulorekisterin sähköisessä asiointipalvelussa listan niistä varmenteista, jotka ovat organisaation käytössä.

Voiko tekninen yhteyshenkilömme saada varmenteiden hakemiseen liittyvät viestit englanninkielisinä?

Teknisille yhteyshenkilöille lähetettävät varmennepalvelun viestit ovat kolmikielisiä (suomi, ruotsi ja englanti).

Jos ohjelmistotoimittaja X hakee oman varmenteen, voivatko tämän jälkeen kaikki ohjelmistoa käyttävät tilitoimistot käyttää ohjelmiston X varmennetta?

Ohjelmistotoimittaja X toimii ohjelmistotalona. Jokaisen ohjelmisto X:ää käyttävän asiakkaan, kuten tilitoimiston tai yrityksen, on haettava oma varmenne tulorekisterin tuotantokäyttöä varten.

Tuleeko jokaisen ohjelmistotalon, joka toteuttaa teknisen rajapinnan tulorekisteriin, toteuttaa tekninen rajapinta myös varmennepalveluun?

Tuotannon aikaisen varmenteen hakee ohjelmistotalon asiakasyritys (tilitoimisto tai yritys). Käytännössä ohjelmistoon on kuitenkin toteutettava ratkaisu, jolla varmenne haetaan ja talletetaan ohjelmiston käytettäväksi.

Varmenteet ja tilitoimistot

Ohjelmistotalon asiakkaana on tilitoimistoja, jotka hoitavat omien asiakkaidensa taloushallintoa ja palkkoja taloushallinnon ohjelmistossa X. Jos tilitoimisto lähettää asiakasyrityksen puolesta tulorekisteri-ilmoituksen, voidaanko tällöin käyttää ohjelmiston X omaa varmennetta? Tarvitseeko tilitoimistolla itsellään olla minkäänlaista varmennetta ohjelmistoon X liittyen?

Ohjelmistotoimittaja X toimii ohjelmistotalona. Jokaisen ohjelmisto X:ää käyttävän tilitoimiston on hankittava oma tuotannon aikainen varmenne. Tilitoimistot tarvitsevat siten kukin omat varmenteet. Varmenteen tarvitsee se yritys tai tilitoimisto, joka taloushallinnon ohjelmaa käyttää.

Tulorekisterin tuotannon aikaisen sopimuksen tekee tilitoimisto. Tuotantosopimuksia voi tehdä syksystä 2018 lähtien. Vaikka tilitoimisto tekee sopimuksen, se voi kuitenkin ilmoittaa sopimuksella tekniseksi yhteyshenkilöksi esimerkiksi ohjelmistotalon edustajan, joka tällöin saa varmenteen hakemiseen liittyvät tiedot ja voi siten käytännössä hoitaa varmenteen hakemisen tilitoimiston puolesta.

Miten varmenteet haetaan ja miten niitä käytetään tilitoimistoissa?

Tilitoimisto A, jolla on asiakkaat:
Asiakas 1 Oy
Asiakas 2 Oy
Asiakas 3 Oy

Tilitoimisto B, jolla on asiakkaat:
Asiakas 2 Oy
Asiakas 4 Oy, haluaa tehdä itse aineistotilauksia

Mitä näistä vaihtoehdoista käytetään
1. Hakeeko jokainen asiakas varmenteen itse ja antaa sen tilitoimiston käyttöön?
2. Hakeeko tilitoimisto asiakkaan puolesta varmenteen?
3. Vai onko tilitoimistolla yksi varmenne, jota käytetään kaikilla asiakkailla?

Tilitoimiston nimenkirjoitusoikeudellinen henkilö tekee palvelusopimuksen tulorekisterin kanssa ja hakee yhden varmenteen.

Varmenteen hakemisen yhteydessä tekniseksi yhteyshenkilöksi voi nimetä esimerkiksi ohjelmistotalon edustajan, joka käytännössä hoitaa varmenteen hakemisen tilitoimistolle. Varmenteen voi käytännössä muodostaa tilitoimistolle se taho, jonka tilitoimiston nimenkirjoittaja on merkinnyt tekniseksi yhteyshenkilöksi.

Miten toimitaan Asiakas 2 Oy kohdalla, jonka palkkoja hoitavat Tilitoimisto A ja Tilitoimisto B?

Molemmilla tilitoimistoilla on omat varmenteet ja ne hoitavat asiakkaansa puolesta asiointia normaalisti, kuten asioinnista on sovittu Asiakas 2 Oy:n kanssa.

Miten toimitaan Asiakas 4 Oy kohdalla, joka haluaa tehdä itse aineistotilauksia, mutta Tilitoimisto B tekee ilmoitukset?

Asiakas 4 Oy voi käyttää sähköistä asiointipalvelua aineistotilauksiin tai hankkia oman varmenteen. Tilitoimisto B:llä on oma varmenne, jota käytetään ilmoittamisessa.

Tarvitseeko palkanlaskentaohjelmaa käyttävien tilitoimistojen ja yritysten hakea varmenne? Tarvitseeko yrityksen tai tilitoimiston valtuuttaa ohjelmisto X lähettämään aineistoja heidän puolestaan?

Taloushallinnon ohjelmaa käyttävät yritykset ja tilitoimistot tarvitsevat jokainen oman varmenteen. Jos yrityksen asioita hoitaa tilitoimisto, tilitoimisto tarvitsee varmenteen, jota se käyttää kaikkien asiakkaidensa puolesta asiointiin. Tilitoimiston asiakkaana oleva yritys ei siis tarvitse omaa varmennetta, ellei se ilmoita palkkoja itse rajapinnan kautta.

Kun tilitoimisto on sitoutunut tulorekisterin käyttöehtoihin, se voi ilmoittaa tietoja rajapinnan kautta edustamansa asiakasyrityksen puolesta. Kaikissa tapauksissa varmenteen tarvitsee siis se yritys tai tilitoimisto, joka taloushallinnon ohjelmaa käyttää.

Teknisen rajapinnan käyttöön ei tarvita Suomi.fi-valtuutuksia. Sen sijaan tulorekisterin sähköisessä asiointipalvelussa käytetään Suomi.fi-tunnistautumista, ja yrityksen pitää valtuuttaa tarvittavat henkilöt ja tahot Suomi.fi-valtuutuksilla asioimaan sen puolesta.

Miten toimitaan, jos tilitoimistolla tai yritykselläon useita ohjelmistoja, joista tuotetaan ilmoituksia suoraan tulorekisteriin (esimerkiksi palkka- ja matkalaskujärjestelmä)?

Samaa varmennetta voi käyttää saman tilitoimiston/asiakasyrityksen eri ohjelmistoissa. Tilitoimiston tai yrityksen eri ohjelmistot voivat käyttää samaa varmennetta, jos samantyyppinen varmenne soveltuu eri ohjelmistojen tarpeisiin. Vaihtoehtoisesti jokaiselle ohjelmistolle voi hakea oman varmenteen.

Kuinka ohjeen "Tietojen toimittaminen – Skeemat – Palkkatietoilmoitukset" kohdassa 2.1 "Aineiston tiedot" olevia aineiston omistajaa, muodostajaa ja lähettäjää koskevia käsittelysääntöjä olisi tulkittava alla olevassa tilanteessa:

  • Maksajalla on asiakastunniste eli se on aineiston omistaja Yritys A.

  • Aineiston muodostaa ulkoista palkanlaskentapalvelua tarjoava Yritys B.

  • Tiedoston lähettää viranomaisraportointipalvelua tuottava Yritys C. (11.5.2018)

Omistajaksi on pantava maksaja (A). Muodostajan ja lähettäjän on oltava sama taho, eli se taho, jonka varmenteella tiedosto lähetetään. Kysymyksessä kuvattu tilanne ei ole mahdollinen.

Miten voisimme testata tilannetta, jossa maksajalla, muodostajalla ja lähettäjällä on eri Y-tunnus? (25.5.2018)

Omistajaksi on pantava maksaja. Muodostajan ja lähettäjän on oltava sama taho, eli se taho, jonka varmenteella tiedosto lähetetään. Kysymyksessä kuvattu tilanne ei ole mahdollinen.

Varmenteet ja SaaS-palvelu

Tulorekisterin rajapinnan käyttö edellyttää varmenteen hakemista joko yritykselle itselleen tai sen puolesta asioiville tilitoimistoille tai muulle palkkahallinnon kumppanille.

Miten toimitaan silloin, jos yritys on ostanut palkat ohjelmistotoimittajalta SaaS-palveluna? Voiko samalla palvelimella olla monen yrityksen varmenne tulorekisteriä varten?

Tulorekisterihanke ei ota kantaa siihen, kuinka monta varmennetta on samalla palvelimella. Määrää ei siis ole rajoitettu.

SaaS-palvelussakin kukin tietoja ilmoittava yritys hankkii oman varmenteen. Varmenteen tekniseksi yhteyshenkilöksi voidaan nimetä SaaS-palveluntarjoajan edustaja, jolloin hän voivat yrityksen puolesta hakea varmenteen ja asentaa sen.

Varmenteet ja pilvipohjaiset tuotteet

Yrityksellä Z on pilvipohjaisia tuotteita, joita käyttävät monet loppuasiakkaat, esimerkiksi tilitoimistot.Myönnetäänkö varmenne
1) tulorekisteriin teknisesti tietoja rajapintaan lähettävälle organisaatiolle (=Yritys Z) vai
2) loppuasiakkaalle, joka muodostaa aineiston, esimerkiksi tilitoimisto?

Tulorekisterin varmenne myönnetään loppuasiakkaalle. Varmenne myönnetään tilitoimistolle mutta loppuasiakas voi nimetä varmenteen tekniseksi yhteyshenkilöksi Yritys Z:n edustajan, joka voi käytännössä hakea varmenteen.

Varmenteen uusiminen

Kun varmennetta uusitaan, korvaako uusi varmenne vanhan heti, vai onko vanha voimassa sen alkuperäiseen voimassaolopäivään asti? Dokumentaatio mainitsee kyllä, että vanha tulisi korvata, mutta ei määrittele tarkemmin sitä, onko saatu uusi varmenne korvaava vai käytännössä vain uusi varmenne. Jos uusi korvaa vanhan varmenteen, korvaako se sen silloin, kun se on muodostettu, vai vasta, kun se on noudettu?

Vanha varmenne jää voimaan, kunnes se vanhenee tai se pyydetään erikseen sulkemaan. Uusi varmenne on siinä mielessä korvaava, että sillä on sama DN kuin vanhalla, mutta itse varmenne on uusi.

Täytyykö uusi avainpari generoida? (21.3.2018)

Kyllä. Avaimen uusimisella halutaan vähentää riskiä avaimen joutumisesta vääriin käsiin.

Miten XML-allekirjoitus muodostetaan yksityisellä avaimella? (21.3.2018)

XML-allekirjoituksen speksi on julkaistu tulorekisterin rajapintadokumentaatiossa.

Koskevatko erikoismerkkien muunnoksiin liittyvät vaatimukset käytännössä asiakkaan nimeä (CustomerName), mikäli se välitetään rajapinnassa? Esim. siirtotunnukselle (TransferId) ja kertakäyttösalasanalle (TransferPassword) ei olisi tarvetta tehdä merkkikonversiota? (21.3.2018)

Rajapinnan palvelussa tulee käyttää UTF-8-merkistöä. Mikäli lähetettävät tiedot ovat tämän merkistön puitteissa, ei konversioita tarvita.

Saimme onnistuneesti haettua testivarmenteet palvelusta https://pkiws-testi.vero.fi/2017/10/CertificateServices.wsdl, mutta muita annettuja palveluita kokeillessa
https://ws-testi.tulorekisteri.fi/20170526/InvalidationService.svc
https://ws-testi.tulorekisteri.fi/20170526/PayerSummaryReportService.svc
https://ws-testi.tulorekisteri.fi/20170526/StatusService.svc
https://ws-testi.tulorekisteri.fi/20170526/WageReportService.svc
palautuu vain http virhe 403 forbidden ilman lisäselitteitä, niin selaimen kautta tai koodin kautta täytenä Web Service -kutsuna. Onko muilla testaajilla tullut vastaavaa ongelmaa vastaan, vai mistä tuo voisi johtua? Vaaditaanko jonkin meidän IP:n whitelistaus? (13.4.2018)

Testiympäristössä käytetään varmennepalveluista haettua varmennetta myös SSL-varmenteena. Tällä varmenteella tunnistautuminen onnistui.

Ymmärtääkseni testipalvelimet eivät vaadi erillistä SSL-varmennetta, vaan se tulee vasta tuotantokäytössä, ja tällöinkin sen puuttuessa virhe olisi http 401? (13.4.2018)

Testipuolella on asiakasvarmenteella autentikointi päällä kuten tuotannossakin. Eli sidosryhmän tulee konfiguroida ohjelmansa käyttämään varmennetta autentikoinnissa.

Varmennetiedostojen allekirjoittaminen

Voitteko täsmentää käytännön esimerkin kautta, mitä varmennepalvelusta tarvitaan allekirjoittamiseen / allekirjoitusprosessi yleisesti? (21.3.2018)

Ohje allekirjoitukseen on teknisen rajapinnan soveltamisohjeessa. Varmennepalvelu allekirjoittaa Web Service-palveluiden vastaussanomat omalla varmenteellaan. Asiakas tai asiakkaan järjestelmä voi halutessaan tarkistaa tämän allekirjoituksen ja varmistua siitä, että vastaus tulee varmennepalvelulta. Mitään pakkoa tätä tarkistusta ei ole tehdä.

Aineistotilauksen XML-vinkkejä (21.3.2018)

  • DeliveryDataOwner/ = maksajan tunnus, mikäli sellainen on käytettävissä. Jos maksajalla ei ole asiakastunnistetta ja palveluntarjoaja toimittaa tiedot maksajan puolesta: ownerin pitää olla palveluntarjoajan tunniste
  • Creator/Sender = näissä oltava varmenteen keinotekoinen Y-tunnus
  • DeliveryChannelCode = tässä oltava 1 eli jakelukanavana SFTP
  • ValidFrom = tässä ei voi olla menneisyyden päivämäärää
  • ModifiedTimespanEnd = tätä tietoa ei voi antaa jatkuvalle tilaukselle. Jatkuvassa tilauksessa poiminta-aikaväli päättyy aina poimintahetkeen, joka on taas seuraavan tilauksen poimintavälin alkuhetki
  • QueryDataSchemaVersion = tieto käytettävistä skeemaversioista (palkkatietoilmoitukset ja työnantajan erillisilmoitukset):
    • http://www.tulorekisteri.fi/2017/1/WageReportsFromIR

    • http://www.tulorekisteri.fi/2017/1/PayerSummaryReportsFromIR

    • Aineistotilauksen XML:ssä <QueryDataSchemaVersion>http://www.tulorekisteri.fi/2017/1/WageReportsFromIR</
      QueryDataSchemaVersion>

  • QueryProfile = aineistotyypillä 306 käytetään työnantajan erillisilmoituksen profiilia xx
  • Palkkatietoilmoituksien tilauksissa (300, 303..) käytetään profiilia xx
  • Aineistotyypin 303 tilauksen pakolliset hakuparametrit: Lista maksajia, Lista tulonsaajia
  • Signature-elementin allekirjoitus tulee muodostaa noudetulla varmenteella. SFTP-palvelun osoite on sftp-testi.tulorekisteri.fi.