Suomi.fi-valtuudet –
Kyselyn rajapintakuvaus, organisaation valtuudet

Sisältö

Suomi.fi-valtuudet – Kyselyn rajapintakuvaus, organisaation valtuudet

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

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>5555555-6</ns3:memberCode>
            <ns3:subsystemCode>kaparova3</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>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"
            xmlns:ns4="http://x-road.eu/xsd/xroad.xsd">
            <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

Suomi.fi-valtuudet – Kyselyn rajapintakuvaus, organisaation valtuudet