Siirry suoraan sisältöön.
Suomi.fi-valtuudet

Web API -yhteys: Kehittäjän ohje

Artikkelissa kerromme, miten Web API -rajapintaliitos toteutetaan asiakasorganisaation asiointipalvelun ja Suomi.fi-valtuuksien välille.

  • Ohjeistus on suunnattu tekniselle asiantuntijalle.

Web API -rajapintaliitoksen avulla Valtuudet-palvelun valtuustarkistuskyselyt voidaan tehdä julkisen internetin kautta, jolloin erilliselle liityntäpalvelimelle ei ole tarvetta. Toteutuksen voi tehdä myös pelkän rajapintakuvauksen perusteella, mutta tästä artikkelista saattaa olla apua.

Esiehdot

Ennen kuin Web API -rajapintaliitoksen toteuttaminen asiakasorganisaation asiointipalvelun ja Valtuudet-palvelun välille voidaan aloittaa, seuraavien ehtojen tulee täyttyä:

  • Digi- ja väestötietoviraston Valtuudet-palvelun käyttöönotto on toimittanut asiakasorganisaatiolle Web API -rajapinnan käyttöön tarvittavat kolme tunnistetietoa: Web API Client ID, API Key ja OAuth-salasana.
  • Asiakasorganisaatio on toimittanut Digi- ja väestötietoviraston Valtuudet-palvelun käyttöönotoille paluuosoitteen. Paluuosoitteen tulee olla suojattu HTTPS-protokollalla, jos se osoittaa muuhun kuin localhostiin.
  • Teknisen toteutuksen tekijä asiakasorganisaatiossa on tutustunut seuraaviin aineistoihin: Web API -rajapintakuvaus

Rajapintaliitoksen käyttöönoton työvaiheet

Web API -rajapintaliitoksen tekninen käyttöönotto voidaan jakaa karkeasti seuraaviin työvaiheisiin:

  1. Rajapintakuvauksiin tutustuminen
  2. Tietoliikenneyhteyksien tarkistaminen testiympäristössä
  3. Rajapintojen kutsumisen testaaminen valmiin lähdekoodin avulla
  4. Rajapintojen kutsuminen ohjelmakoodista
  5. Toteutuksen verifiointi testiympäristössä
  6. Tietoliikenneyhteyksien tarkistaminen tuotantoympäristössä
  7. Toteutuksen verifiointi tuotantoympäristössä.

1. Rajapintakuvauksiin tutustuminen

Web API -rajapinta tarjoaa valintakäyttöliittymän, jonka kautta valitaan toisen puolesta asioinnin kohteet eli ne henkilöt, joita valtuuksien antaminen koskee. Web API -rajapinta tarjoaa myös REST-kyselyrajapinnat, joiden kautta tehdään asiointioikeuskyselyjä eli selvitetään, onko henkilöllä oikeus asioida toisen puolesta.

Rajapinnan kutsumisessa hyödynnetään REST-/JSON-rajapintoja, jotka on suojattu joko API Key- tai OAuth2 +API Key -suojauksella. Tutustu tarkemmin seuraaviin aineistoihin:

2. Tietoliikenneyhteyksien tarkistaminen testiympäristössä

Ennen Valtuudet-palvelun käyttöönoton teknisen toteutuksen aloittamista on hyvä tarkistaa, että tietoliikenneyhteydet toimivat asiakasorganisaation asiointipalvelun ja Valtuudet-palvelun Web API -rajapinnan välillä.

Valtuudet-palvelu edellyttää, että sen Web API -rajapintaan lähetettävien pyyntöjen header-osioon on liitetty tarvittavat tunnistetiedot ja tarkistesumma. Tietoliikenneyhteyden toimivuuden voi kuitenkin testata myös ilman tunnistetietoja ja tarkistesummaa käyttämällä selainta tai komentorivityökalua ja esimerkiksi alla näkyviä osoitteita. Tällöin vastaukseksi tulee ”Http Error 403 Forbidden”.

Palvelun osoite testiympäristössä

Yhteyspiste (rova_host):

  • https://asiointivaltuustarkastus.test.suomi.fi/

Esimerkki HPA (henkilön puolesta asiointi) -rekisteröintikutsusta:

  • https://asiointivaltuustarkastus.test.suomi.fi/service/hpa/user/register/ed4b7ae7/080297-915A?requestId=02fd35dc-99e6-477b-b6e2-03f02cbf3666

