Suomi.fi-valtuudet – Käyttöönotto

Organisaatio hakee Suomi.fi-valtuuksien asiakasorganisaatioksi sähköisellä hakemuslomakkeella, johon täytetään palveluun liitettävää asiointipalvelua koskevat perustiedot.

Samalla organisaatio hyväksyy käyttöehdot allekirjoittamalla käyttöehtojen hyväksymislomakkeen ja liittää sen hakemuslomakkeeseen.

Asiakasorganisaation tulee kuvata liitteeksi myös käyttötapaus eli kuinka asiontipalvelu hyödyntää palvelua asiointiprosessissaan. Kuvaustapa on vapaamuotoinen, mutta käyttötapauksesta tulee ilmetä, miten vahva tunnistautuminen on järjestetty, miten toisen puolesta asiointia käytetään sekä prosessikuvaus käyttötapauksesta. Käyttötapaukseen voi hyödyntää oheista pohjaa: Käyttötapauslomake

Jos organisaatiosi haluaa integroida Suomi.fi-valtuuksien rajapintapalvelut asiointipalveluun, tee näin:

  1. Tutustu Suomi.fi-valtuuksien esittelymateriaaliin: https://esuomi.fi/palveluntarjoajille/valtuudet/
  2. Täytä liittymisilmoitus ja liitä siihen käyttötapauskuvaushttps://esuomi.fi/palveluntarjoajille/valtuudet/kayttoonotto/
  3. Arvioi tarpeisiinne sopiva liittymistapa kahdesta vaihtoehdosta tämän dokumentin avulla ja toimita valtuuksien käyttöönottotiimille liityntään tarvittavat tiedot osoitteeseen: valtuudet-kayttoonotot@vrk.fi
    1. Jos valitsemasi liityntätapa on WebAPI-liityntä, toimita paluusoite
    2. Jos valitsemasi liityntätapa on Suomi.fi-palveluväylä, liity ensin palveluväylän käyttäjäksi ja toimita sen jälkeen seuraavat tiedot: Member Class, Member Code, Subsystem Code)
  4. Tämän jälkeen valtuuksien käyttöönottotiimi perustaa teille testiympäristön, jonka avulla voitte tehdä kehityksen aikaista testausta. Käyttöönottotiimi toimittaa samalla myös testiaineiston ja muut asiakastestiympäristöön liittymiseen tarvittavat tiedot.
  5. Tee kehitystyö ja testaus valmiiksi ja ilmoita käyttöönottotiimille tuotantokäytön ajankohta. Ilmoita käyttöönottotiimille myös tuotantoympäristöön liittymiseen tarvittavat tiedot eli WebAPI-liitynnässä paluuosoite tai palveluväylä-liitynnässä Member Class, Member Code, Subsystem Code ja liityntäpalvelimen julkinen IP-osoite palomuuriavauksia varten.
  6. Ilmoita käyttöönottotiimille jonkun henkilön nimi ja henkilötunnus pääsyoikeuksien myöntämiseksi asiointipalvelunne sääntömoottoria varten.
  7. Ilmoita käyttöönottotiimille myös sähköpostiosoite tai osoitteet häiriötiedotteille ja julkaisutiedotteille.

Tässä taulukossa kuvataan Suomi.fi-valtuuksien käyttöönoton prosessi.

Palvelun hyödyntämistä varten asiointipalvelulla tulee olla käytössään vahvan tunnistamisen tunnistuspalvelu:

TEHTÄVÄ TIEDOT STATUS OHJEISTUS JA LISÄTIEDOT
1. KARTOITUS   
Täytä Suomi.fi-valtuuksien liittymislomake ja siinä olevat liitteet.

Suomi.fi-valtuuksien liittymislomake

Hyödyntäjäorganisaatio tekee Organisaatio hakee Suomi.fi-valtuuksien  asiakasorganisaatioksi sähköisellä hakemuslomakkeella, johon täytetään palveluun liitettävää asiointipalvelua koskevat perustiedot.

Samalla organisaatio hyväksyy käyttöehdot allekirjoittamalla käyttöehtojen hyväksymislomakkeen ja liittää sen hakemuslomakkeeseen.

