Kyselyn rajapintakuvaus, organisaation valtuudet
Suomi.fi-valtuudet –
Sisältö
1. Johdanto
Tämä dokumentti käsittelee Suomi.fi-valtuuksien organisaatiovaltuuskyselyn 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.
Suomi.fi-valtuudet on palvelu, jonka avulla voidaan luotettavasti tarkistaa henkilön tai yrityksen valtuudet, valtakirjat ja oikeudet asioida sähköisesti toisen henkilön tai edustamansa yrityksen puolesta ajasta ja paikasta riippumatta.
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 OrganizationalMandates -rajapinnan. Rajapinta tarjotaan palveluväylän (XRoad6) kautta. XRoad SOAP-otsakkeita käytetään 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:
OrganizationalMandates | Puolesta-asioijan valtuudet kysely yrityksen tunnisteen perusteella | orgmandates.wsdl | 1.3.2018 |
(Huom. Sallitut rajapinnat määritellään käyttöönoton yhteydessä, joten kaikki tarjotut rajapinnat eivät välttämättä ole asiakkaan käytettävissä.)
Rajapintakuvauksissa viitataan lisäksi seuraaviin X-Road:in skeema tiedostoihin: xroad6.xsd ja xroad6identifiers.xsd.
3. X-Road-6 -attribuutit
Oheisessa taulukossa on lueteltu X-Road v6 -otsakkeet, jotka on asetettava Valtuudet-palvelua kutsuttaessa:
Taulukko 2. X-Roadin attribuutit Valtuudet-kyselyissä
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. |
(Huom. Ylläkuvatun taulukon kenttien pakollisuus saattaa erota X-Roadin tiedonsiirtoprotokolla-dokumentissa mainituista.)
X-Road-protokollan tarkempi kuvaus: X-Road v6.4 -tiedonsiirtoprotokolla
4. Kutsukuvaus: OrganizationalMandates – organisaation valtuudet
Kutsusanoma
Kutsu sisältää valtuutetun tahon tunnisteen (delegate) sekä yhden tai useamman mahdollisen valtuuttajaorganisaation (principal) tunnisteen.
Taulukko 3. OrganizationalMandates-kyselysanoman kuvaus
request | |||
delegate | Pakollinen tieto. Valtuutetun organisaation yksilöllinen tunniste | y-tunnus | |
principal | Pakollinen tieto. Haettavan organisaation tunniste (Y-tunnus). Voi olla useita. | y-tunnus |
Vastaussanoma
OrganizationalMandates -kutsu palauttaa listan asioivalle organisaatiolle myönnetyistä valtuuksista. Valtuudet on ryhmitelty myöntäneiden organisaatioiden mukaan. Mikäli kutsun käsittelyssä tapahtuu virhe, löytyy virheen syy exceptionMessage -kentässä.
Taulukko 1. OrganizationalMandates-vastaussanoman kuvaus
response | |||
principalList | Lista organisaatioista. | Lista n*[principal] tai tyhjä | |
exceptionMessage | Mahdollinen virheviesti | merkkijono |
PrincipalList-elementin kuvaus:
principal | |||
principal | Valtuuttava organisaatio ja liittyvät valtuudet | principal – issue |
Principal-elementin kuvaus:
principal | |||
principal | Valtuuttavan organisaation tunniste | y-tunnus | |
issue | Liittyvä valtuus. Voi olla useita. Elementti jää pois, jos valtuuksia ei ole. | valtuuskoodi |
5. Sanomaesimerkit
<!-- request --> <?xml version= '1.0' encoding= 'UTF-8' ?> <S:Envelope xmlns:S= "http://schemas.xmlsoap.org/soap/envelope/" <SOAP-ENV:Header> ns3:objectType= "SUBSYSTEM" > <ns3:xRoadInstance>FI-DEV</ns3:xRoadInstance> <ns3:memberClass>COM</ns3:memberClass> <ns3:memberCode> 5555555 - 6 </ns3:memberCode> <ns3:subsystemCode>kaparova3</ns3:subsystemCode> </client> ns3:objectType= "SERVICE" > <ns3:xRoadInstance>FI-DEV</ns3:xRoadInstance> <ns3:memberClass>COM</ns3:memberClass> <ns3:memberCode> 5555555 - 6 </ns3:memberCode> <ns3:subsystemCode>kaparova</ns3:subsystemCode> <ns3:serviceCode>rovaOrgMandatesService</ns3:serviceCode> <ns3:serviceVersion>v1</ns3:serviceVersion> </service> </SOAP-ENV:Header> <S:Body> <ns2:rovaOrgMandatesService xmlns:ns2= "http://xml.vrk.fi/ws/Rova/OrgMandates/Entities" xmlns:ns3= "http://x-road.eu/xsd/identifiers" <request> <delegate> 6666666 - 5 </delegate> <principal> 9999999 - 2 </principal> <principal> 8888888 - 3 </principal> <principal> 7777777 - 4 </principal> </request> </ns2:rovaOrgMandatesService> </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" xmlns:S= "http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV= "http://schemas.xmlsoap.org/soap/envelope/" >6a85dd42-04e4-42fa-ae2a-0ae646ad0956</id> <requestHash xmlns= "http://x-road.eu/xsd/xroad.xsd" xmlns:S= "http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV= "http://schemas.xmlsoap.org/soap/envelope/" algorithmId= "http://www.w3.org/2001/04/xmlenc#sha512" >Ryi6rQMaG6BDbXoLCSZbriP5IRMw0EOABKnslSvGMNoBK89k5b0b8Qj3GK/ 2 +BSJZ3jF7O2LkX5DGaobzdPIIg==</requestHash> <protocolVersion xmlns= "http://x-road.eu/xsd/xroad.xsd" xmlns:S= "http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV= "http://schemas.xmlsoap.org/soap/envelope/" > 4.0 </protocolVersion> <userId xmlns= "http://x-road.eu/xsd/xroad.xsd" xmlns:S= "http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV= "http://schemas.xmlsoap.org/soap/envelope/" >kela-rova-user</userId> <client xmlns= "http://x-road.eu/xsd/xroad.xsd" xmlns:S= "http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV= "http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns3= "http://x-road.eu/xsd/identifiers" ns3:objectType= "SUBSYSTEM" > <ns3:xRoadInstance>FI-DEV</ns3:xRoadInstance> <ns3:memberClass>COM</ns3:memberClass> <ns3:memberCode> 5555555 - 6 </ns3:memberCode> <ns3:subsystemCode>kaparova3</ns3:subsystemCode> </client> <service xmlns= "http://x-road.eu/xsd/xroad.xsd" xmlns:S= "http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV= "http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns3= "http://x-road.eu/xsd/identifiers" ns3:objectType= "SERVICE" > <ns3:xRoadInstance>FI-DEV</ns3:xRoadInstance> <ns3:memberClass>COM</ns3:memberClass> <ns3:memberCode> 5555555 - 6 </ns3:memberCode> <ns3:subsystemCode>kaparova</ns3:subsystemCode> <ns3:serviceCode>rovaOrgMandatesService</ns3:serviceCode> <ns3:serviceVersion>v1</ns3:serviceVersion> </service> </SOAP-ENV:Header> <S:Body> <ns4:rovaOrgMandatesServiceResponse 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/OrgMandates/Entities" > <request> <delegate> 6666666 - 5 </delegate> <principal> 9999999 - 2 </principal> <principal> 8888888 - 3 </principal> <principal> 7777777 - 4 </principal> </request> <response> <principalList> <principal> <principal> 9999999 - 2 </principal> <issue>http: //valtuusrekisteri.suomi.fi/p1</issue> </principal> <principal> <principal> 8888888 - 3 </principal> <issue>http: //valtuusrekisteri.suomi.fi/p1</issue> <issue>http: //valtuusrekisteri.suomi.fi/p2</issue> </principal> <principal> <principal> 7777777 - 4 </principal> </principal> </principalList> </response> </ns4:rovaOrgMandatesServiceResponse> </S:Body> </S:Envelope> |
Dokumentin tiedot
Versionro | Mitä tehty | Pvm/henkilö |
---|---|---|
1.0 | Dokumentti luotu | 16.03.2018/EJ |