Tietoliikenneyhteyden tarkistaminen komentorivillä testiympäristössä

Voit tarkistaa testiympäristössä tietoliikenneyhteyden toimivuuden komentorivillä seuraavalla tavalla:

$ wget https://asiointivaltuustarkastus.test.suomi.fi/service/hpa/user/register/ed4b7ae7/080297-915A?requestId=02fd35dc-99e6-477b-b6e2-03f02cbf3666
--2017-02-08 14:37:32-- https://asiointivaltuustarkastus.test.suomi.fi/service/hpa/user/register/ed4b7ae7/080297-915A?requestId=02fd35dc-99e6-477b-b6e2-03f02cbf3666
Selvitetään osoitetta asiointivaltuustarkastus.test.suomi.fi (asiointivaltuustarkastus.test.suomi.fi)... 131.207.22.80
Yhdistetään palvelimeen asiointivaltuustarkastus.test.suomi.fi (asiointivaltuustarkastus.test.suomi.fi)|131.207.22.80|:443... yhdistetty.
HTTP-pyyntö lähetetty, odotetaan vastausta... 403 Forbidden
2017-02-08 14:37:32 VIRHE 403: Forbidden.


Jos yhteys toimii, komentoriville tulostuu

131.207.22.80|:443… yhdistetty.

3. Rajapintojen kutsumisen testaaminen valmiin lähdekoodin avulla

Web API -rajapinnan kutsumiseen on saatavissa valmis lähdekoodi kahdella ohjelmointikielellä. Lähdekoodeja voi hyödyntää testaamiseen ja oman toteutuksensa pohjaksi.

Valmiiden lähdekoodien käyttäminen ei ole välttämätöntä, mutta se saattaa helpottaa testaamista ja toteutusta.

Node.js Clientin käyttäminen testauksessa

Web API Node Client sisältää kaikki tarvittavat toiminnallisuudet asiointipalvelun asiakaspuolen toteuttamiseen. Se on tarkoitettu palvelun testaamiseen, siihen tutustumiseen ja sen toteutuksen tueksi. Sitä ei ole suunniteltu tuotantokäyttöön, joten sitä ei pidä missään tapauksessa tuotannollistaa sellaisenaan.

Kun käytät Node.js:ää testauksessa, toimi seuraavasti:

  1. Asenna Node.js (versio 6.6.0).
  2. Lataa Node Client -projekti GitHubista.
  3. Lisää projektihakemistoon varmenteet (ks. alla oleva esimerkki testivarmenteiden luomisesta).
  4. Lisää projektihakemistoon config.json-tiedosto. Lisää tiedostoon varmennetiedostojen tiedot sekä tunnistetiedot, jotka olet saanut Valtuudet-palvelun käyttöönoton projektipäälliköltä.
  5. Aja komentorivillä ”npm install” ja ”node WebApiClient.js”.
  6. Mene selaimella osoitteeseen /register/hpa/[HETU]. Esimerkkejä: HPA (henkilön puolesta asiointi): https://localhost:8904/register/hpa/010180-9026, YPA (yrityksen puolesta asiointi): https://localhost:8904/register/ypa/031046-9982.
  7. Asiointioikeuskysely käynnistyy ja ohjaa sinut Valtuudet-palvelun päämiehen valintaan. Valinnan jälkeen selainikkunaan tulostuu kyselyn lopputulos. Se voi olla esimerkiksi kuvan 1 mukainen.

Valtuudet - nodeclient selain
Testivarmenteet voi luoda komentorivillä esimerkiksi seuraavasti:

openssl req -new > cert.csr
openssl rsa -in privkey.pem -out key.pem
openssl x509 -in cert.csr -out cert.pem -req -signkey key.pem -days 1001
cat key.pem>>cert.pem


Node.js Clientin debuggaaminen

Node.js Clientin toimintalogiikan hahmottamiseksi saattaa olla hyödyllistä debugata koodia. Se auttaa ymmärtämään paremmin funktioiden suoritusjärjestystä ja muuttujien sisältöä.

Käynnistäminen debug-tilaan onnistuu komentorivillä seuraavasti:

node --inspect --debug-brk WebApiClient.js
Debugger listening on port 9229.
Warning: This is an experimental feature and could change at any time.
To start debugging, open the following URL in Chrome:
chrome-devtools://devtools/bundled/inspector.html?experiments=true&v8only=true&ws=127.0.0.1:9229/2746fa2b-704a-4a88-acdc-166f60e183d4
Debugger attached.

