Suomi.fi-valtuudet –
Kyselyn rajapintakuvaus, yrityksen puolesta asiointi

Print Friendly, PDF & Email
 


1. Johdanto

Tämä dokumentti käsittelee yrityksen puolesta asioinnin Valtuudet-kyselyn rajapintakuvauksen sekä kutsurajapinnan esimerkkitapaukset.

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 yrityksen puolesta asiointiin OrganizationalRoles-rajapinnan. Rajapinta tarjotaan palveluväylän (XRoad6) kautta.  XRoad SOAP-otsakkeita käytetään palveluvaylä-yhteyden lisäksi palvelun (client header) ja loppukäyttäjän (userId) tunnistamiseen Suomi.fi-valtuuksissa.

 Taulukko 1. Suomi.fi-valtuudet -palvelun tarjoamat rajapinnat

Rajapinta
Kuvaus
wsdl
versio pvm
OrganizationalRoles Puolesta-asioijan roolit kysely henkilön tunnisteen perusteella orgroles.wsdl 12.05.2016

Huom! Sallitut rajapinnat määritellään käyttöönoton yhteydessä, joten kaikki tarjotut rajapinnat eivät välttämättä ole asiakasorganisaation käytettävissä.

Rajapintakuvauksissa viitataan lisäksi seuraaviin X-Roadin skeema tiedostoihin: xroad6.xsd ja xroad6identifiers.xsd.

3. X-Road-6 attribuutit

Oheisessa taulukossa on lueteltu X-Road v6 -otsakkeet, jotka on asetettava rooli ja valtuutuspalvelua 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 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.

Huom! Ylläkuvatun taulukon kenttien pakollisuus saatta erota X-Road-tiedonsiirtoprotokolla -dokumentissa mainituista.

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

4. Kutsukuvaus: OrganizationalRoles – roolit organisaatioissa

Kutsusanoma

Kutsu sisältää valtuutettavan tahon (puolesta-asioija) tunnisteen (delegateIdentifier) sekä valinnaisesti organisaatioden tunnisteita.

Taulukko 3. OrganizationalRoles-kyselysanoman kuvaus

Pääelementti
Elementin nimi
Kuvaus
Arvojoukko
request
delegateIdentifier Pakollinen tieto. Puolesta-asioijan eli asiamiehen yksilöllinen tunniste hetu
organizationIdentifier Haettavan organisaation tunniste (Y-tunnus). Voi olla useita. y-tunnus

Vastaussanoma

OrganizationalRoles -kutsu palauttaa listan puolesta-asioijan organisaatioista ja niihin liittyvistä rooleista. Mikäli osa rooleista jää selvittämättä esim. etäkutsun timeout tilanteen takia, laitetaan SOAP-vastauksen exceptionMessage -kenttään arvo incomplete. Mikäli kutsun käsittelyssä tapahtuu virhe, löytyy virheen syy exceptionMessage -kentässä.

Taulukko 4. OrganizationalRoles-vastaussanoman kuvaus

Pääelementti

Elementin nimi

Kuvaus
Arvojoukko
response
 organizationList  Lista organisaatioista  Lista n*[organization] tai tyhjä
 exceptionMessage  Mahdollinen virheviesti  Merkkijono. Arvo on ’incomplete’, jos osa organisaation rooleista jää selvittämättä.

 

Taulukko 5. OrganizationList-elementin kuvaus

Pääelementti

Elementin nimi

Kuvaus
Arvojoukko
organization
organizationIdentifier Organisaation tunniste (Y-tunnus)  y-tunnus
name Organisaation nimi organisaation nimi
roles Listaus rooleista Lista n*[role [”NIMKO”, ”TJ”, String]]

5. Sanomaesimerkit

OrgRoles – Haetaan puolesta-asioijan yritysroolit

