Suomi.fi-valtuudet –
Kyselyn rajapintakuvaus, henkilön puolesta asiointi

Print Friendly, PDF & Email
 


1 Johdanto

1.1 Kyselyn  rajapintakuvaus

Tässä dokumentissa kuvataan Suomi.fi-valtuuksien valtuudet-kyselyn rajapintakuvaus ja kutsurajapinnan esimerkkitapaukset henkilön puolesta asioinnin (HPA) osalta.

1.2 Käsitteet

Asiamies on henkilö, jonka toinen on valtuuttanut toimimaan puolestaan eli päämiehen puolesta-asioija.

Suomi.fi-palveluväylä on standardoitu tiedonsiirtokanava, joka tarjoaa vakioidun tavan tietojen siirtoon organisaatioiden välillä sekä mahdollistaa turvallisten palvelukokonaisuuksien rakentamisen.

Päämies on valtuuttaja eli henkilö, jonka puolesta asiamies asioi.

SOAP (Simple Object Access Protocol) on XML-kieleen pohjautuva tietoliikenneprotokolla, jota X-Road-ratkaisun liityntäpalvelimen rajapintatoteutuksessa käytetään.

X-Road on Virossa kehitetty ja käytössä oleva ohjelmisto, joka toimii osana Suomi-fi-palveluväylän teknistä ydintä

2 Rajapinnan kutsuminen

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.

Taulukko 1. Suomi.fi-valtuuksien tarjoamat rajapinnat:

Rajapinta
Kuvaus
wsdl
versio pvm
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.

3 X-Road-6 attribuutit

Oheisessa taulukossa on lueteltu X-Road v6 -otsakkeet, jotka on asetettava Suomi.fi-valtuuksia kutsuttaessa:

Taulukko 2. X-Road attribuutit Suomi.fi-valtuudet-kyselyissä:

Kenttä
Pakollinen
 Lisätietoja
service (objectType=SERVICE) x Sisältää kentät: xRoadInstance, memberClass, memberCode, subSystemCode, serviceCode ja serviceVersion.
client (objectType=SUBSYSTEM) x Sisältää kentät: xRoadInstance, memberClass, memberCode ja subSystemCode.
userId x Loppukäyttäjän tunnistava tunniste, ei kuitenkaan henkilötunnus. Esim. tunnistustapahtuman assertio tai vastaava.
id x Kyselytapahtuman tunnistava yksilöllinen tunniste.
issue Mikäli rajapintakutsut liittyvät samaan tapahtumaan, tulee niillä olla sama issue-tunniste.

X-Road protokollan tarkempi kuvaus: Suomi.fi-palveluväylä – X-Road-tiedonsiirtoprotokolla

4 Kutsukuvaus: Authorization – asiointioikeushaku

Kutsusanoma

Kutsu sisältää asiamiehen tunnisteen (delegateIdentifier) sekä päämiehen tunnisteen (principalIdentifier).

Taulukko 3. Authorization-kyselysanoman kuvaus

Pääelementti
Elementin nimi
Kuvaus
Arvojoukko
request
delegateIdentifier Pakollinen tieto. Puolesta-asioijan eli asiamiehen yksilöllinen tunniste hetu
principalIdentifier Pakollinen tieto. Puolesta-asioitavan eli päämiehen yksilöllinen tunniste hetu
issue Valtuutuksen uri. Voi olla useita. uri

Vastaussanoma

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:

Pääelementti
Elementin nimi
Kuvaus
Arvojoukko
request Alkuperäinen kyselytieto palautetaan vastauksessa. kts. taulukko 4
response
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.

Kentän käytöstä sovitaan palvelusopimuksessa erikseen.

n* reason[rule, value].

Kenttä rule sisältää kyseisen säännön tunnisteen ja value syyn lokalisointiavaimen

exceptionMessage Mahdollinen virheviesti merkkijono

5 Kutsukuvaus: AuthorizationList – valtuustunnistehaku

Kutsusanoma

Kutsu sisältää asiamiehen tunnisteen (delegateIdentifier) sekä päämiehen tunnisteen (principalIdentifier).

Taulukko 5. AuthorizationList-kyselysanoman kuvaus

Pääelementti Elementin nimi Kuvaus Arvojoukko
 request
 delegateIdentifier Pakollinen tieto. Puolesta-asioijan eli asiamiehen yksilöllinen tunniste  hetu
 principalIdentifier Pakollinen tieto. Puolesta-asioitavan eli päämiehen yksilöllinen tunniste  hetu

Vastaussanoma

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

Pääelementti Elementin nimi Kuvaus Arvojoukko
 request  Alkuperäinen kyselytieto palautetaan vastauksessa.  ks. taulukko 5.
 response
 roles  Asiat yksilöivät valtuustunnisteet, joissa asiamiehellä on asiointioikeus päämiehen puolesta.  role ”ALL”, n * role issue