Kopioi tämän jälkeen Chrome-selaimen osoiteriville URL-osoite, joka on tulostunut komentoriville (alkaa chrome-devtools://). Sen jälkeen voit asettaa lähdekoodiin pysäytyspisteitä ja käynnistää asiointioikeuskyselyn aiemmin kuvatulla tavalla.

4. Rajapintojen kutsuminen ohjelmakoodista

4.1 Henkilön puolesta asiointi (HPA)

Seuraavassa on kuvattu asiointioikeuskyselyn vaiheet henkilön puolesta asioinnissa (Web API HPA). Kuvauksesta käyvät ilmi pyyntö- ja vastaussanomissa välitettävät muuttujat. Niiden lisäksi kyselyssä tulee välittää joitakin asiointipalvelukohtaisia vakioita. Asiointioikeuskyselyn asiointipalvelukohtaiset vakiot on kuvattu Web API -rajapintakuvauksessa.

1. (GET) Rekisteröi Web API -sessio: {rova_host}/service/hpa/user/register/{client_id}/{hetu}?requestId={requestId}

  • header-osiossa: X-AsiointivaltuudetAuthorization (tarkistesumma)
  • poimi vastauksesta sessionId
  • poimi vastauksesta userId.

2.(GET) Siirrä käyttäjä Valtuudet-palvelun päämiesvalintaan: {rova_host}/oauth/authorize?client_id={client_id}&response_type=code&redirect_uri={redirect_uri}&user={user}&lang={lang}

  • välitetään userId URLin muuttujan user-arvona
  • käyttäjä on ohjattu redirect URLiin, jossa parametrina on code
  • poimi vastauksesta authorization_code.

3.(POST) Lähetä authorization_code: {rova_host}/oauth/token?grant_type=authorization_code&redirect_uri={redirect_uri}&code={code}

  • välitetään authorization_code URLin muuttujan code-arvona
  • välitetään HTTP Basic Authorization header
  • poimi vastauksesta access_token.

4.(GET) Hae valittu päämies tai päämiehet: {rova_host}/service/hpa/api/delegate/{sessionId}?requestId={requestId}

  • lasketaan tarkistesumma (ks. alempaa kohta Tarkistesumman laskeminen)
  • välitetään header-osiossa: X-AsiointivaltuudetAuthorization (tarkistesumma)
  • välitetään access_token header-osiossa
  • välitetään sessionId URLissa
  • poimi vastauksesta hetu-lista.

5.(GET) Lähetä asiointioikeuskysely: {rova_host}/service/hpa/api/authorization/{sessionId}/{personId}?requestId={requestId}&issues={issues}

  • lasketaan tarkistesumma (ks. alempaa kohta Tarkistesumman laskeminen)
  • välitetään header-osiossa: X-AsiointivaltuudetAuthorization (tarkistesumma)
  • välitetään access_token header-osiossa
  • välitetään sessionId URLissa
  • välitetään issues-parametrin arvona URI, jos kysely halutaan kohdistaa koskemaan tiettyä kohdetta (= valtuusasioiden koodistossa asian yksilöivä URI)
  • poimi vastauksesta ALLOWED/DISALLOWED.

Asiointioikeuskyselyn vastaus henkilön puolesta asioinnissa voi olla esimerkiksi seuraavanlainen:

[{"result":"ALLOWED","reasons":[],"principal":{"personId":"120508A950F","name":"Kumpulainen Anni Emilia"}}]

Kuvassa 2 on esitetty yhteenvetona, miten yllä kuvattu asiointioikeuskysely henkilön puolesta asioinnissa etenee.

Valtuudet - webapi sekvenssikaavio

AuthorizationList

AuthorizationList-kyselyn avulla on mahdollista hakea kerralla kaikki valitun päämiehen myöntämät asiointiroolit. Asiointiroolilla määritetään, millaisia asioita asiamiehellä on oikeus hoitaa päämiehen puolesta. Täysivaltaisella henkilöllä voi esimerkiksi olla valtuus hoitaa vanhempansa lääkeasioita mutta ei pankkiasioita.

AuthorizationList-vastaus sisältää tiedon asiointirooleista, joihin päämies on valtuuttanut asiamiehen. Asiointioikeus ilmaistaan kentässä roles, jonka arvona palautetaan joko ALL (rajoittamaton asiointioikeus) tai lista asioista (issue URI), joita asiointioikeus koskee. Vastauksessa voi olla useampia asiointirooleja. Tyhjä lista tarkoittaa, että asiointioikeutta ei ole.

AuthorizationList-kysely kohdistetaan osoitteeseen /service/hpa/api/authorizationlist/.

Seuraavassa on esimerkkivastaus AuthorizationList-kyselyyn. Esimerkissä henkilöllä 010132-998W on seuraavat valtuudet: adoptiotietojen selvittäminen, ajoneuvotietojen selvittäminen, sotalapsitietojen selvittäminen ja sukuselvityksen tilaaminen.

[{"reasons":[],"roles":
["http://valtuusrekisteri.suomi.fi/sotalapsitietojen_selvittaminen",
"http://valtuusrekisteri.suomi.fi/adoptiotietojen_selvittaminen",
"http://valtuusrekisteri.suomi.fi/sukuselvityksen_tilaaminen",
"http://valtuusrekisteri.suomi.fi/ajoneuvotietojen_selvittaminen"],
"principal":{"personId":"010132-998W","name":"Tuulispää Edelweiss"}}]

Seuraavassa on esimerkkivastaus, kun toimitaan alaikäisen huollettavan puolesta:

[{"reasons":[],"roles":["ALL"],"principal":"personId":"120508A950F","name":"Kumpulainen Anni Emilia"}}]