Asiakasorganisaation tulee kuvata liitteeksi myös käyttötapaus eli kuinka asiontipalvelu hyödyntää palvelua asiointiprosessissaan. Kuvaustapa on vapaamuotoinen, mutta käyttötapauksesta tulee ilmetä, miten vahva tunnistautuminen on järjestetty, miten toisen puolesta asiointia käytetään sekä prosessikuvaus käyttötapauksesta. Käyttötapaukseen voi hyödyntää oheista pohjaa: Käyttötapauslomake

Käyttötapauksen validointi VRK tekee VRK arvioi asiakasorganisaation käyttötapauksen toteuttamiskelpoisuuden ja pyytää tarvittaessa lisätietoja.Jos asiakas käyttää Katso-palvelua, Valtuudet-palvelun soveltuvuus tulee arvioida.
2. SUUNNITTELU   
Tuotantokäytön aloituksen päivämäärä Asiakasorganisaatio ja VRK suunnittelevat yhdessä käyttöönoton tarkennettu aikataulun.
Käyttöönotettavien rajapintojen ja ominaisuuksien yhteenveto Henkilön puolesta asiointi:

  • Aikuisen puolesta asiointi
  • Alaikäisen huollettavan puolesta asiointi

Yrityksen puolesta asiointi:

  • Toimielinrooliin ja nimenkirjoitusoikeuteen pohjautuva asiointi
  • Valtuusrekisteriin pohjautuva asiointi

Liityntätapa:

  • WebAPI
  • Palveluväylä

Hyödynnettävät rekisterit:

  • Väestötietojärjestelmä
  • Kaupparekisteri
  • Valtuusrekisteri
  • Katso
Materiaalit:

Mikäli käytetään liityntäpalvelin-rajapintaa. HUOM: Varaa liityntäpalvelimen asennukseen sekä varmenteiden ja palomuurien avauksiin riittävästi aikaa.

Rajapinnan totetutuksessa voidaan hyödyntää Githubista löytyviä valmiita kirjastoja. Github-palvelu

3. TOTEUTUS   
Valinnainen: Testi-liityntäpalvelimen asennus Hyödyntäjäorganisaatio tekee Mikäli käytetään liityntäpalvelin-rajapintaa: http://esuomi.fi/palveluntarjoajille/palveluvayla/HUOM: Varaa liityntäpalvelimen asennukseen sekä varmenteiden ja palomuurien avauksiin riittävästi aikaa.
Valinnainen: Testi-liityntäpalvelimen tiedot Hyödyntäjäorganisaatio ilmoittaa VRK:lle seuraavat:

  • X-road Instance: FI-TEST
  • Member Class:
  • Member Code:
  • Subsystem Code:
Valtuudet-tiimi toimittaa saadut tiedot tekniselle asiantuntijalle, joka koordinoi palomuurien avauksen ja luvitukset.

  • Asiakasorganisaatio selvittää liityntäpalvelimen parametrit omasta liityntäpalvelin-ympäristöstään ja toimittaa ne VRK:n käyttöönoton projektipäällikölle.
Valinnainen: Asiakasorganisaation luvitus Valtuudet-palvelun liityntäpalvelimeen, testiympäristö (liityntäpalvelinliitos) VRK tekee
Valinnainen: Testipalvelun perustaminen (liityntäpalvelinliitos) VRK tekee Talletetaan saadut liityntäpalvelintiedot ja asiakasorganisaation tiedot palvelun perustietoihin.
Valinnainen: Testipalvelun perustaminen ja asiointipalvelun tunnisteiden luonti (WebAPI-liitos) VRK toimittaa hyödyntäjäorganisaatiolle:

  • WebAPI client ID:
  • API Key (ei kirjata)
  • Oauth-salasana (ei kirjata)

Hyödyntäjäorganisaatio toimittaa VRK:lle:

  • paluuosoite (voi olla useampi):