reason Arvo ehdollinen. ”reason”-elementtejä voi olla useampia, yksi jokaista hylkäämisperustetta kohden.
Kentän käytöstä sovitaan palvelusopimuksessa erikseen.
n* reason[rule, value].
Kenttä rule sisältää kyseisen säännön tunnisteen ja value syyn lokalisointiavaimen
 exceptionMessage Mahdollinen virheviesti.  merkkijono

6 Sanomaesimerkit

Authorization – puolesta-asiointioikeushaku

<!--Request-->
<?xml version='1.0' encoding='UTF-8'?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"
            xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header>
        <id xmlns="http://x-road.eu/xsd/xroad.xsd">875910ef-d522-4fb6-954e-2816d7fd9ff5</id>
        <protocolVersion xmlns="http://x-road.eu/xsd/xroad.xsd">4.0</protocolVersion>
        <userId xmlns="http://x-road.eu/xsd/xroad.xsd">requesting_enduser_id</userId>
        <client xmlns="http://x-road.eu/xsd/xroad.xsd" xmlns:ns3="http://x-road.eu/xsd/identifiers"
                ns3:objectType="SUBSYSTEM">
            <ns3:xRoadInstance>FI-DEV</ns3:xRoadInstance>
            <ns3:memberClass>COM</ns3:memberClass>
            <ns3:memberCode>member_code</ns3:memberCode>
            <ns3:subsystemCode>subsys_code</ns3:subsystemCode>
        </client>
        <service xmlns="http://x-road.eu/xsd/xroad.xsd" xmlns:ns3="http://x-road.eu/xsd/identifiers"
                 ns3:objectType="SERVICE">
            <ns3:xRoadInstance>FI-DEV</ns3:xRoadInstance>
            <ns3:memberClass>COM</ns3:memberClass>
            <ns3:memberCode>member_code</ns3:memberCode>
            <ns3:subsystemCode>subsys_code</ns3:subsystemCode>
            <ns3:serviceCode>rovaService</ns3:serviceCode>
            <ns3:serviceVersion>v1</ns3:serviceVersion>
        </service>
    </SOAP-ENV:Header>
    <S:Body>
        <ns3:rovaAuthorizationService xmlns:ns2="http://x-road.eu/xsd/identifiers"
                                      xmlns:ns3="http://xml.vrk.fi/ws/Rova/Authorization/Entities"
                                      xmlns:ns4="http://x-road.eu/xsd/xroad.xsd">
            <request>
                <delegateIdentifier>ppkkvv-xxxx</delegateIdentifier>
                <principalIdentifier>ppkkvv-yyyy</principalIdentifier>
                <issue>http://www.yso.fi/onto/rova/p9239</issue>
            </request>
        </ns3:rovaAuthorizationService>
    </S:Body>
</S:Envelope>
 
 <!--Response-->
<?xml version='1.0' encoding='UTF-8'?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header>
      <id xmlns="http://x-road.eu/xsd/xroad.xsd">875910ef-d522-4fb6-954e-2816d7fd9ff5</id>
      <protocolVersion xmlns="http://x-road.eu/xsd/xroad.xsd">4.0</protocolVersion>
      <userId xmlns="http://x-road.eu/xsd/xroad.xsd">requesting_enduser_id</userId>
      <client ns3:objectType="SUBSYSTEM" xmlns="http://x-road.eu/xsd/xroad.xsd" xmlns:ns3="http://x-road.eu/xsd/identifiers">
         <ns3:xRoadInstance>FI-DEV</ns3:xRoadInstance>
         <ns3:memberClass>COM</ns3:memberClass>
         <ns3:memberCode>member_code</ns3:memberCode>
         <ns3:subsystemCode>subsys_code</ns3:subsystemCode>
      </client>
      <service ns3:objectType="SERVICE" xmlns="http://x-road.eu/xsd/xroad.xsd" xmlns:ns3="http://x-road.eu/xsd/identifiers">
         <ns3:xRoadInstance>FI-DEV</ns3:xRoadInstance>
         <ns3:memberClass>COM</ns3:memberClass>
         <ns3:memberCode>member_code</ns3:memberCode>
         <ns3:subsystemCode>subsys_code</ns3:subsystemCode>
         <ns3:serviceCode>rovaService</ns3:serviceCode>
         <ns3:serviceVersion>v1</ns3:serviceVersion>
      </service>
   </SOAP-ENV:Header>
   <S:Body>
      <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">
         <request>
            <delegateIdentifier>ppkkvv-xxxx</delegateIdentifier>
            <principalIdentifier>ppkkvv-yyyy</principalIdentifier>
            <issue>http://www.yso.fi/onto/rova/p9239</issue>
         </request>
         <response>
            <authorization>ALLOWED</authorization>
         </response>
      </ns4:rovaAuthorizationServiceResponse>
   </S:Body>