4.2 Yrityksen puolesta asiointi (YPA)

Seuraavassa on kuvattu asiointioikeuskyselyn vaiheet yrityksen puolesta asioinnissa (Web API YPA). Kuvauksesta käyvät ilmi pyyntö- ja vastaussanomissa välitettävät muuttujat. Niiden lisäksi kyselyssä tulee välittää joitakin asiointipalvelukohtaisia vakioita. Asiointioikeuskyselyn asiointipalvelukohtaiset vakiot on kuvattu Web API -rajapintakuvauksessa.

Yrityksen puolesta asioinnissa ensimmäisen vaiheen rekisteröintikutsu suoritetaan eri osoitteeseen kuin henkilön puolesta asioinnissa. Myös varsinaiset asiointioikeuskyselyt eli vaiheet 4 ja 5 poikkeavat henkilön puolesta asioinnista.

1. (GET) Rekisteröi Web API -sessio: {rova_host}/service/ypa/user/register/{service_id}/{hetu}?requestId={requestId}

  • header-osiossa: X-AsiointivaltuudetAuthorization (tarkistesumma)
  • poimi vastauksesta sessionId
  • poimi vastauksesta userId.

2. (GET) Siirrä käyttäjä Valtuudet-palvelun päämiesvalintaan: {rova_host}/oauth/authorize?client_id={client_id}&response_type=code&redirect_uri={redirect_uri}&user={user}&lang={lang}

  • välitetään userId URLin muuttujan user-arvona
  • käyttäjä on ohjattu redirect URLiin, jossa parametrina on code
  • poimi vastauksesta authorization_code.

3. (POST) Lähetä authorization_code: {rova_host}/oauth/token?grant_type=authorization_code&redirect_uri={redirect_uri}&code={code}

  • välitetään authorization_code URLin muuttujan code-arvona
  • välitetään HTTP Basic Authorization header
  • poimi vastauksesta access_token.

4.(GET) Hae lista toisen puolesta asioijan valitsemista kohdeyrityksistä ja niihin liittyvistä rooleista: {rova_host}/service/ypa/api/organizationRoles/{sessionId}?requestId={requestId}

  • lasketaan tarkistesumma (ks. alempaa kohta Tarkistesumman laskeminen)
  • välitetään header-osiossa: X-AsiointivaltuudetAuthorization (tarkistesumma)
  • välitetään access_token header-osiossa
  • välitetään sessionId URLissa
  • poimi vastauksesta organizationList.

Asiointioikeuskyselyn vastaus yrityksen puolesta asioinnissa voi olla esimerkiksi seuraavanlainen:

[{"name":"Asunto Oy Tampereen Ratinanpuisto","identifier":"2305162-8","complete":true,"roles":["IS"]}]

4.3 Tarkistesumman laskeminen

