Suomi.fi-valtuudet –
Kyselyn rajapintakuvaus, organisaation valtuudet

Print Friendly, PDF & Email


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'?>
    <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: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"?>
    <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>
            <ns3:xRoadInstance>FI-DEV</ns3:xRoadInstance>
            <ns3:memberClass>COM</ns3:memberClass>
            <ns3:memberCode>5555555-6</ns3:memberCode>
            <ns3:subsystemCode>kaparova3</ns3:subsystemCode>
        </client>
            <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