VRK toimittaa generoidut tunnisteet asiakasorganisaatiolle salatulla sähköpostilla ja tallettaa asiakasorganisaatiolta saadun paluuosoitetiedon.
Valinnainen: Valtuuskoodien määrittely Hyödyntäjäorganisaatio / VRK tekee Listataan tähän määritellyt valtuuskoodit.
Valinnainen: Valtuuskoodien rajaustarkenteen määrittely Hyödyntäjäorganisaatio / VRK tekee Listataan tähän määritellyt rajaustarkenteet.
Valinnainen: Uudet valtuuskoodit lisätään testiympäristön valtuuskoodistoon.  (Valtuusrekisterin sähköisten valtakirjojen käyttöönotto) VRK tekee Määritellyt uudet asiakasorganisaation toimialaa koskevat valtuuskoodit ja niiden kuvaukset lisätään testiympäristön valtuuuskoodistoon.
Valinnainen: Asiakastestiympäristön päivittäminen VRK tekee Asiakastestiympäristön sovellusversio päivitetään, jotta uudet valtuuskoodit tulevat hyödynnettäväksi testaukseen.
Valinnainen: Katso-integraation toteutus asiakastestiympäristöön VRK tekee Vain Katso-palvelusta Valtuudet-palveluun siirtyville asiointipalveluille. VRK tekee seuraavat toimenpiteet:

  • Lähettää liityntäagentin julkisen avaimen hyödyntäjäorganisaatiolle, joka lisää sen oman liityntäagenttinsa metadataan
  • Liittää Katso-rooli(t) valtuuskoodiin ontologiatiedostossa.
  • Asettaa hyödyntäjäorganisaation liityntäagentin tunnisteen hallintakäyttöliittymällä asiakaskohtaiseen palvelukonfiguraatioon.

Lisäksi valtuudelle lisätään aina seuraavat Katso-roolit:

  • all
  • secondary_admin
Asiakastestiympäristö: Valtuuksien hallintakäyttöliittymän käyttöönotto VRK tekee Valtuudet-tiimi lisää käyttöoikeudet jollekin testiaineiston hetulle ja toimittaa hetun hyödyntäjäorganisaaatiolle.Asiakastestiympäristön hallintakäyttöliittymä: https://asiointivaltuudet.test.suomi.fi/
Valinnainen: Asiakastestiympäristö: Valtuuskoodien käytön luvittaminen (Valtuusrekisterin  sähköisten valtakirjojen käyttöönotto) VRK tekee VRK luvittaa testiympäristössä asiakasorganisaatiolle ne valtuuskoodit, joita loppukäyttäjät voivat käyttää asiakasorganisaation palveluissa ja palvelukanavissa. Tämän myötä uudet valtuuskoodit tulevat näkyviin ja valittavaksi sähköisen valtakirjan luonnissa, valtuuskoodien hakunäytölle. Lisäksi hakunäytölle tulee näkyviin linkitys niihin PTV:ssä kuvattuihin palveluihin ja kanaviin, joissa valtakirjaan perustuva toisen puolesta asiointi on mahdollistettu.
Testidatan toimitus VRK tekee VRK toimittaa käyttötapaukseen soveltuvan testidatan asiakasorganisaatiolle.
VRK:n palvelutuotannolle tieto testiympäristöön liittymisestä. VRK tekee Valtuudet-tiimi ilmoittaa testiympäristöön liittyneen asiakasorganisaation tiedot VRK:n palvelutuotantoon seuraavilla tiedoilla:

  • Asiakasorganisaation nimi ja asiointipalvelu
  • Mikä Valtuudet-palvelun ominaisuus asiakasorganisaatiolla on testauksessa (esim. HPA WebAPI tai YPA Palveluväylä)
  • Palvelun tunniste (joko Palveluväylätunniste tai Web API client ID)
  • Testiympäristön häiriötiedotteiden sähköpostijakelulista
Tietoluvan vahvistaminen VRK tekee Varmistetaan, että tietolupa on kunnossa.
Valinnainen: Tuotanto-liityntäpalvelimen asennus Hyödyntäjäorganisaatio tekee Mikäli käytetään liityntäpalvelin-rajapintaa.http://esuomi.fi/palveluntarjoajille/palveluvayla/

HUOM: Varaa liityntäpalvelimen asennukseen sekä varmenteiden ja palomuurien avauksiin riittävästi aikaa.