Tarkistesumma tulee liittää Valtuudet-palvelun Web API -rajapintaan lähetettävien pyyntöjen header-osioon. Seuraavassa on esitetty, miten tarkistesumman voi laskea Node.js- ja Java-koodilla. Lisäksi on kuvattu, miten tarkistesumman laskemiseen toteutettu funktio voidaan verifioida.

Esimerkki Node.js-koodilla

function xAuthorizationHeader(path) {
var timestamp = moment().format();
var checksum = crypto.createHmac('sha256', CLIENT_SECRET)
.update(path + ' ' + timestamp)
.digest('base64');
return CLIENT_ID + ' ' + timestamp + ' ' + checksum;
}

Katso tarkistesumman laskemisen Node.js-esimerkkikoodi kokonaisuudessaan.Avautuu uuteen ikkunaan.

Esimerkki Java-koodilla

protected String getAuthorizationValue(String path) throws IOException {
String timestamp = ZonedDateTime.now(ZoneOffset.UTC).format(DateTimeFormatter.ISO_DATE_TIME);
return config.getClientId() + " " + timestamp + " " + hash(path + " " + timestamp, config.getApiKey());
}
private String hash(String data, String key) throws IOException {
try {
Mac mac = Mac.getInstance(HMAC_ALGORITHM);
SecretKeySpec signingKey = new SecretKeySpec(key.getBytes(), HMAC_ALGORITHM);
mac.init(signingKey);
byte[] rawHmac = mac.doFinal(data.getBytes());
String result = new String(Base64.getEncoder().encode(rawHmac));
return result;
} catch (NoSuchAlgorithmException | InvalidKeyException | IllegalStateException e) {
throw new IOException("Cannot create hash", e);
}
}

Katso tarkistesumman laskemisen Java-esimerkkikoodi kokonaisuudessaan.Avautuu uuteen ikkunaan.

Tarkistesumman laskemiseen toteutetun funktion verifiointi

Alla olevilla syötteillä voi varmistaa, että tarkistesumman laskemiseen toteutettu funktio toimii asianmukaisesti. Kun annat funktiolle alla olevat syötteet, lopputuloksen tulee olla sama kuin alla.

Path = ”/service/hpa/user/register/ed4b7ae7/080297-915A?requestId=02fd35dc-99e6-477b-b6e2-03f02cbf3666” 
ClientId = ”ed4b7ae7” 
ApiKey = ”3ba56df8-88b8-4805-9b04-2f8e7a61” 
TimeStamp = ”2017-02-09T10:29:42.09Z” 

Lopputulos: 

ed4b7ae7 2017-02-09T10:29:42.09Z z7X+xWtrvth1L7Ql6B/4xZ0iQ1VjToWX4TnHVLo8RGo=


4.4 Asiointioikeuskyselyn kohdistaminen tiettyyn valtuusasiaan henkilön puolesta asioinnissa

Valtuusasialla rajataan valtuuden toimivalta eli se kertoo, mitä asiaa tai asioita henkilö voi hoitaa toisen puolesta. Valtuusasia voi olla esimerkiksi ajoneuvon rekisteröinti tai ajoneuvon katsastus.

Asiointioikeuskyselyn voi kohdistaa tiettyyn valtuusasiaan tai -asioihin lisäämällä Authorization-kyselyyn parametrin &issues={issues}. Katso lisätietoa asiointioikeuskyselyn kohdistamisesta Web API -rajapintakuvauksen kohdasta Henkilön puolesta asiointi (HPA).

Authorization-kyselyn parametriksi voi antaa useamman valtuusasian kerralla. Silloin kieltävästä vastauksesta ei kuitenkaan käy ilmi, mihin valtuusasiaan asiointioikeus on evätty. Jos halutaan tietää, mihin valtuusasiaan asiointioikeus on evätty, jokaiseen valtuusasiaan pitää tehdä erillinen kysely.

Yleinen käyttötapaus:

  1. Henkilö A on myöntänyt valtuuden henkilölle B toimia puolestaan valtuudessa eli asiassa C. Valtuus on tallennettu valtuusrekisteriin.
  2. Asiakasorganisaation asiointipalvelulle D on perustettu palvelu E Digi- ja väestötietovirastolle.
  3. Palvelulle E on konfiguroitu käyttöön valtuus C.
  4. Henkilö B kirjautuu asiointipalveluun D ja valitsee haluavansa asioida asiassa C.
  5. Henkilö B valitsee valintakäyttöliittymässä päämiehen eli henkilön A, jonka puolesta hän haluaa asioida.
  6. Asiointipalvelu D tekee asiointioikeuskyselyn (Authorization), jolla tarkistetaan, onko henkilöllä B oikeus toimia asiassa C henkilön A puolesta.

