Source: https://esuomi.fi/palveluntarjoajille/valtuudet/tekninen-aineisto/kyselyn-rajapintakuvaus-henkilon-puolesta-asiointi/
Timestamp: 2019-12-16 03:46:42+00:00
Document Index: 16955585

Matched Legal Cases: ['kko ', 'kko ', 'kko ', 'kko ', 'kko ', 'kko ', 'kko ']

﻿ Kyselyn rajapintakuvaus, henkilön puolesta asiointi – esuomi.fi
You are here: Home / Suomi.fi-palvelut / Suomi.fi-valtuudet / Tekninen aineisto / Kyselyn rajapintakuvaus, henkilön puolesta asiointi
Suomi.fi-valtuudet – Kyselyn rajapintakuvaus, henkilön puolesta asiointi
1.1 Kyselyn rajapintakuvaus
2 Rajapinnan kutsuminen
3 X-Road-6 attribuutit
4 Kutsukuvaus: Authorization – asiointioikeushaku
5 Kutsukuvaus: AuthorizationList – valtuustunnistehaku
6 Sanomaesimerkit
Tässä dokumentissa kuvataan Suomi.fi-valtuuksien valtuudet-kyselyn rajapintakuvaus ja kutsurajapinnan esimerkkitapaukset henkilön puolesta asioinnin (HPA) osalta.
Asiamies on henkilö, jonka toinen on valtuuttanut toimimaan puolestaan eli päämiehen puolesta-asioija.
Valtuuksien rajapintakokonaisuus tarjoaa kaksi erillistä kyselyrajapintaa henkilön puolesta asiointiin. Henkilön puolesta asiointiin tarjotaan Authorization- ja AuthorizationList-rajapinnat. Rajapinnat tarjotaan Suomi.fi-palveluväylän (XRoad6) kautta. X-Road SOAP-otsakkeita käytetään Suomi.fi-palveluväylä-yhteyden lisäksi palvelun (client header) ja loppukäyttäjän (userId) tunnistamiseen Suomi.fi-valtuuksissa.
Authorization Asiointioikeuskysely asiamiehen tunnisteen (delegateIdentifier) ja päämiehen tunnisteen (principalIdentifier) perusteella. authorization.wsdl 25.5.2016 (dokumentaatio päivitetty 26.10.2017)
AuthorizationList Valtuusasiat erittelevien URI:en, eli issue-tunnisteiden kysely asiamiehen ja päämiehen tunnisteiden perusteella. authorizationList.wsdl 26.10.2017
Rajapintakuvauksissa viitataan lisäksi seuraaviin X-Roadin skeematiedostoihin: xroad6.xsd ja xroad6identifiers.xsd.
Oheisessa taulukossa on lueteltu X-Road v6 -otsakkeet, jotka on asetettava Suomi.fi-valtuuksia kutsuttaessa:
Taulukko 2. X-Road attribuutit Suomi.fi-valtuudet-kyselyissä:
userId x Loppukäyttäjän tunnistava tunniste, ei kuitenkaan henkilötunnus. Esim. tunnistustapahtuman assertio tai vastaava.
X-Road protokollan tarkempi kuvaus: Suomi.fi-palveluväylä – X-Road-tiedonsiirtoprotokolla
Kutsu sisältää asiamiehen tunnisteen (delegateIdentifier) sekä päämiehen tunnisteen (principalIdentifier).
Taulukko 3. Authorization-kyselysanoman kuvaus
principalIdentifier Pakollinen tieto. Puolesta-asioitavan eli päämiehen yksilöllinen tunniste hetu
issue Valtuutuksen uri. Voi olla useita. uri
Authorization-kutsu (katso kohta sanomaesimerkit) palauttaa tiedon siitä, onko asiamiehellä oikeus asioida valitun päämiehen puolesta. Asiointioikeus ilmaistaan kentässä ”authorization”, jonka arvona palautetaan joko positiivinen päätös ALLOWED tai negatiivinen päätös DISALLOWED. Mikäli vastaus on DISALLOWED ja palvelulle on sallittu näyttää hylkäysperusteet, palautetaan ne listan reason-elementeissä. Mikäli kutsun käsittelyssä tapahtuu virhe, löytyy virheen syy exceptionMessage -elementissä.
Vastaussanoma kuvataan alla olevassa taulukossa.
Taulukko 4. Authorization-vastaussanoman kuvaus:
request Alkuperäinen kyselytieto palautetaan vastauksessa. kts. taulukko 4
authorization Päätöstieto onko puolesta-asiointi valitussa kontekstissa sallittu. ALLOWED tai DISALLOWED
reason Arvo ehdollinen. ”reason”-elementtejä voi olla useampia, yksi jokaista hylkäämisperustetta kohden.
Taulukko 5. AuthorizationList-kyselysanoman kuvaus
AuthorizationList-kutsu (katso ”Sanomaesimerkit”) 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. Mikäli palvelulle on sallittu näyttää mahdolliset hylkäysperusteet, palautetaan ne reason-elementeissä. Mikäli kutsun käsittelyssä tapahtuu virhe, löytyy virheen syy exceptionMessage-elementistä. Vastaussanoma kuvataan alla olevassa taulukossa.
Taulukko 6. AuthorizationList-vastaussanoman kuvaus
request Alkuperäinen kyselytieto palautetaan vastauksessa. ks. taulukko 5.
roles Asiat yksilöivät valtuustunnisteet, joissa asiamiehellä on asiointioikeus päämiehen puolesta. role ”ALL”, n * role issue
exceptionMessage Mahdollinen virheviesti. merkkijono
Kohdan 6 vastauksessa on principalId niminen tarkenne, joka on tyyppiä PRINCIPAL_ID ja arvo (hetu tai Y-tunnus) kertoo valtuuttajan. Vastauksessa on myös subOrganization niminen tarkenne, joka on tyyppiä DEFAULT ja jonka matcherType on KATSO_SUB_ORGANIZATION. Tarkenteen nimen perusteella valtuus on rajattu koskemaan tiettyä aliorganisaatiota ja matcherTypen perusteella voidaan päätellä, että valtuus voi tulla joko Valtuusrekisteristä tai Katso-palvelusta.
Authorization – puolesta-asiointioikeushaku
<id xmlns="http://x-road.eu/xsd/xroad.xsd">875910ef-d522-4fb6-954e-2816d7fd9ff5</id>
<userId xmlns="http://x-road.eu/xsd/xroad.xsd">requesting_enduser_id</userId>
<ns3:memberCode>member_code</ns3:memberCode>
<ns3:subsystemCode>subsys_code</ns3:subsystemCode>
<ns3:serviceCode>rovaService</ns3:serviceCode>
<ns3:rovaAuthorizationService xmlns:ns2="http://x-road.eu/xsd/identifiers"
xmlns:ns3="http://xml.vrk.fi/ws/Rova/Authorization/Entities"
<principalIdentifier>ppkkvv-yyyy</principalIdentifier>
<issue>http://www.yso.fi/onto/rova/p9239</issue>
</ns3:rovaAuthorizationService>
<client ns3:objectType="SUBSYSTEM" xmlns="http://x-road.eu/xsd/xroad.xsd" xmlns:ns3="http://x-road.eu/xsd/identifiers">
<service ns3:objectType="SERVICE" xmlns="http://x-road.eu/xsd/xroad.xsd" xmlns:ns3="http://x-road.eu/xsd/identifiers">
<ns4:rovaAuthorizationServiceResponse xmlns:ns2="http://x-road.eu/xsd/identifiers" xmlns:ns3="http://x-road.eu/xsd/xroad.xsd" xmlns:ns4="http://xml.vrk.fi/ws/Rova/Authorization/Entities">
<authorization>ALLOWED</authorization>
</ns4:rovaAuthorizationServiceResponse>
AuthorizationList – valtuustunnistehaku
<ns3:rovaAuthorizationListService xmlns:ns2="http://x-road.eu/xsd/identifiers"
xmlns:ns3="http://xml.vrk.fi/ws/Rova/AuthorizationList/Entities"
</ns3:rovaAuthorizationListService>
<ns4:rovaAuthorizationListServiceResponse xmlns:ns2="http://x-road.eu/xsd/identifiers" xmlns:ns3="http://x-road.eu/xsd/xroad.xsd" xmlns:ns4="http://xml.vrk.fi/ws/Rova/AuthorizationList/Entities">
<role>http://valtuusrekisteri.suomi.fi/p58780</role>
<role>http://valtuusrekisteri.suomi.fi/p55459</role>
<role>http://valtuusrekisteri.suomi.fi/p64592</role>
<role>http://valtuusrekisteri.suomi.fi/p53490</role>
</ns4:rovaAuthorizationListServiceResponse>
Versio nro
1.0 Dokumentti luotu 29.04.15 / JK
1.2 Sisältöä lisätty 09.09.15 / JK
1.3 Muokattu julkaistavaksi 23.09.15 / AU, NP
2.0 Dokumentti päivitetty 31.05.16 / NP
2.1 UserId kentän sisältömääritykseen lisätty vaatimus,
ettei kentässä saa välittyä henkilötunnusta. 02.11.16 / NP
2.2 Lisätty kohtaan 2 huomio, etteivät kaikki rajapinnat ole välttämättä luvitettuja asiakkaalle. 27.02.17 / NP
2.3 Lisätty sanomaesimerkkeihin protocolVersion-header 06.03.17 / NP
2.4 Päivitetty dokumentti AuthorizationList -rajapinnan kuvauksella. 04.12.17 / NP
2.5 Päivitetty dokumentti tarkenteiden osalta. 08.04.19 / NP