Valtuustarkistuskyselyn rajapintakuvaus henkilön asioidessa yrityksen puolesta – OrganizationalRoles-kysely

Tässä artikkelissa esitellään Suomi.fi-valtuuksien valtuustarkistuskyselyn rajapintakuvaus, kun henkilö asioi yrityksen puolesta. Artikkelissa kerrotaan kyselyssä käytettävän OrganizationalRoles-rajapinnan kutsumisesta sekä kuvataan kutsu- ja vastaussanomien sisältöä.

Rajapinnan kutsuminen

Valtuudet-palvelun tarjoaman OrganizationalRoles-rajapinnan kautta tarkistetaan, onko henkilöllä oikeus asioida yrityksen puolesta ja millaisessa roolissa hän on yritykseen nähden. Rajapinta tarjotaan Palveluväylän (X-Road 6) kautta. X-Roadin SOAP-otsakkeita käytetään Palveluväylä-yhteyden lisäksi asiointipalvelun (client header) ja loppukäyttäjän (userId) tunnistamiseen Valtuudet-palvelussa.

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 skeematiedostoihin:

• X-Roadin skeematiedosto xroad6.xsdAvautuu uuteen ikkunaan.
• X-Roadin skeematiedosto xroad6identifiers.xsdAvautuu uuteen ikkunaan..

Liityntäkatalogissa:

• TestiympäristöAvautuu uuteen ikkunaan.
• TuotantoympäristöAvautuu uuteen ikkunaan.

X-Road 6 -attribuutit

Huom! Taulukon kenttien pakollisuus saattaa erota X-Roadin tiedonsiirtoprotokollasta.

• X-Road-tiedonsiirtoprotokollan kuvaus

OrganizationalRoles-rajapinnan kutsu- ja vastaussanomat

Kutsusanoma

OrganizationalRoles-rajapintaan lähetettävä kutsu (request) sisältää kaksi elementtiä:

• DelegateIdentifier-elementti yksilöi sen henkilön, jonka valtuus asioida yrityksen puolesta tarkistetaan.
• OrganizationIdentifier-elementti puolestaan yksilöi sen yrityksen, jonka puolesta henkilö haluaa asioida.

OrganizationIdentifier-elementtejä voi olla kutsusanomassa useita, eli yhdellä kutsusanomalla voidaan tarkistaa usean yrityksen myöntämät valtuudet.

Vastaussanoma

Vastauksena (response) kutsusanomaan OrganizationalRoles-rajapinta palauttaa listan (organizationList) asiamieheen liittyvistä yrityksistä ja hänen rooleistaan niissä. Jos osa rooleista jää selvittämättä esimerkiksi etäkutsun time out -tilanteen takia, vastauksen exceptionMessage-kentässä palautetaan arvo incomplete. Jos kutsun käsittelyssä tapahtuu virhe, virheen syy palautetaan exceptionMessage-kentässä.

Taulukossa on kuvattu organizationList-elementin tiedot. OrganizationList sisältää yhden tai useamman organization-elementin, joka ilmaisee valtuuttaneen yrityksen yritystunnuksen ja nimen sekä listauksen asiamiehen rooleista yrityksessä.

Taulukossa on kuvattu organization-elementin tiedot. Se sisältää kolme elementtiä: organizationIdentifier, name ja roles. OrganizationIdentifier ilmaisee valtuuttaneen yrityksen yritystunnuksen ja name yrityksen nimen. Roles taas kertoo, missä rooleissa asiamies toimii yrityksessä.

Tarkenteista

Tarkenteiden tyypit ja nimet on määritelty valtuusasioiden koodistossa. Jos valtuusasialle on määritelty tarkenteita, ne on lisätty vastauksessa valtuusasian tunnisteen perään avain-arvopareina:

1. PRINCIPAL_ID-tyyppisen tarkenteen arvo kertoo valtuuttajan tunnisteen.
2. DEFAULT-tyyppisen tarkenteen arvon merkitys riippuu asiayhteydestä, eikä järjestelmä ota siihen kantaa.

Alla esitetyn sanomaesimerkin vastauksessa on principalId-niminen tarkenne, joka on tyyppiä PRINCIPAL_ID. Sen arvo kertoo valtuuttajan. Vastauksessa on myös subOrganization-niminen tarkenne, joka on tyyppiä DEFAULT. Tarkenteen nimen perusteella valtuus on rajattu koskemaan tiettyä aliorganisaatiota.

Jos toimivalta on saatu edustamisvaltuuden kautta, valtuusasiaan liitetään edustettavan yrityksen yritystunnus fragmenttina. Esimerkiksi http://valtuusrekisteri.suomi.fi/palkkatietojen-ilmoittaminen#1234567-1 kertoo, että alkuperäinen valtuus on annettu yritykselle 1234567-1, joka on antanut edustamisvaltuuden kyselyn kohteena olleelle asiamiehelle.

Sanomaesimerkki

Seuraavassa on tämän artikkelin asioista koostettu esimerkki. Siitä käyvät ilmi rajapinnan kutsuminen sekä kutsu- ja vastaussanomat tarkistettaessa henkilön valtuuksia asioida yrityksen puolesta.

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-TEST</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-TEST</ns3:xRoadInstance>
            <ns3:memberClass>GOV</ns3:memberClass>
            <ns3:memberCode>0245437-2</ns3:memberCode>
            <ns3:subsystemCode>RolesAuthsServiceTest</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-TEST</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-TEST</ns3:xRoadInstance>
         <ns3:memberClass>GOV</ns3:memberClass>
         <ns3:memberCode>0245437-2</ns3:memberCode>
         <ns3:subsystemCode>RolesAuthsServiceTest</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>
               <organization>
                  <organizationIdentifier>ccccccc-c</organizationIdentifier>
                     <name>Pasilan Puu ja Pallo</name>
                     <roles>
                        <role>http://valtuusrekisteri.suomi.fi/palkkatietojen-ilmoittaminen?principalId=ccccccc-c&amp;subOrganization=123</role>
                        <role>http://valtuusrekisteri.suomi.fi/palkkatietojen-ilmoittaminen?principalId=ccccccc-c&amp;subOrganization=a%26b</role>
                     </roles>
               </organization>
            </organizationList>
         </response>
      </ns4:rovaOrganizationalRolesServiceResponse>
   </S:Body>
</S:Envelope>