4.5 Yrityksen puolesta asioinnin vastausesimerkki, kun valtuusrekisterissä on valtuuksia

Yritys, jonka Y-tunnus on 2036583-2, on luonut valtuuden ”Työperäinen maahanmuutto” henkilölle, jonka henkilötunnus on 010180-9026. Tämä henkilö kirjautuu sisään ja valitsee valintakäyttöliittymästä yrityksen 2036583-2. Palvelun X sääntömoottorissa on konfiguroitu päälle asetus ”Henkilölle löytyy valtuus valtuusrekisterissä http://valtuusrekisteri.suomi.fi/Tyoperainen_maahanmuutto”.

Tällöin kysely tuottaa seuraavanlaisen vastauksen:

[{"name":"Maanrakennus Ari Eerola T:mi","identifier":"2036583-2","complete":true,"roles":["http://valtuusrekisteri.suomi.fi/tyoperainen_maahanmuutto"]}]

5. Toteutuksen verifiointi testiympäristössä

Testiympäristöön luotu palvelu on vapaasti käytettävissä toteutuksen aikaiseen testaukseen ja toteutuksen verifiointiin. Testipalvelu on käytettävissä myös tuotantovaiheeseen siirtymisen jälkeen mahdollisten muutosten verifiointiin.

Palvelua voi testata Valtuudet-palvelun testaamiseen tarkoitetuilla henkilötunnuksilla ja Y-tunnuksilla.

6. Tietoliikenneyhteyksien tarkistaminen tuotantoympäristössä

Tietoliikenneyhteyksien toimivuus tulee tarkistaa myös ennen tuotantoympäristöön siirtymistä.

Palvelun osoite tuotantoympäristössä

Yhteyspiste (rova_host):

  • https://asiointivaltuustarkastus.suomi.fi/

Esimerkki HPA (henkilön puolesta asiointi) -rekisteröintikutsusta:

  • https://asiointivaltuustarkastus.suomi.fi/service/hpa/user/register/ed4b7ae7/080297-915A?requestId=02fd35dc-99e6-477b-b6e2-03f02cbf3666

Tietoliikenneyhteyden tarkistaminen komentorivillä tuotantoympäristössä

Voit tarkistaa tuotantoympäristössä tietoliikenneyhteyden toimivuuden komentorivillä seuraavalla tavalla:

$ wget https://asiointivaltuustarkastus.suomi.fi/service/hpa/user/register/ed4b7ae7/080297-915A?requestId=02fd35dc-99e6-477b-b6e2-03f02cbf3666
--2017-02-08 13:49:47-- https://asiointivaltuustarkastus.suomi.fi/service/hpa/user/register/ed4b7ae7/080297-915A?requestId=02fd35dc-99e6-477b-b6e2-03f02cbf3666
Selvitetään osoitetta asiointivaltuustarkastus.suomi.fi (asiointivaltuustarkastus.suomi.fi)... 131.207.22.78
Yhdistetään palvelimeen asiointivaltuustarkastus.suomi.fi (asiointivaltuustarkastus.suomi.fi)|131.207.22.78|:443... yhdistetty.
HTTP-pyyntö lähetetty, odotetaan vastausta... 403 Forbidden
2017-02-08 13:49:47 VIRHE 403: Forbidden

Jos yhteys toimii, komentoriville tulostuu

131.207.22.78|:443… yhdistetty


7. Toteutuksen verifiointi tuotantoympäristössä

Tuotantoympäristössä ei voi suorittaa varsinaista testausta, mutta toteutuksen toimivuuden voi verifioida oikeita henkilö- tai Y-tunnuksia käyttämällä. Testitunnukset eivät toimi tuotantoympäristössä.

Ongelmatilanteet

Mahdollisissa ongelmatilanteissa ota yhteyttä Digi- ja väestötietoviraston Valtuudet-palvelun käyttöönottoihin. Lähtökohtaisesti sinun on syytä varmistaa ensin itse, ettei ongelma johdu virheistä asiakaspuolen toteutuksessa, konfiguraatioissa tai tietoliikenneyhteyksissä.