</S:Envelope>

AuthorizationList – valtuustunnistehaku

<!--Request-->
<?xml version='1.0' encoding='UTF-8'?>
            xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header>
        <id xmlns="http://x-road.eu/xsd/xroad.xsd">875910ef-d522-4fb6-954e-2816d7fd9ff5</id>
        <protocolVersion xmlns="http://x-road.eu/xsd/xroad.xsd">4.0</protocolVersion>
        <userId xmlns="http://x-road.eu/xsd/xroad.xsd">requesting_enduser_id</userId>
        <client xmlns="http://x-road.eu/xsd/xroad.xsd" xmlns:ns3="http://x-road.eu/xsd/identifiers"
                ns3:objectType="SUBSYSTEM">
            <ns3:xRoadInstance>FI-DEV</ns3:xRoadInstance>
            <ns3:memberClass>COM</ns3:memberClass>
            <ns3:memberCode>member_code</ns3:memberCode>
            <ns3:subsystemCode>subsys_code</ns3:subsystemCode>
        </client>
        <service xmlns="http://x-road.eu/xsd/xroad.xsd" xmlns:ns3="http://x-road.eu/xsd/identifiers"
                 ns3:objectType="SERVICE">
            <ns3:xRoadInstance>FI-DEV</ns3:xRoadInstance>
            <ns3:memberClass>COM</ns3:memberClass>
            <ns3:memberCode>member_code</ns3:memberCode>
            <ns3:subsystemCode>subsys_code</ns3:subsystemCode>
            <ns3:serviceCode>rovaService</ns3:serviceCode>
            <ns3:serviceVersion>v1</ns3:serviceVersion>
        </service>
    </SOAP-ENV:Header>
    <S:Body>
        <ns3:rovaAuthorizationListService xmlns:ns2="http://x-road.eu/xsd/identifiers"
                                      xmlns:ns3="http://xml.vrk.fi/ws/Rova/AuthorizationList/Entities"
                                      xmlns:ns4="http://x-road.eu/xsd/xroad.xsd">
            <request>
                <delegateIdentifier>ppkkvv-xxxx</delegateIdentifier>
                <principalIdentifier>ppkkvv-yyyy</principalIdentifier>
            </request>
        </ns3:rovaAuthorizationListService>
    </S:Body>
</S:Envelope>
 <!--Response-->
<?xml version='1.0' encoding='UTF-8'?>
   <SOAP-ENV:Header>
      <id xmlns="http://x-road.eu/xsd/xroad.xsd">875910ef-d522-4fb6-954e-2816d7fd9ff5</id>
      <protocolVersion xmlns="http://x-road.eu/xsd/xroad.xsd">4.0</protocolVersion>
      <userId xmlns="http://x-road.eu/xsd/xroad.xsd">requesting_enduser_id</userId>
      <client ns3:objectType="SUBSYSTEM" xmlns="http://x-road.eu/xsd/xroad.xsd" xmlns:ns3="http://x-road.eu/xsd/identifiers">
         <ns3:xRoadInstance>FI-DEV</ns3:xRoadInstance>
         <ns3:memberClass>COM</ns3:memberClass>
         <ns3:memberCode>member_code</ns3:memberCode>
         <ns3:subsystemCode>subsys_code</ns3:subsystemCode>
      </client>
      <service ns3:objectType="SERVICE" xmlns="http://x-road.eu/xsd/xroad.xsd" xmlns:ns3="http://x-road.eu/xsd/identifiers">
         <ns3:xRoadInstance>FI-DEV</ns3:xRoadInstance>
         <ns3:memberClass>COM</ns3:memberClass>
         <ns3:memberCode>member_code</ns3:memberCode>
         <ns3:subsystemCode>subsys_code</ns3:subsystemCode>
         <ns3:serviceCode>rovaService</ns3:serviceCode>
         <ns3:serviceVersion>v1</ns3:serviceVersion>
      </service>
   </SOAP-ENV:Header>
   <S:Body>
      <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">
         <request>
            <delegateIdentifier>ppkkvv-xxxx</delegateIdentifier>
            <principalIdentifier>ppkkvv-yyyy</principalIdentifier>
         </request>
         <response>
            <roles>
               <role>ALL</role>
               <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>
            <roles>
         </response>
      </ns4:rovaAuthorizationListServiceResponse>
   </S:Body>
</S:Envelope>

 


 Dokumentin tiedot

Versio nro Mitä tehty Pvm/henkilö
 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

Yksilöintitunnus: JTO21