Liityntätavan ja rajapintojen valinta

Suomi.fi-valtuuksia voi hyödyntää kahdella erilaisella teknisellä liittymistavalla. Toinen on Suomi.fi-palveluväylä ja toinen WebAPI-liityntä.

WebAPI-liityntä

Suomi.fi-palveluväylä:

Kumpi liityntätapa soveltuu parhaiten minun asiointipalveluuni?

  • Jos asiointipalvelussa halutaan mahdollistaa henkilön puolesta asiointi, suositeltavin liittymistapa on tällöin WebAPI-liityntä.
  • Jos asiointipalvelussa halutaan mahdollistaa sekä henkilön että yrityksen puolesta asiointi, suositeltavin liittymistapa on tällöin WebAPI-liityntä. Muutoin joudutaan rakentamaan integraatio kahdella eri liittymistavalla.
  • Jos asiointipalvelussa halutaan mahdollistaa pelkästään yrityksen puolesta asiointi ja päämiehen valinta halutaan tehdä asiointipalvelun omalla käyttöliittymällä, silloin ainoa vaihtoehto on Suomi.fi-palveluväylä.

Esimerkit asiointipoluista

WebAPI-liityntä

1. Tunnistaudutaan asiointipalveluun
2. Valitaan ”Toisen puolesta asiointi”
Istunto siirtyy Valtuudet-palvelun valintakäyttöliittymälle, josta valitaan kenen puolesta halutaan asioida

4. Valinnan jälkeen istunto palaa asiointipalveluun ja asiointi jatkuu valtiun päämiehen puolesta (henkilö tai yritys)

Suomi.fi-palveluväylä

1. Tunnistaudutuaan asiointipalveluun ja valitaan pudotusvalikosta yritys jonka puolesta halutaan asioida

Liityntätapojen arkkitehtuuriset erot

WebAPI-liityntä

Suomi.fi-palveluväylä

Asiakastestiympäristöön liittyminen

WebAPI-liityntä

Ilmoita Valtuuksien käyttöönottotiimille (valtuudet-kayttoonotot@vrk.fiWebAPI-liitynnän paluuosoite.  Se on asiointipalvelun osoite johon käyttäjän selainistunto ohjataan sen jälkeen kun hän on valinnut päämiehen Valtuudet-palvelun valintakäyttöliittymällä. Osoite voi olla testausvaiheessa localhost. Protokolla pitää olla https ja osoitteessa pitää olla osoitteen polku kokonaisuudessaan.

Kun asiointipalvelu aloittaa OAuth-valtuutusprosessin se välittää asiointivaltuuspalvelulle uudelleenohjausosoitteen johon käyttäjän selain ohjataan valtuutuksen päätteeksi. Jotta paluupyynnön mukana välitettävä OAuth-avain ei päädy väärin käsiin, rajoittaa asiointivaltuudet-palvelu uudelleenohjauksen vain sille ennalta määriteltyihin osoitteisiin. Asiointipalvelun on toimitettava tieto täsmällisistä uudelleenohjausosoitteista asiontivaltuudet-palvelulle liityntäprosessin yhteydessä.

Lisätietoa: http://security.stackexchange.com/questions/44214/what-is-the-purpose-of-oauth-2-0-redirect-uri-checking

Suomi.fi-palveluväylä

WebAPI-liitynnän kautta hyödynnettävät valtuuksien rajapintakyselyt

Rajapintakysely Syöte Vapaaehtoinen syöte Vastaus Vastausesimerkki
Delegate sessionId Lista päämiesten perustiedoista
Authorization asiamiehen hetu + päämiehen hetu issue (valtuuskoodin uri, voi olla useita Päätöstieto onko puolesta-asiointi valitussa kontekstissa sallittu [{"result":"ALLOWED","reasons":[],"principal":{"personId":"120508A950F","name":"Kumpulainen Anni Emilia"}}]
AuthorizationList asiamiehen hetu + päämiehen hetu AuthorizationList-kutsu palauttaa tiedon kaikista valtuutustunnisteista, eli asioista, joissa asiamiehellä on asiointioikeus päämiehen puolesta. Mikäli asiat eivät ole rajattuja, esim. huoltajuussuhteen vuoksi, palautetaan erillisten asioiden sijaan ALL. [{"reasons":[],"roles":
["ALL",
"http://valtuusrekisteri.suomi.fi/sukuselvityksen_tilaaminen",
"principal":{"personId":"010132-998W","name":"Tuulispää Edelweiss"
}}]
OrganizationalRoles asiamiehen hetu y-tunnus
Haettavan organisaation tunniste (y-tunnus). Voi olla useita
OrganizationalRoles -kutsu palauttaa listan puolesta-asioijan organisaatioista ja niihin liittyvistä rooleista. [{"name":"Itä-Suomen Alihankkijat Oy","identifier":"2149444-1","complete":true,"roles": [ "TJ" "http://valtuusrekisteri.suomi.fi/tyonhakijatietojen_tarkastelu_ja_yhteydenotto_hakijoihin", "http://valtuusrekisteri.suomi.fi/tyontarjoajan_kuvauksen_paivitys" ]}]

Suomi.fi-palveluväylän kautta hyödynnettävät valtuuksien rajapintakyselyt

Rajapintakysely Syöte Vapaaehtoinen syöte Vastaus Vastausesimerkki
Authorization asiamiehen hetu + päämiehen hetu issue (valtuuskoodin uri, voi olla useita Päätöstieto onko puolesta-asiointi valitussa kontekstissa sallittu
ALLOWED
AuthorizationList asiamiehen hetu + päämiehen hetu AuthorizationList-kutsu palauttaa tiedon kaikista valtuutustunnisteista, eli asioista, joissa asiamiehellä on asiointioikeus päämiehen puolesta. Mikäli asiat eivät ole rajattuja, esim. huoltajuussuhteen vuoksi, palautetaan erillisten asioiden sijaan ALL.

ALL
http://valtuusrekisteri.suomi.fi/palkkatietojen_ilmoittaminen

OrganizationalRoles asiamiehen hetu y-tunnus
Haettavan organisaation tunniste (y-tunnus). Voi olla useita.
OrganizationalRoles -kutsu palauttaa listan puolesta-asioijan organisaatioista ja niihin liittyvistä rooleista.


aaaaaaa-a
Maanrakennus Ari Eerola T:mi

NIMKO



bbbbbbb-b
Rova Oy 1

NIMKO



VersionroMitä tehtyPVM /Henkilö
1.0Sivu luotu12.12.2018 / EJ