Valinnainen: Tuotanto-liityntäpalvelimen tiedot Hyödyntäjäorganisaatio ilmoittaa VRK:lle seuraavat:

  • julkinen IP-osoite:
  • X-road Instance: FI
  • Member Class:
  • Member Code:
  • Subsystem Code:
Valtuudet-tiimi toimittaa saadut tiedot tekniselle asiantuntijalle, joka koordinoi palomuurien avauksen ja luvitukset.

  • Asiakasorganisaatio selvittää liityntäpalvelimen parametrit omasta liityntäpalvelinympäristöstään ja toimittaa ne VRK:n käyttöönoton projektipäällikölle.
Valinnainen: Liityntäpalvelimien palomuurien avaus, tuotanto (liityntäpalvelin liitos) Hyödyntäjäorganisaatio ja VRK tekee omissa liityntäpalvelimissaan
Valinnainen: Asiakasorganisaation luvitus Valtuudet- liityntäpalvelimeen, tuotanto (liityntäpalvelin liitos) VRK tekee
Valinnainen: Tuotantopalvelun perustaminen (liityntäpalvelinliitos) VRK tekee VRK tallentaa saadut liityntäpalvelintiedot ja asiakasorganisaation tiedot palvelun perustietoihin.
Valinnainen: Tuotantoympäristö: Asiointipalvelun tuotantokonfiguraation ja tunnisteiden luonti (WebAPI-liitos) VRK toimittaa hyödyntäjäorganisaatiolle:

  • WebAPI client ID:
  • API Key (ei kirjata)
  • Oauth-salasana (ei kirjata)

Hyödyntäjäorganisaatio ilmoittaa VRK:lle:

  • paluuosoite (voi olla useampi):
VRK toimittaa generoidut tunnisteet asiakasorganisaatiolle salatulla sähköpostilla ja tallettaa asiakasorganisaatiolta saadun paluuosoitetiedon.
Valinnainen: Valtuuskoodien tuotannollistamisen aikataulun koordinointi VRK tekee yhteistyössä hyödyntäjäorganisaation kanssa Valtuuskoodien käyttöönotto edellyttäää sovellusversion päivityksen. Valtuuksien sovellusversio päivitetään tuotantoympäristöön lähtökohtaisesti kahden viikon välein. Hyödyntäjäoganisaation valtuuskoodien tuotannollistaminen pitää tehdä sovellusversion päivityksen yhteydessä.
Valinnainen: Uudet valtuuskoodit lisätään tuotantoympäristön valtuuskoodistoon (Valtuusrekisterin sähköisten valtakirjojen käyttöönotto) VRK tekee VRK lisää määritellyt uudet asiakasorganisaation toimialaa koskevat valtuuskoodit ja niiden kuvaukset tuotantoympäristön valtuuskoodistoon.
Valinnainen: Katso-integraation toteutus tuotantoon VRK tekee Vain Katso-palvelusta Valtuudet-palveluun siirtyville asiointipalveluille. VRK tekee seuraavat toimenpiteet:

  • Lähettää liityntäagentin julkisen avaimen hyödyntäjäorganisaatiolle, joka lisää sen oman liityntäagenttinsa metadataan
  • Liittää Katso-rooli(t) valtuuskoodiin ontologiatiedostossa.
  • Asettaa hyödyntäjäorganisaaiton liityntäagentin tunnisteen hallintakäyttöliittymällä asiakaskohtaiseen palvelukonfiguraatioon.

Lisäksi valtuudelle lisätään aina seuraavat Katso-roolit:

  • all
  • secondary_admin