Alle on koottu käyttöönotoissa ilmenneitä ongelmatilanteita ja ratkaisuja niihin.

Web API HPA: Prosessi pysähtyy "403 Forbidden" -virheeseen sivulla https://asiointivaltuustarkastus.suomi.fi/oauth/authorize sen jälkeen, kun olen valinnut päämiehen ”Valitse, kenen puolesta asioit” -sivulla ja painanut ”Jatka”-nappia.

  • Tarkista, että toteutuksessa on käytössä Valtuuksien käyttöönoton toimittamat tunnistetiedot, jotka on tarkoitettu nimenomaan käytettävään ympäristöön.
  • Tarkista, että sama toteutus toimii testiympäristössä.
  • Ratkaisu eräässä käyttöönotossa: Kutsuttavassa osoitteessa /oauth/authorize oli yksi kauttaviiva liikaa eli osoite oli virheellisesti https://asiointivaltuustarkastus.suomi.fi//oauth/authorize?client_id=…

Web API HPA: Rekisteröintikutsusta tulee time out tai selaimella testattaessa virheilmoitus "ERR_CONNECTION_REFUSED".

  • Tarkista tietoliikenneyhteydet esimerkiksi komentorivillä wget-työkalulla.
  • Ratkaisu eräässä käyttöönotossa: Digi- ja väestötietoviraston palomuuriin oli tehty virheellisesti muutos, mikä esti tietoliikenteen ulkoverkosta.

Web API HPA: Kutsu palauttaa virheilmoituksen "HTTP 400 Bad Request".

  • Tarkista tietoliikenneyhteydet.
  • Ratkaisu eräässä käyttöönotossa: Asiakasorganisaation ympäristössä oli virheellisesti konfiguroitu välityspalvelin, mikä esti tietoliikenteen.

Web API YPA: Kutsu palauttaa virheilmoituksen "HTTP 403 Forbidden".

  • Ongelma johtuu lähes aina siitä, että pyynnön header-tiedot eivät ole kunnossa. Esimerkiksi X-AsiointivaltuudetAuthorization-header voi puuttua kokonaan tai tarkistesumman laskenta tuottaa virheellisen tuloksen.
  • Tarkista, että toteutuksessa on käytössä Valtuuksien käyttöönoton toimittamat tunnistetiedot, jotka on tarkoitettu nimenomaan käytettävään ympäristöön.
  • Tarkista, että pyyntö sisältää kaikki tarvittavat tiedot.
  • Tarkista, että tarkistesumman laskenta tuottaa oikean tuloksen.
  • Ratkaisu eräässä käyttöönotossa: Asiakasorganisaation C#-toteutuksessa käyttämä RestSharp.org-kirjasto ei lisännyt header-tietoa oikein. Ongelma ratkesi käyttämällä standardia WebRequest C# -kirjastoa.

Web API YPA: Rekisteröintikutsu palauttaa virheilmoituksen "403 Forbidden".

  • Tarkista, että toteutuksessa on käytössä Valtuuksien käyttöönoton toimittamat tunnistetiedot, jotka on tarkoitettu nimenomaan käytettävään ympäristöön.
  • Ratkaisu eräässä käyttöönotossa: X-AsiointivaltuudetAuthorization-headerin nimessä oli ylimääräinen kaksoispiste merkkijonon perässä.

Web API YPA: Rekisteröintikutsu palauttaa virheilmoituksen "HTTP 403 Forbidden".

  • Ongelma johtuu lähes aina siitä, että pyynnön header-tiedot eivät ole kunnossa. Esimerkiksi X-AsiointivaltuudetAuthorization-header voi puuttua kokonaan tai tarkistesumman laskenta tuottaa virheellisen tuloksen.
  • Tarkista, että toteutuksessa on käytössä Valtuuksien käyttöönoton toimittamat tunnistetiedot, jotka on tarkoitettu nimenomaan käytettävään ympäristöön.
  • Tarkista, että pyyntö sisältää kaikki tarvittavat tiedot.
  • Tarkista, että tarkistesumman laskenta tuottaa oikean tuloksen.
  • Ratkaisu eräässä käyttöönotossa: Asiakasorganisaation palvelinympäristössä oli käytössä väärä aikavyöhyke, mikä sotki tarkistesumman laskemisen. 


Päivitetty: 15.5.2025

Oletko tyytyväinen tämän sivun sisältöön?