<!-- 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">6a85dd42-04e4-42fa-ae2a-0ae646ad0956</id>
        <protocolVersion xmlns="http://x-road.eu/xsd/xroad.xsd">4.0</protocolVersion>
        <userId xmlns="http://x-road.eu/xsd/xroad.xsd">kela-rova-user</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>xxxxxxx-x</ns3:memberCode>
            <ns3:subsystemCode>subsys</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>xxxxxxx-x</ns3:memberCode>
            <ns3:subsystemCode>subsys</ns3:subsystemCode>
            <ns3:serviceCode>rovaOrganizationalRolesService</ns3:serviceCode>
            <ns3:serviceVersion>v1</ns3:serviceVersion>
        </service>
    </SOAP-ENV:Header>
    <S:Body>
        <ns2:rovaOrganizationalRolesService
            xmlns:ns2="http://xml.vrk.fi/ws/Rova/OrgRoles/Entities" xmlns:ns3="http://x-road.eu/xsd/identifiers"
            xmlns:ns4="http://x-road.eu/xsd/xroad.xsd">
            <request>
                <delegateIdentifier>ppkkvv-xxxx</delegateIdentifier>
                <!--
                <organizationIdentifier>aaaaaaa-a</organizationIdentifier>
                <organizationIdentifier>bbbbbbb-b</organizationIdentifier>
                -->
            </request>
        </ns2:rovaOrganizationalRolesService>
    </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">6a85dd42-04e4-42fa-ae2a-0ae646ad0956</id>
      <protocolVersion xmlns="http://x-road.eu/xsd/xroad.xsd">4.0</protocolVersion>
      <userId xmlns="http://x-road.eu/xsd/xroad.xsd">kela-rova-user</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>xxxxxxx-x</ns3:memberCode>
         <ns3:subsystemCode>subsys</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>xxxxxxx-x</ns3:memberCode>
         <ns3:subsystemCode>subsys</ns3:subsystemCode>
         <ns3:serviceCode>rovaOrganizationalRolesService</ns3:serviceCode>
         <ns3:serviceVersion>v1</ns3:serviceVersion>
      </service>
      <ns3:requestHash algorithmId="http://www.w3.org/2001/04/xmlenc#sha512" xmlns:ns3="http://x-road.eu/xsd/xroad.xsd">fhN8bdnbHRPjbYEbm7rannc0oImF9szcU4+bXZVpIRCCzUcMlNIZhjt2I0NNwXK7vacVsuOiFLXMsIm4DvzoTw==</ns3:requestHash>
   </SOAP-ENV:Header>
   <S:Body>
      <ns4:rovaOrganizationalRolesServiceResponse 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/OrgRoles/Entities">
         <request>
            <delegateIdentifier>ppkkvv-xxxx</delegateIdentifier>
         </request>
         <response>
            <organizationList>
               <organization>
                  <organizationIdentifier>aaaaaaa-a</organizationIdentifier>
                  <name>Maanrakennus Ari Eerola T:mi</name>
                  <roles>
                     <role>NIMKO</role>
                  </roles>
               </organization>
               <organization>
                  <organizationIdentifier>bbbbbbb-b</organizationIdentifier>
                  <name>Rova Oy 1</name>
                  <roles>
                     <role>NIMKO</role>
                  </roles>
               </organization>
            </organizationList>
         </response>
      </ns4:rovaOrganizationalRolesServiceResponse>
   </S:Body>
</S:Envelope>

 


 

Dokumentin tiedot

Versionro Mitä tehty Pvm/

henkilö

 1.0 Dokumentti luotu 3.2.16/NY
 1.1  Dokumenttia päivitetty  16.05.2016/NP
 1.2  Dokumenttia päivitetty  20.05.2016/NP
1.3 Dokumenttia päivitetty 31.05.2016/NP
1.4 Dokumenttia päivitetty 26.07.2016/TR-K
1.5
UserId kentän sisältömääritykseen lisätty vaatimus ettei kentässä saa välittyä henkilötunnusta.
3.11.2016/NP
1.6
Lisätty kohtaan 2 huomio etteivät kaikki rajapinnat ole välttämättä luvitettuja asiakkaalle.
27.02.2017/NP
1.7
Lisätty sanomaesimerkkiin protocolVersion-header
06.03.2017/NP

27.02.2017/NP

Yksilöintitunnus: x