Valinnainen: Valtuuskoodien asettaminen oikeisiin palveluihin ja palvelukanaviin PTV:n tuotantoympäristössä  (Valtuusrekisterin sähköisten valtakirjojen käyttöönotto) Hyödyntäjäorganisaatio tekee Asiakasorganisaatio asettaa PTV:n tuotantoympäristössä käyttöönotettavat valtuuskoodit niihin palveluihin ja palvelukanaviin, joissa sähköiseen valtakirjaan perustuva toisen puolestaasiointi mahdollistetaan. Jos asiakasorganisaatio ei ole vielä kuvannut palveluitaan PTV:hen, täytyy sen kuvata PTV:hen vähintään ne palvelut ja palvelukanavat, joissa halutaan mahdollistaa toisen puolesta asiointi sähköisten valtakirjojen avulla. Lisätietoja: Suomi.fi-palvelutietovaranto
Tuotantoympäristö: Sääntömoottorin säännöt VRK/Hyödyntäjäorganisaatio tekee Asetetaan sääntömoottorin säännöt asiakasorganisaation suunnittelemalla tavalla. Jatkossa organisaatio ylläpitää sääntöjä itsenäisesti.
Tuotantoympäristö: Valtuudet-palvelun hallintakäyttöliittymän käyttöönotto Hyödyntäjäorganisaatio toimittaa Valtuudet-palvelua hyödyntävien pääkäyttäjiensä nimitiedot ja henkilötunnukset Valtuudet-tiimi luo käyttöoikeuden Valtuudet-hallintakäyttöliittymään toimitetuille henkilötunnuksille.Tuotantoympäristön hallintakäyttöliittymä: https://asiointivaltuudet.suomi.fi/
Valinnainen: Tuotantoympäristö: Valtuuskoodien käytön luvittaminen (Valtuusrekisterin sähköisten valtakirjojen käyttöönotto) VRK tekee VRK luvittaa tuotantoympäristössä asiakasorganisaatiolle ne valtuuskoodit, joita loppukäyttäjät voivat käyttää asiakasorganisaation palveluissa ja palvelukanavissa. Tämän myötä uudet valtuuskoodit tulevat näkyviin ja valittavaksi sähköisen valtakirjan luonnissa, valtuuskoodien hakunäytölle. Lisäksi hakunäytölle tulee näkyviin linkitys niihin PTV:ssä kuvattuihin palveluihin ja kanaviin, joissa  valtakirjaan perustuva toisen puolesta asiointi on mahdollistettu.
4. VIIMEISTELY JA KÄYTTÖÖNOTTO
Tuotantotestaus Hyödyntäjäorganisaatio tekee Asiakasorganisaatio testaa tuotantoympäristön toimivuuden aidolla datalla.
Koulutus ja ohjeistukset Hyödyntäjäorganisaatio tekee, VRK tukee Asiakasorganisaatio kouluttaa uudet toimintamallit henkilöstölleen. Tukiprosessin ja hyödynnettävissä olevan tukimateriaalin (mm. ohjevideot) läpikäynti.Tietoa Suomi.fi-valtuuksista Suomi.fi-verkkopalvelussa
Päivitetään valtuuksia hyödyntävien palveluiden lista VRK tekee Listataan uudet palvelut ja uudet valtuuskoodit: Valtuudet: Suomi-valtuuksia hyödyntävät palvelut

Ilmoitus verkkotoimitukselle (suomi.fi@suomi.fi) sähköpostiin lisäyksestä.

Käyttöönotto valmis VRK tekeeHyödyntäjäorganisaatiolta tarvitaan sähköpostiosoite, johon toimitetaan palvelun häiriötiedotteet VRK ilmoittaa uudesta käyttöönotosta:

Ilmoitetaan yllä oleville tahoille:

  • missä asiointipalvelussa on otettu Valtuudet käyttöön
  • minkä tyyppistä asiointia Valtuuksien avulla siellä tehdään (HPA / YPA)
  • mitä asiointivaltuuksia palvelussa voi hyödyntää (valtuuskoodien nimet)
  • lisäksi Palvelupisteelle ilmoitetaan palvelun tekninen tunniste (WebAPI client ID tai palveluväylätunniste)
  • lisäksi Palvelupisteelle ilmoitetaan häiriötiedoteosoitteet.

Print Friendly, PDF & Email

VersioMitä tehty / muutettuPvm/
henkilö
1.0Dokumentti julkaistu eSuomessa20.01.16 / NP
1.1Sisältöä päivitetty11.1.16/TR
1.2.Sisältöä päivitetty12.12.2018 / EJ
1.3.Sisältöä päivitetty.30.1.2019 / EJ

Yksilöintitunnus: 12345