Suomi.fi-valtuudet – Web-API-rajapinta ja valintakäyttöliittymä

Print Friendly, PDF & Email

 


1. Yleistä

Web-API rajapinta tarjoaa valintakäyttöliittymän puolesta-asioinnin kohteiden valintaan sekä REST-kyselyrajapinnat asiointioikeuskyselyiden tekemiseen.
Rajapinnan kutsumisessa hyödynnetään REST / JSON -rajapintoja, jotka on suojattu joko API key tai OAuth2 +API key suojauksella.
Asiointipalvelua rekisteröidessä Asiointivaltuudet-palvelun ylläpitäjä toimittaa asiointipalvelulle Web API client ID:n ja jaetun salaisuuden eli API keyn.

Palvelun kutsumiseen asiointipalvelu tarvitsee seuraavat tiedot:

  Kuvaus
Web API client ID 8-merkkinen alphanumeerinen tunniste
API key merkkijono
client_id OAuth tunniste
client_secret OAuth salasana

Rajapinta palauttaa HTTP 401 vastauksen mikäli Web-API session on vanhentunut.

2. Api-key suojattujen rajapintojen kutsuminen

Api-key suojattujen rajapintojen kutsuminen. Api-key tunnistetieto välitetään X-AsiointivaltuudetAuthorization HTTP headerissa. Headerin arvoksi laitetaan Web API client ID, aikaleima ja tarkistesumma välilyönnein erotettuna.

Kenttä Kuvaus
Web API client ID Asiointipalvelukohtainen asiakastunniste
aikaleima Aikaleima ilmaistaan ISO-8601 muodossa. Esimerkiksi: 1997-07-16T19:20+01:00. Rajapinta hylkää kutsut, joiden aikaleima eroaa NTP-synkronoidusta kellonajasta yli + 5 minuuttia.
tarkistesumma Tarkistesumma lasketaan pyynnön polusta ja aikaleimasta, välilyönnein erotettuna. Lähdeaineistosta lasketaan HMACSHA256 -tiiviste, jonka salausavaimena on API key
Tuloksena saatu binäärimuotoinen tiiviste lopuksi BASE64 enkoodataan.

  • Pyynnön polulla tarkoitetaan URL:n domain osan jälkeistä osuutta.
  • Aikaleiman muoto on määritetty taulukon kohdassa aikaleima
  • Api-key on palvelulle määritetty jaettu salaisuus, joka löytyy mm. admin käyttöliittymästä. Api key on käyttäjätunnukseen ja salasanaan verrattavissa oleva tunniste.

Tarkistesumman verifiointi

Alla näkyvää esimerkkilaskentaa voi käyttää tarkistesumman laskemiseen toteutetun funktion verifioimiseen. Ko. syötteillä pitäisi tulla sama lopputulos.
Esimerkki tarkistesumman laskentaan käytettävistä syötteistä ja lopputuloksesta
Path = ”/service/hpa/user/register/ae6r5iu9/111111-1111?requestId=a1b2c3d4e5f6g7” ClientId = ”ae6r5iu9” ApiKey = ”5ki56df8-89b8-4815-9g04-2f8e7c90” TimeStamp = ”2017-02-09T10:29:42.09Z” __________________
Lopputulos: ae6r5iu9 2017-02-09T10:29:42.09Z QPbl7lf1i6XJy5WgKwkPU6eJD164PqekipCx23yhtek=

3. OAuth2 -suojattujen rajapintojen kutsuminen

Lisätietoa OAuth2 suojauksesta löytyy {+}http://tools.ietf.org/html/rfc6749+
OAuth2 rajapinnan kutsumiseen tarvitaan seuraavat tiedot:

  Kuvaus
client_id Asiakkaan tunniste
client_secret Asiakkaan salaisuus

OAuth2 endpointit:

URL Kuvaus Esimerkkipyyntö Esimerkkivastaus
{rova_host}/oauth/authorize?client_id=web-api-client&response_type=code 
&redirect_uri={redirect_uri}&user={user}&lang={lang}
URL johon käyttäjä ohjataan valintojen tekemistä varten 
Pyynnön parametrit ovat:

  • client_id
  • redirect_uri (URL johon palataan ja jonka on oltava rekisteröity asiointipalvelulle)
  • response_type=code (aina näin)
  • user (register tapahtuman vastauksena tullut userId)
  • state (Ei pakollinen, mutta suositeltava parametri XSRF-hyökkäyksiä vastaan. Ks. {+}https://tools.ietf.org/html/rfc6749#section-10.12+)
  • lang (Ei pakollinen, toivottu käyttöliittymän kieli ISO 639-kielikoodina, esim. ”fi” tai ”sv”)  

    Vastaus:
  • authorization_code
GET /oauth/authorize?client_id=42bbe569&response_type=code&requestId=requestId&user=5b329323-17a4-4a38-8758-2ee5686ad4e7&state=fbd24182-016c-45ea-ae9c-630a4b00188f&redirect_uri={+}http://localhost:8901/hpa_web_api.html+&lang=fi HTTP/1.1

Host: localhost:18102

Esimerkki uudelleenohjauksesta: 
{+}http://localhost:8901/hpa_web_api.html?code=3lN85M&state=fbd24182-016c-45ea-ae9c-630a4b00188f+
.POST {rova_host}/oauth/token?grant_type=authorization_code 
&redirect_uri={redirect_uri}&code={code}
Token URL, jossa valintakäyttöliittymältä tullut code voidaan vaihtaa oauth tokeniin. 
Pyynnössä tulee olla HTTP Basic Authorization header, jossa tunnuksena on client_id ja salasana on client_secret. 
Pyynnön parametrit ovat:

  • grant_type=authorization_code (aina näin)
  • redirect_uri (sama URI kuin mitä on annettu /oauth/authorize – pyynnössä)
  • code (Authorisointi koodi, joka on saatu /oauth/authorize -pyynnön vastauksena) 

    Vastaus:
  • access_token
  • token_type
  • refresh_token
  • expires_in
  • scope
POST /oauth/token?code=pvGVSH&grant_type=authorization_code&redirect_uri={+}http://localhost:9999/callback/hpa+ HTTP/1.1

Authorization: Basic NDJiYmU1Njk6YmFkYi1hYmU0LWNhZmU=

Host: localhost:18102

Connection: close

Content-Length: 0

HTTP/1.1 200 OK

Server: Apache-Coyote/1.1

X-Content-Type-Options: nosniff

X-XSS-Protection: 1; mode=block

Cache-Control: no-cache, no-store, max-age=0, must-revalidate Pragma: no-cache

Expires: 0

X-Frame-Options: DENY

X-Application-Context: application:8102

Cache-Control: no-store

Pragma: no-cache

Content-Type: application/json;charset=UTF-8

Transfer-Encoding: chunked

Date: Mon, 13 Jun 2016 11:06:41 GMT

Connection: close

{”access_token”:”c77e38fe-ddb4-42c4-80bd-31ad83f3b618″,”token_type”:”bearer”,”refresh_token”:”e043c886-8048-4c54-b85b-a55a25a68891″,”expires_in”:599,”scope”:”read write trust”}

4. Rajapintojen kutsuminen

4.1 Pyyntö- ja loppukäyttäjätunnisteet

Tässä kappaleessa esitetyissä pyynnöissä tulee olla pyyntötunniste (requestId). Pyyntötunniste on pyynnön yksilöivä tunniste, jolla yksittäinen tapahtuma voidaan tunnistaa lokeista.

4.2. Web api session aloitus

REST-kutsujen palveluosoitteet:

  GET URL Esimerkkipyyntö Esimerkkivastaus
hpa {rova_host}/service/hpa/user/register/{service_id}/{hetu}?requestId={requestId} GET /service/hpa/user/register/42bbe569/010180-9026?requestId=requestId HTTP/1.1

X-AsiointivaltuudetAuthorization: 42bbe569 2016-06-13T11:23:34.481Z +m5GW11Zxu7taZd0XEspavunQQhIGooCCuLztjlCXSQ=

Accept: application/json;charset=UTF-8

Host: localhost:18102

Connection: keep-alive

HTTP/1.1 200 OK

Server: Apache-Coyote/1.1

Pragma: no-cache

Expires: 0

Cache-control: no-cache, no-store, max-age=0, must-revalidate

X-Content-Type-Options: nosniff

X-XSS-Protection: 1; mode=block

Cache-Control: no-cache, no-store, max-age=0, must-revalidate Pragma: no-cache

Expires: 0

X-Frame-Options: DENY

Content-Security-Policy: default-src ’self’; script-src ’self’ ’unsafe-inline’; style-src ’self’ ’unsafe-inline’;

X-Application-Context: application:8102

Content-Type: application/json;charset=UTF-8

Transfer-Encoding: chunked

Date: Mon, 13 Jun 2016 11:23:34 GMT

{”sessionId”:”6539d4ae-3791-4f5c-946b-7aaeb58f7107″,”userId”:”6f920b7d-be67-4a32-b431-340e21bd9359″}

ypa {rova_host}/service/ypa/user/register/{service_id}/{hetu}?requestId={requestId} GET /service/ypa/user/register/42bbe569/010180-9026?requestId=requestId HTTP/1.1

X-AsiointivaltuudetAuthorization: 42bbe569 2016-06-13T12:39:26.964Z zCPlTjoRhaQUFaTAETEU6gzN7+MWH1CDM/3cKAwG3hQ=

Accept: application/json;charset=UTF-8

Host: localhost:18102

Connection: keep-alive

HTTP/1.1 200 OK

Server: Apache-Coyote/1.1

Pragma: no-cache

Expires: 0

Cache-control: no-cache, no-store, max-age=0, must-revalidate

X-Content-Type-Options: nosniff

X-XSS-Protection: 1; mode=block

Cache-Control: no-cache, no-store, max-age=0, must-revalidate

Pragma: no-cache

Expires: 0

X-Frame-Options: DENY

Content-Security-Policy: default-src ’self’; script-src ’self’ ’unsafe-inline’; style-src ’self’ ’unsafe-inline’;

X-Application-Context: application:8102

Content-Type: application/json;charset=UTF-8

Transfer-Encoding: chunked

Date: Mon, 13 Jun 2016 12:39:27 GMT

{”sessionId”:”27652cd4-53c6-4f83-8ed4-ffda6a7c3d17″,”userId”:”cbaa6a42-d13a-4b12-80f9-7f488a8dbe68″}

hpa siirretty {rova_host}/service/hpa/user/register/transfer/{transfer_token}/{service_id}/{hetu}?requestId={requestId} GET /service/hpa/user/register/transfer/8UYQjnIY4vpU8DQVzviGDqH7Kxt9sW5W/f5f0d662/010180-9026?requestId=requestId HTTP/1.1

X-AsiointivaltuudetAuthorization: f5f0d662 2016-09-14T08:48:15.503Z Kt2vtNGi3FIDsTeEgAcJfqR17N+jYAOOW/XA48VEGf0=

Accept: application/json;charset=UTF-8

Host: localhost:18102

Connection: keep-alive

HTTP/1.1 200 OK

Server: Apache-Coyote/1.1

X-Content-Type-Options: nosniff

X-XSS-Protection: 1; mode=block

Cache-Control: no-cache, no-store, max-age=0, must-revalidate

Pragma: no-cache

Expires: 0

X-Frame-Options: DENY

Set-Cookie: JSESSIONID=5C0B947E916DF07CBC929BBFD629EF2E; Path=/; HttpOnly

X-Application-Context: application:18102

Content-Type: application/json;charset=UTF-8

Transfer-Encoding: chunked

Date: Wed, 14 Sep 2016 08:48:15 GMT

64

{”sessionId”:”9a980afa-1ea5-402e-a405-d52a08e36ef1″,”userId”:”00b1c274-97a4-48de-a1a4-c634e2928cf2″}

0

ypa 
siirretty
{rova_host}/service/ypa/user/register/transfer/{transfer_token}/{service_id}/{hetu}?requestId={requestId} GET /service/ypa/user/register/transfer/NnO6urpyH3Z1l2jbd7rrHewSGfcpxkKf/f5f0d662/010180-9026?requestId=requestId HTTP/1.1

X-AsiointivaltuudetAuthorization: f5f0d662 2016-09-14T08:56:20.32Z gKmAJz9XpqhQFlvGcLLqTxxWaGrfbJOLdZtzgRiQRiY=

Accept: application/json;charset=UTF-8

Host: localhost:8102

Connection: keep-alive

HTTP/1.1 200 OK

Server: Apache-Coyote/1.1

X-Content-Type-Options: nosniff

X-XSS-Protection: 1; mode=block

Cache-Control: no-cache, no-store, max-age=0, must-revalidate

Pragma: no-cache

Expires: 0

X-Frame-Options: DENY

Set-Cookie: JSESSIONID=A54DF5C396F59B587994A71A9FBE7003; Path=/; HttpOnly

X-Application-Context: application:18102

Content-Type: application/json;charset=UTF-8

Transfer-Encoding: chunked

Date: Wed, 14 Sep 2016 08:56:20 GMT

64

{”sessionId”:”faa683f0-b56e-4667-bc85-51e65a8a1ce4″,”userId”:”c4f6900a-c1f0-4a37-880b-c1d2f3470593″}

0

(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ä.)
Vastaus:

Vastaus kenttä Kuvaus
sessionId UUID muotoinen istuntotunniste, jota käytetään jatkokyselyihin.
userId UUID muotoinen käyttäjäkohtainen kertakäyttötunniste, joka välitetään valintakäyttöliittymälle. Tunnisteen voimassaoloaika on 10 minuuttia, jonka aikana käyttäjä on uudelleenohjattava valintakäyttöliittymään.

Rekisteröintikutsussa tulee olla X-AsiointivaltuudetAuthorization-header. Katso sen määrittely edellä.

4.3. HPA: henkilön puolesta asiointi

Access_token luetaan joko authorization bearer headerista tai url-parametrista.

HPA REST-kutsujen palveluosoitteet:

  GET URL   Esimerkkipyyntö Esimerkkivastaus
Delegate {rova_host}/service/hpa/api/delegate/{sessionId}?requestId={requestId}&access_token={access_token} GET /service/hpa/api/delegate/6539d4ae-3791-4f5c-946b-7aaeb58f7107?requestId=requestId&access_token=5b8fa683-0270-44e1-bc08-14622da02c3d HTTP/1.1


X-AsiointivaltuudetAuthorization: 42bbe569 2016-06-13T11:27:48.512Z vRd7rhcKL8Pix8PurTiV5SvC8Ian2cQY+siajTjnilU=

Host: localhost:18102

Accept: application/json;charset=UTF-8

Connection: keep-alive

HTTP/1.1 200 OK

Server: Apache-Coyote/1.1

X-Content-Type-Options: nosniff

X-XSS-Protection: 1; mode=block

Cache-Control: no-cache, no-store, max-age=0, must-revalidate Pragma: no-cache

Expires: 0

X-Frame-Options: DENY

X-Application-Context: application:8102

Content-Type: application/json;charset=UTF-8

Transfer-Encoding: chunked

Date: Mon, 13 Jun 2016 11:27:48 GMT

[{”personId”:”310813A951F”,”name”:”Kumpulainen Onni Matias”}]

Authorization {rova_host}/service/hpa/api/authorization/{sessionId}/{personId}?requestId={requestId}&issues={issues}&access_token={access_token} issues-parametrin arvona on asia, johon haetaan valtuutusta. Parametri ei ole pakollinen, niitä voi olla useita. GET /service/hpa/api/authorization/7407df88-8fbe-4e16-94fd-05467963b49e/120508A950F?requestId=testClientRequestId&issues={+}http://www.yso.fi/onto/rova/p6604&access_token=44416402-4869-4609-9b46-618cc028c839+ HTTP/1.1

X-AsiointivaltuudetAuthorization: 42bbe569 2016-06-13T11:48:02.087Z sK91/VzjqGbq4DVTntNf+2c2Q377rtcnpkWDNqE0W6o=

Host: localhost:18102

Accept: application/json;charset=UTF-8

Connection: keep-alive

HTTP/1.1 200 OK

Server: Apache-Coyote/1.1

X-Content-Type-Options: nosniff

X-XSS-Protection: 1; mode=block

Cache-Control: no-cache, no-store, max-age=0, must-revalidate Pragma: no-cache

Expires: 0

X-Frame-Options: DENY

X-Application-Context: application:8102

Content-Type: application/json;charset=UTF-8

Transfer-Encoding: chunked

Date: Mon, 13 Jun 2016 11:48:02 GMT

{”result”:”ALLOWED”,”reasons”:[]}

AuthorizationList {rova_host}/service/hpa/api/authorizationlist/{sessionId}/{personId}?requestId={requestId}&access_token={access_token} GET /service/hpa/api/authorizationlist/1bed4372-5706-4a3d-be1c-84a4c436636a/310813A951F?requestId=testClientRequestId&access_token=82e69cb5-b659-4dec-a12e-9fd9cf62db9f HTTP/1.1

X-AsiointivaltuudetAuthorization: 42bbe569 2017-10-25T05:22:03.873Z 1CngFqz1RPPSih0+4K8lsDa/e3rl79wywUP2hxkEJ6k=

Host: localhost:8102

Accept: application/json;charset=UTF-8

Connection: keep-alive

HTTP/1.1 200

Set-Cookie: JSESSIONID=98A7D5AE47A0B927496AFC382FD5F65D;path=/;HttpOnly X-Application-Context: roles-auths-web-api:8102

X-Content-Type-Options: nosniff

X-XSS-Protection: 1; mode=block

Cache-Control: no-cache, no-store, max-age=0, must-revalidate

Pragma: no-cache

Expires: 0

X-Frame-Options: DENY

Content-Type: application/json;charset=UTF-8

Transfer-Encoding: chunked

Date: Wed, 25 Oct 2017 05:22:05 GMT

{”reasons”:[],”roles”:[”ALL”]}

4.3.1 Delegate

REST-kutsussa välitetään rekisteröintipyynnön vastauksena saatu sessionId.

Taulukko 1. Delegate- JSON-vastaussanoman kuvaus

Elementin nimi Tyyppi Kuvaus Arvojoukko
sessionId string Register-pyynnön vastauksessa annettu sessionId
hetu string Register-pyynnössä välitetty hetu
service string Register-pyynnössä välitetty service_id:tä vastaava XRoadServiceIdentifier
type string ”HPA”
principals array<Principal> Lista päämiesten perustiedoista Lista n*[principal [personId,name]] tai tyhjä lista

Principal

Elementin nimi Tyyppi Kuvaus Arvojoukko
personId string Hetu
name string Nimi

4.3.2 Authorization

Rest-kutsussa välitetään rekisteröintipyynnön vastauksena saatu sessionId, asiointioikeustarkistuksen kohteen personId sekä mahdolliset valtuutukset, joiden puitteissa oikeustarkistus tehdään.
Authorization-vastaus sisältää tiedon siitä, onko asiamiehellä valitun päämiehen puolesta asiointioikeus. Asiointioikeus ilmaistaan kentässä ”authorization”, jonka arvona palautetaan joko positiivinen päätös ALLOWED tai negatiivinen päätös DISALLOWED. Mikäli vastaus on DISALLOWED ja palvelulle on sallittu näyttää hylkäysperusteet, palautetaan ne listan reason-kentissä.
Onnistuneen kyselyn vastaussanoma kuvataan alla olevassa taulukossa.
Taulukko 5. Authorization-vastaussanoman kuvaus

Elementin nimi Tyyppi Kuvaus Arvojoukko
result string Päätöstieto onko puolesta-asiointi valitussa kontekstissa sallittu ”ALLOWED” tai ”DISALLOWED”
reasons array<DecisionReason> Arvo ehdollinen. ”reason”-elementtejä voi olla useampia, yksi jokaista hylkäämisperustetta kohden. 
Kentän käytöstä sovitaan palvelusopimuksessa erikseen.
n* reason[rule, value]
Kenttä rule sisältää kyseisen säännön tunnisteen ja value syyn lokalisointiavaimen

DecisionReason

Elementin nimi Tyyppi Kuvaus Arvojoukko
reasonRule string
reasonValue string
valueType string ”DESCRIPTION”, ”EXCEPTION”

4.3.3 AuthorizationList

Rest-kutsussa välitetään rekisteröintipyynnön vastauksena saatu sessionId ja asiointioikeustarkistuksen kohteen personId.
AuthorizationList-vastaus sisältää tiedon asiointirooleista, joihin asiamiehellä valitun päämiehen puolesta on asiointioikeus. Asiointioikeus ilmaistaan kentässä ”roles”, jonka arvona palautetaan joko ALL (rajoittamaton asiointioikeus) tai lista asioista (issue uri), joita asiointioikeus koskee. Mikäli lista on tyhjä, ei asiointioikeutta ole.
Onnistuneen kyselyn vastaussanoma kuvataan alla olevassa taulukossa.
Taulukko 5. AuthorizationList-vastaussanoman kuvaus

Elementin nimi Tyyppi Kuvaus Arvojoukko
roles array<String> Listaus asiamiehen asiointioikeuksista päämiehen puolesta String[n* ”issue URI”], String[”ALL”]
reasons array<DecisionReason> Arvo ehdollinen. ”reason”-elementtejä voi olla useampia, yksi jokaista hylkäämisperustetta kohden. 
Kentän käytöstä sovitaan palvelusopimuksessa erikseen.
n* reason[rule, value]
Kenttä rule sisältää kyseisen säännön tunnisteen ja value syyn lokalisointiavaimen

DecisionReason

Elementin nimi Tyyppi Kuvaus Arvojoukko
reasonRule string
reasonValue string
valueType string ”DESCRIPTION”, ”EXCEPTION”

4.4. YPA

Access_token luetaan joko authorization bearer headerista tai url-parametrista.

YPA REST-kutsujen palveluosoitteet:

  GET URL Esimerkkipyyntö Esimerkkivastaus
organizationRoles (all selected) {rova_host}/service/ypa/api/organizationRoles/{sessionId}?requestId={requestId}&access_token={access_token} GET /service/ypa/api/organizationRoles/450c59d4-0456-4ad5-b298-ac9c4b5c44e9?requestId=requestId&access_token=d8b67168-0354-4795-b7d9-fbdc4a4850ad HTTP/1.1

X-AsiointivaltuudetAuthorization: 42bbe569 2016-06-13T11:50:48.327Z ES9QTREbV0tL4N0NCr5pYs8Tfcvr9wz+1tIfLMAI+pY=

Host: localhost:18102

Accept: application/json;charset=UTF-8

Connection: keep-alive

HTTP/1.1 200 OK

Server: Apache-Coyote/1.1

X-Content-Type-Options: nosniff

X-XSS-Protection: 1; mode=block Cache-Control: no-cache, no-store, max-age=0, must-revalidate

Pragma: no-cache

Expires: 0

X-Frame-Options: DENY

X-Application-Context: application:8102

Content-Type: application/json;charset=UTF-8

Transfer-Encoding: chunked

Date: Mon, 13 Jun 2016 11:50:47 GMT

[{”name”:”Lumi Global Oy”,”identifier”:”123456-1″,”roles”:[”NIMKO”,”TJ”,[{”name”:”Lumi Global Oy”,”identifier”:”123456-1″,”roles”:[”NIMKO”,”TJ”,”http://valtuusrekisteri.suomi.fi/palkkatietojen_katselu?principalId=6004971-1&subOrganization=1234], ”complete”:true}]], ”complete”:true}]

organizationRoles (one) {rova_host}/service/ypa/api/organizationRoles/{sessionId}/{organizationId}?requestId={requestId}&access_token={access_token} GET /service/ypa/api/organizationRoles/450c59d4-0456-4ad5-b298-ac9c4b5c44e9/123456-1?requestId=requestId&access_token=d8b67168-0354-4795-b7d9-fbdc4a4850ad HTTP/1.1

X-AsiointivaltuudetAuthorization: 42bbe569 2016-06-13T11:50:48.327Z ES9QTREbV0tL4N0NCr5pYs8Tfcvr9wz+1tIfLMAI+pY=

Host: localhost:18102

Accept: application/json;charset=UTF-8

Connection: keep-alive

HTTP/1.1 200 OK

Server: Apache-Coyote/1.1

X-Content-Type-Options: nosniff

X-XSS-Protection: 1; mode=block

Cache-Control: no-cache, no-store, max-age=0, must-revalidate

Pragma: no-cache

Expires: 0

X-Frame-Options: DENY

X-Application-Context: application:8102

Content-Type: application/json;charset=UTF-8

Transfer-Encoding: chunked

Date: Mon, 13 Jun 2016 11:50:47 GMT

[{”name”:”Lumi Global Oy”,”identifier”:”123456-1″,”roles”:[”NIMKO”,”TJ,[{name”:”Lumi Global Oy”,”identifier”:”123456-1″,”roles”:[”NIMKO”,”TJ”,”http://valtuusrekisteri.suomi.fi/palkkatietojen_katselu?principalId=6004971-1&subOrganization=1234], ”complete”:true}]”], ”complete”:true}]


OrganizationRoles vastaus sisältää listan puolesta asioijan valitsemista kohdeorganisaatioista ja niihin liittyvistä rooleista. Mikäli osa rooleista jää selvittämättä esim. etäkutsun timeout tilanteen seurauksena , tulee organization elementin complete kentän arvoksi false.

Taulukko 1. OrganizationRoles-vastaussanoman kuvaus

Elementin nimi Kuvaus Arvojoukko
organizationList Lista organisaatioista. Lista n*[organization] tai tyhjä

OrganizationList-elementin kuvaus:

Pääelementti Elementin nimi Kuvaus Arvojoukko
organization
organizationIdentifier Organisaation tunniste (y-tunnus)  y-tunnus
name Organisaation nimi organisaation nimi
roles Listaus rooleista (Mukana vain pyynnöissä joissa organisaatio-tunniste rajaus tai mikäli käyttäjään liittyy vain 1 organisaatio) Lista n*[role [”NIMKO”, ”TJ”, String]]
complete Mikäli osa rooleista jää selvittämättä, tulee complete kentän arvoksi false. true (oletus), false

4.5. Web api -session siirto

Nykyisestä Web api sessiosta voidaan luoda siirtotunniste (transfer_token), joka välitetään seuraavalle asiointipalvelulle. Katso session aloitus siirto-siirtotoiminnallisuus.
REST-kutsujen palveluosoitteet:

  GET URL Esimerkkipyyntö Esimerkkivastaus
hpa {rova_host}/service/hpa/user/transfer/token/{sessionId} GET /service/hpa/user/transfer/token/26f6c8d7-151c-4ee5-8927-4bbe9b6a0cf4 HTTP/1.1

X-AsiointivaltuudetAuthorization: 42bbe569 2016-09-14T08:48:09.646Z +zk9r02Xhyjxw8gmdl9DRTeCfFtNcfAKtSihMGY5X70=

Host: localhost:8102

Accept: application/json;charset=UTF-8

Connection: keep-alive

HTTP/1.1 200 OK

Server: Apache-Coyote/1.1

X-Content-Type-Options: nosniff

X-XSS-Protection: 1; mode=block

Cache-Control: no-cache, no-store, max-age=0, must-revalidate

Pragma: no-cache

Expires: 0

X-Frame-Options: DENY

Set-Cookie: JSESSIONID=BACEFB94488E58A5120327427B4A0090; Path=/; HttpOnly

X-Application-Context: application:18102

Content-Type: application/json;charset=UTF-8

Content-Length: 32

Date: Wed, 14 Sep 2016 08:48:09 GMT

8UYQjnIY4vpU8DQVzviGDqH7Kxt9sW5W

ypa {rova_host}/service/ypa/user/transfer/token/{sessionId} GET /service/ypa/user/transfer/token/faa683f0-b56e-4667-bc85-51e65a8a1ce4 HTTP/1.1

X-AsiointivaltuudetAuthorization: f5f0d662 2016-09-14T09:14:37.313Z LRMvn3/TkDRQKE2XQj8Bqt/wzo50crEDs4pL29Js1ro=

Host: localhost:18102

Accept: application/json;charset=UTF-8

Connection: keep-alive

HTTP/1.1 200 OK

Server: Apache-Coyote/1.1

X-Content-Type-Options: nosniff

X-XSS-Protection: 1; mode=block

Cache-Control: no-cache, no-store, max-age=0, must-revalidate

Pragma: no-cache

Expires: 0

X-Frame-Options: DENY

Set-Cookie: JSESSIONID=16B81306E6EE869153481D689CFBB130; Path=/; HttpOnly

X-Application-Context: application:18102

Content-Type: application/json;charset=UTF-8

Content-Length: 32

Date: Wed, 14 Sep 2016 09:14:37 GMT

LWrF1SN4OE6ZaTrnolyfxf1JdFFcHT-R

4.6. Web api -session lopetus

Web api session ja käyttäjän tekemät valinnat vapautetaan unregister toiminnolla.
REST-kutsujen palveluosoitteet:

  GET URL Esimerkkipyyntö Esimerkkivastaus
hpa {rova_host}/service/hpa/user/unregister/{sessionId} GET /service/hpa/user/unregister/ef2977df-605a-49b3-9960-a9bc9b61b168 HTTP/1.1

X-AsiointivaltuudetAuthorization: 42bbe569 2016-06-14T13:41:19.103Z L/qxZb9R84KJeGJMAUNpOtlfvjDWL2mZEj+IpPUxv+I=

Host: localhost:18102

Accept: application/json;charset=UTF-8

Connection: keep-alive

HTTP/1.1 200 OK

Server: Apache-Coyote/1.1

Pragma: no-cache

Expires: 0

Cache-control: no-cache, no-store, max-age=0, must-revalidate

X-Content-Type-Options: nosniff

X-XSS-Protection: 1; mode=block

Cache-Control: no-cache, no-store, max-age=0, must-revalidate

Pragma: no-cache

Expires: 0

X-Frame-Options: DENY

Content-Security-Policy: default-src ’self’; script-src ’self’ ’unsafe-inline’; style-src ’self’ ’unsafe-inline’;

X-Application-Context: application:8102

Content-Type: application/json;charset=UTF-8

Transfer-Encoding: chunked

Date: Tue, 14 Jun 2016 13:41:19 GMT

true

ypa {rova_host}/service/ypa/user/unregister/{sessionId} GET /service/ypa/user/unregister/ef2977df-605a-49b3-9960-a9bc9b61b168 HTTP/1.1

X-AsiointivaltuudetAuthorization: 42bbe569 2016-06-14T13:41:19.103Z L/qxZb9R84KJeGJMAUNpOtlfvjDWL2mZEj+IpPUxv+I=

Host: localhost:18102

Accept: application/json;charset=UTF-8

Connection: keep-alive

HTTP/1.1 200 OK

Server: Apache-Coyote/1.1

Pragma: no-cache

Expires: 0

Cache-control: no-cache, no-store, max-age=0, must-revalidate

X-Content-Type-Options: nosniff

X-XSS-Protection: 1; mode=block

Cache-Control: no-cache, no-store, max-age=0, must-revalidate

Pragma: no-cache

Expires: 0

X-Frame-Options: DENY

Content-Security-Policy: default-src ’self’; script-src ’self’ ’unsafe-inline’; style-src ’self’ ’unsafe-inline’;

X-Application-Context: application:8102

Content-Type: application/json;charset=UTF-8

Transfer-Encoding: chunked

Date: Tue, 14 Jun 2016 13:41:19 GMT

true

4.7 Rajapintojen JWT-versiot

Seuraavista Web-APIn rajapinnoista löytyy myös JWT-versiot, jotka palauttavat vastauksen RFC 7519:ssa määriteltyinä JSON Web Tokeneina:

  • Authorization
  • AuthorizationList
  • organizationRoles (all selected)

organizationalRoles-rajapinnasta on saatavilla myös oletusvastauksen sijasta roolien myöhempää hakemista varten JWT tokenin palauttava versio. Tämä mahdollistaa JWT-vastausta useamman valtuutuksen aiheen palauttamisen vastaussanomassa.
Tokenit tarjoavat lisäturvaa tiedonsiirtoon, sisältäen asiointivaltuuksien vastauksissa allekirjoitettuina seuraavat tiedot:

Yleiset tiedot:

Avain Arvo / Kuvaus
iss (issuer) ’Suomi-fi-Valtuudet’
aud (audience) Käytetyn palvelun UUID
iat (issueTime) Luontiajankohta
jti (jwtID) Tokenin UUID
sub (subject) ’Authorization’ | ’AuthorizationList’ | ’OrganizationalRoles’

Asiointivaltuudet-kohtaiset tiedot:

Avain Arvo / Kuvaus
principal Päämiehen/valtuuttajan hetu
hetu Loppukäyttäjän hetu
response Rajapintakohtainen vastaus
issue Authorization-pyynnölle annettu aiherajaus

Rajapintojen JWT-versioita käytettäessä tarvitaan seuraavat asetukset perusrajapintojen edellyttämien asetusten lisäksi:

Asetus Kuvaus
serviceUUID Käytettävän palvelun UUID.
publicKey Allekirjoituksen tarkastamiseen käytettävä palvelun julkinen avain

JWT-rajapinnat ovat käytettävissä muiden rajapintojen tapaan Asiointivaltuuksien esimerkkiasiakaskirjastolla roles-auths-client. Tällöin JWT asiakas on alustettava vakioarvojen lisäksi käytettävän palvelun UUID:llä ja julkisella avaimella.

JWT tokenien allekirjoitusten tarkastamiseen käytettävät julkiset avaimet:

Tuotantoympäristö
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAh5dSdhllRgZDvjdSayG+RUcUztSKtiPgFEmRHEW6LPesuafmKMaRQsoLgVKpJySqrkiz4dLXlm5lNJjS3GvsNLJpEVAtLjg/62+knfGxSTAuEOGw1cXgl9JXKUCF+6ROOQm4RzrgjyzJGY4shQdNnU7c7sUPEU1rWPaCwUsvxWxXq++mhrDIWaHArgqNz1vmu4exURgbmuVR4rLbrmuqlGBVKRXI9SY2SHMDlFhkpLwOP60rHw5x3atkwPvCslLGuc7c56gNhV7LxFTRzwSSCXiWC3+/nMeoJPPxlB4H6sXc3A2zfkg/AIxhjojEI1UDyCWRTYR2aAiNmfZiVVlUrGKNl8wEuW3HXTGz0/yxt9++MdLCl7a2/4QkPs3y4vgXBUC91HpFb7vO1nuJRwrcyPKtkfhvZZa8sQn/FqsJXUzcTm079xmt4vLhm5liSUik3uYDueteP3rKyUtrnXeX8VX0NoS2ROXQm7eAZskifH4cCTJU29k5/G1sgaISK/mWFEExdsI8Ua7toYOUmCh3zMc/SC0Pf+9XCPFQOpADpumb6ihoiulndDT9pyN0uXYzbblL6QC+jSZMVOEgFyhJ336BjAcd8Do86nuSTA6gtH6JsfzeKr0E+XO6QB4ayr+62guFpHxHdCV1h5B8V7x4ow2bvsHEpVRRErkNrFpkVckCAwEAAQ==

QA-ympäristö
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAu5JAD2cfUhm2XV/3AJbs65xRqYXII0tEhCVim3ra1lccxk5enpyzTW26lXpg1J4wixaDHDA7DzvCmfg+ZPQOqyShqfDtHj9t2SaP8p5C55QA+PMMoFDMTMZNdzBorSfPb7w14mxP89vq5g32/FVpFuo5UMaQ9fFS+ayquDKS4NN5ptrv5jLxHJTZzTXDXEMnO2Seybwi2nANqug6j/ty+kpBwGRPcCN9upgu5Zw2XF92UF9z+Wb/qHIvDgzQZmgSihA8dbeoK7zdDHGUI5Tn+1hATIOYIbCDWPVnnpK6ZDeHS4yto4wIZ1H+5VOb91AfW9p/xVw+LvXdcF9cXuGVkHT0IWk/cpGh87hlhDYM5LkPRffuBSKxUUiR2fBdQAB8jqlTnnzQz8lRfoRKpQWhccuFxFdLczbvruGBJM5NjrfXbkopHBjb+zvMhBB2ydlhVukAs59sk9gYd2+3FC3bXI/xMQHTG+Heyw74l+zIYuqoNE4HoKLNs5I/T9X6Pqo7hcCRfVbAh0UyS967XWt1KJwxPeM7qMdOU1FwlGR1eJtjPLSfgPJp+s2oQmctukFnCaLGDwRb7ApAQVGtwE3aJa88UJGhoKWSCLR+ntokB9M8iTHNJdqpw3UPMnkONNdfLjE7qQAhGM24I6+zqCinw5dr89XsJi0MiE29Y8Rnde0CAwEAAQ==

Asiakastestiympäristö
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA6/U3FlrDvNZ0ygPK1WGBjDsn0fXFgsEgNgVlY5wlp9fskVZM8efZNqxbhBYHuKUp0sAZrV7Zjj8DDk9j6XXtRRma2CKVjur1G9bm2snKfmwIjfQmdJ8iPCLLhzhsuECsNKFm0kTsc8UUWG8/zv/nWciAfF+tDXTu4K6wxW8cQjOX2u54ZqfbCL5itL/5nZk6b+Qx6eQOD0liZkEQTVZhELm4hXPhsTgIApKsN/+tnFbT7gNBsJuD+JDZBYFapFLlEz5UEjwCF+Z7WlzWy3tHxkHt+MMyJRD/gMb2zjv1W8/hs3qWrJXszW6UX6KbtQenVvfJrAeBSI2UlsE0Yx2rJwIDAQAB

Access_token luetaan joko authorization bearer headerista tai url-parametrista.

Alla JWT-vastausta tukevien REST-kutsujen palveluosoitteet. Vastausten sisällöt löytyvät avattuina taulukon alapuolelta.

  GET URL Esimerkkipyyntö (lisätty rivinvaihtoja) Esimerkkivastaus (lisätty rivinvaihtoja)
Authorization /api/authorization/jwt/{sessionId}/{principalId}?requestId={requestId}&issues={issues}&access_token={access_token} GET

http://localhost:8102/service/hpa/api/authorization/jwt/ef6a5404-51b4-426e-9dc4-d4168b1ef43d/120508A950F?requestId=f4eb5a78-7db0-476a-81fd-19400b9861a5 &access_token=5bc76cde-8166-4b88-b7e6-05e61645a236 HTTP/1.1

Accept: application/json;charset=UTF-8

Connection: keep-alive

Host: localhost:8102

X-AsiointivaltuudetAuthorization: 42bbe569 2018-01-24T07:14:28.431Z 2LAP79FYt/GQh9Xisc/00bobUbQWhG9Vuu0HtoXDXfs=

issues-parametrin arvona on asia, johon haetaan valtuutusta. Parametri ei ole pakollinen, niitä voi olla useita.

HTTP/1.1 200

Cache-Control: no-cache, no-store, max-age=0, must-revalidate

Content-Length: 664

Content-Type: text/plain;charset=UTF-8

Date: Wed, 24 Jan 2018 07:14:29 GMT

Expires: 0

Pragma: no-cache

Set-Cookie: JSESSIONID=3D911FCD6AF0831817BF836B7A543A46;path=/;HttpOnly

X-Application-Context: roles-auths-web-api:8102

X-Content-Type-Options: nosniff

X-Frame-Options: DENY

X-XSS-Protection: 1; mode=block

eyJhbGciOiJSUzI1NiJ9.eyJwcmluY2lwYWwiOiIxMjA1MDhBOTUwRiIsImF1ZCI6ImQ0M2 NmZWI0LTZiMDctNGIzNi05OGVlLWNjMWE4ZjI5YjhhNCIsInN1YiI6IkF1dGhvcml6YXRpb 24iLCJyZXNwb25zZSI6IkFMTE9XRUQiLCJpc3MiOiJTdW9taS5maS1WYWx0dXVkZXQiLCJp YXQiOjE1MTY3NzgwNjksImp0aSI6ImM2YTllODBmLTI0YTgtNGQ5OS05MTBhLWI3YTdiNzk 1M2FlMiIsImhldHUiOiIxMjA5NzgtOTAzOCJ9.uq1vMkVFrBpqQi8JyJHJCvqguyKpgn9o4 XGBUe8nMubqMsvt5pGItBbrGFHoqjZf1jNqvPlnGvsowcyHK69VvRm9JMSVx6ldQ0aCxp2J 8HvpqRIURV0XeOWU-CCP22phoeAb3dfbWen0YYAHl61_j1AlHgvrlWl3mE_E9WbMBkqysYs tfGgDhsim2cvFblje8uotTb1uetyF–8FA7z9oZahgS0SokuZWB-wqAFj_5YPMLvBBdQ_ya tUi5XZQpCHtJOU6H2tSZIFgOGI1Oct7qnchwAY26A6330NJger9TRqIJhHeP50IC8ir6GQP eppuN3LM7C03SyMaxIP2bRFQg

AuthorizationList /api/authorizationlist/jwt/{sessionId}/{principalId}?requestId={requestId}&access_token={access_token} GET

http://localhost:8102/service/hpa/api/authorizationlist/jwt/62dce03d-8d32-4c41-b2ac-a700fc3f3064/310813A951F?requestId=728dce44-cb8e-449a-8b39-5dc6128e2b3f &access_token=1fcd01ac-ccb3-4d41-836f-2ec2d4bbc70c HTTP/1.1

Accept: application/json;charset=UTF-8

Connection: keep-alive

Host: localhost:8102

X-AsiointivaltuudetAuthorization: 42bbe569 2018-01-24T07:16:46.666Z VATdbFlExmxgig78IoUiw/8GCTTx6ca5LVnHtt/9DnY=

HTTP/1.1 200

Cache-Control: no-cache, no-store, max-age=0, must-revalidate

Content-Length: 672

Content-Type: text/plain;charset=UTF-8

Date: Wed, 24 Jan 2018 07:16:46 GMT

Expires: 0

Pragma: no-cache

Set-Cookie: JSESSIONID=5331B72B3886AEF9F619B6890F9C586B;path=/;HttpOnly

X-Application-Context: roles-auths-web-api:8102

X-Content-Type-Options: nosniff

X-Frame-Options: DENY

X-XSS-Protection: 1; mode=block

eyJhbGciOiJSUzI1NiJ9.eyJwcmluY2lwYWwiOiIzMTA4MTNBOTUxRiIsImF1ZCI6ImQ0M2 NmZWI0LTZiMDctNGIzNi05OGVlLWNjMWE4ZjI5YjhhNCIsInN1YiI6IkF1dGhvcml6YXRpb 25MaXN0IiwicmVzcG9uc2UiOiJbXCJBTExcIl0iLCJpc3MiOiJTdW9taS5maS1WYWx0dXVk ZXQiLCJpYXQiOjE1MTY3NzgyMDYsImp0aSI6IjYwYjFjZjJiLTdiMjctNGUxYS05MjNkLWU zM2FlNzhkNzBjYyIsImhldHUiOiIxMjA5NzgtOTAzOCJ9.V9JROf9ZsCDtXVr4Mrs1Z2c9P 2h4WcQ8kKvVRgWNhBpThcute8pZbHZNf4jeVt57-MEsuTVf9Hz-eYBGbdMeH8qwzF_vo4fl p687b6Y7S_PwA-2M01i4rwqWKrVl9Ed37q-PdLuYY7KobDtvQuFa7NPRuQiAFqhsQXPBY7D 6szKQSWP8wlga8CijwSQCVdoUFnr0wVM8mHNq2n60VHFGua1qmlohrsLz0ZDNVSe6xSyO1T EXWYkHAQJB5aWM68Z7Qk722uOaJiDRUCI14M79vrg4zb1lGz47ZhXjQPDtvrOkdmmDutz4T feyOy-OpGcsQDU1927Ew1YExQ1UiKM4dw

organizationRoles(kaikki valitut) /api/organizationRoles/jwt/{sessionId}?requestId={requestId}&access_token={access_token} GET

http://localhost:8102/service/ypa/api/organizationRoles/jwt/2153985a-c294-4132-93a6-bffe7f76f9ef?requestId=66d05035-0805-4d40-b4af-34e5ffc5555c &access_token=4ed4d490-1c59-4888-91ea-51b545575588 HTTP/1.1

Accept: application/json;charset=UTF-8

Connection: keep-alive

Host: localhost:8102

X-AsiointivaltuudetAuthorization: 42bbe569 2018-01-24T07:21:24.13Z 7jKRE0evwaQBKhn7+DVZOv4OWEsxge4sQyZ9ffIqY6k=

HTTP/1.1 200

Cache-Control: no-cache, no-store, max-age=0, must-revalidate

Content-Length: 771

Content-Type: text/plain;charset=UTF-8

Date: Wed, 24 Jan 2018 07:21:24 GMT

Expires: 0

Pragma: no-cache

Set-Cookie: JSESSIONID=FFDD91375F5AE5EC4A5748286897C5FC;path=/;HttpOnly

X-Application-Context: roles-auths-web-api:8102

X-Content-Type-Options: nosniff

X-Frame-Options: DENY

X-XSS-Protection: 1; mode=block

eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJkNDNjZmViNC02YjA3LTRiMzYtOThlZS1jYzFhOG YyOWI4YTQiLCJzdWIiOiJPcmdhbml6YXRpb25hbFJvbGVzIiwicmVzcG9uc2UiOiJbe1wib mFtZVwiOlwiTHVtaSBHbG9iYWwgT3lcIixcImlkZW50aWZpZXJcIjpcIjEyMzQ1NjctMVwi LFwiY29tcGxldGVcIjp0cnVlLFwicm9sZXNcIjpbXCJOSU1LT1wiLFwiVEpcIl19XSIsIml zcyI6IlN1b21pLmZpLVZhbHR1dWRldCIsImlhdCI6MTUxNjc3ODQ4NCwianRpIjoiNTU4Yz E1MTgtMWJlMy00OGJhLWE5NDYtNTAxZTAzMDcxNDAyIiwiaGV0dSI6IjAxMDE4MC05MDI2I n0.i7X37jLjbnSujrtQ3sZyu5XUcJOz7DFpXii9M5FHfeWj9cWUPcrOJwUKnO0tyXqkBltf KsghoMpKH1iu4K0tvA8gm_HSG4cn9r_3Y7zfWsu2ulYwJ57IvKadqB1HMhCo-nWhpE2wt0D HmMTu88sVlvWRcfl3bt2K92xwquz3IJnQTiTpTNOtkOcevag7UWS173fY0fex1YFbIkan3t XOn_mbKw4KghM8m614n_PIUfpaJlDT__lSdqOCYeV5mq05Ekbi0esZzlkJ-mdfqnQKUX2sZ tXqnwExCtcBoN1ee2cKktZmVdmRkxO3D5IC5uE4acwFW-59K7CyqfrE3lAHgQ

organizationRoles(token pyyntö vastauksen lataamista varten) /api/organizationRoles/session/jwt/{sessionId}?requestId={requestId}&access_token={access_token} GET

http://localhost:8102/service/ypa/api/organizationRoles/session/jwt/a093bd1b-02a3-4b6d-b7a8-3eb1d399d468?requestId=768cee20-f53a-4098-9230-68d2086a4b88 &access_token=f6d45628-f22a-4b97-89c1-a17b0fc541b2 HTTP/1.1

Accept: application/json;charset=UTF-8

Connection: keep-alive

Host: localhost:8102

X-AsiointivaltuudetAuthorization: 42bbe569 2018-01-24T07:23:46.489Z 9yD371vWVjmpgGys35vDApwOfaHUfJE+4xD0G5lwJ8g=

HTTP/1.1 200

Cache-Control: no-cache, no-store, max-age=0, must-revalidate

Content-Length: 683

Content-Type: text/plain;charset=UTF-8

Date: Wed, 24 Jan 2018 07:23:46 GMT

Expires: 0

Pragma: no-cache

Set-Cookie: JSESSIONID=58AB381310F7EA6AFF46EF3124FE2EE3;path=/;HttpOnly

X-Application-Context: roles-auths-web-api:8102

X-Content-Type-Options: nosniff

X-Frame-Options: DENY

X-XSS-Protection: 1; mode=block

eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJkNDNjZmViNC02YjA3LTRiMzYtOThlZS1jYzFhOG YyOWI4YTQiLCJzdWIiOiJPcmdhbml6YXRpb25hbFJvbGVzIiwiaXNzIjoiU3VvbWkuZmktV mFsdHV1ZGV0Iiwic2Vzc2lvbklkIjoiXCJhMDkzYmQxYi0wMmEzLTRiNmQtYjdhOC0zZWIx ZDM5OWQ0NjhcIiIsImlhdCI6MTUxNjc3ODYyNiwianRpIjoiYTM4NmNmOTQtZWNkMS00NjM yLWI0NTYtYmZhYmI5ZGEzZmIyIiwiaGV0dSI6IjAxMDE4MC05MDI2In0.Nr3tVNxdoOa2Xn kv_W8LycR1Phz–wYeVoIalqxD4wpsMAjzvrPzHejT4IG8Hp02jomDwg1Q_LR-osJtwS2it gzoS3cT4mIXshkBH556t2INDHeSSGltkN5Biv-4pUyspOZsRDYXB9MnvldWFzGW2XEpuUZ2 MjUQbQM4FETyfIJp5v1WIC97pK-V_OIISbC2lc0Kd3156x4t2NfOMbUWX3Wa9EgUjmRPe0B 0Y8JLK57MR2UnQRWk1ckFkmeIUyUOPQwRvFshDhpQOdjWAv58qCSoM-LJx6r-GaI8zhuKW5 djb0fS2YcaWzdZtzxIZs_2NI4jXAtvBV9CqjkN6D6ENg

organizationRoles(kaikki roolit tokenia käyttäen) /jwt/api/organizationRoles/{jwtToken}/?requestId={requestId}&access_token={access_token} GET

http://localhost:8102/service/ypa/jwt/api/organizationRoles/eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJkNDNjZmViNC02YjA3LTRiMzYtOThlZS1jYzFhOG YyOWI4YTQiLCJzdWIiOiJPcmdhbml6YXRpb25hbFJvbGVzIiwiaXNzIjoiU3VvbWkuZmktV mFsdHV1ZGV0Iiwic2Vzc2lvbklkIjoiXCJhMDkzYmQxYi0wMmEzLTRiNmQtYjdhOC0zZWIx ZDM5OWQ0NjhcIiIsImlhdCI6MTUxNjc3ODYyNiwianRpIjoiYTM4NmNmOTQtZWNkMS00NjM yLWI0NTYtYmZhYmI5ZGEzZmIyIiwiaGV0dSI6IjAxMDE4MC05MDI2In0.Nr3tVNxdoOa2Xn kv_W8LycR1Phz–wYeVoIalqxD4wpsMAjzvrPzHejT4IG8Hp02jomDwg1Q_LR-osJtwS2it gzoS3cT4mIXshkBH556t2INDHeSSGltkN5Biv-4pUyspOZsRDYXB9MnvldWFzGW2XEpuUZ2 MjUQbQM4FETyfIJp5v1WIC97pK-V_OIISbC2lc0Kd3156x4t2NfOMbUWX3Wa9EgUjmRPe0B 0Y8JLK57MR2UnQRWk1ckFkmeIUyUOPQwRvFshDhpQOdjWAv58qCSoM-LJx6r-GaI8zhuKW5 djb0fS2YcaWzdZtzxIZs_2NI4jXAtvBV9CqjkN6D6ENg/  ?requestId=768cee20-f53a-4098-9230-68d2086a4b88  &access_token=f6d45628-f22a-4b97-89c1-a17b0fc541b2 HTTP/1.1

Accept: application/json;charset=UTF-8

Connection: keep-alive

Host: localhost:8102

X-AsiointivaltuudetAuthorization: 42bbe569 2018-01-24T07:23:46.521Z U6Ghn/KKKk0ZGdLRVdDyjVb42j4OwFxn3a13vSnOxbs=

HTTP/1.1 200

Cache-control: no-cache, no-store, max-age=0, must-revalidate

Content-Security-Policy: default-src ’self’; script-src ’self’ ’unsafe-inline’; style-src ’self’ ’unsafe inline’;

Content-Type: application/json;charset=UTF-8

Date: Wed, 24 Jan 2018 07:23:46 GMT

Expires: 0

Pragma: no-cache

Set-Cookie: JSESSIONID=B09F8636BC690D4F6D362535401A7E6A;path=/;HttpOnly

Transfer-Encoding: chunked

X-Application-Context: roles-auths-web-api:8102

X-Content-Type-Options: nosniff

X-Frame-Options: DENY

X-XSS-Protection: 1; mode=block

{ ”complete”: true, ”identifier”: ”1234567-1”, ”name”: ”Lumi Global Oy”, ”roles”: [ ”NIMKO”, ”TJ” ] }

Esimerkki JWT-vastausten tokenit avattuina:

  JWT-vastaus Vastauksen sisältö avattuna
Authorization eyJhbGciOiJSUzI1NiJ9.eyJwcmluY2lwYWwiOiIxMjA1MDhBOTUwRiIsImF1ZCI6ImQ0M2 NmZWI0LTZiMDctNGIzNi05OGVlLWNjMWE4ZjI5YjhhNCIsInN1YiI6IkF1dGhvcml6YXRpb 24iLCJyZXNwb25zZSI6IkFMTE9XRUQiLCJpc3MiOiJTdW9taS5maS1WYWx0dXVkZXQiLCJp YXQiOjE1MTY3NzgwNjksImp0aSI6ImM2YTllODBmLTI0YTgtNGQ5OS05MTBhLWI3YTdiNzk 1M2FlMiIsImhldHUiOiIxMjA5NzgtOTAzOCJ9.uq1vMkVFrBpqQi8JyJHJCvqguyKpgn9o4 XGBUe8nMubqMsvt5pGItBbrGFHoqjZf1jNqvPlnGvsowcyHK69VvRm9JMSVx6ldQ0aCxp2J 8HvpqRIURV0XeOWU-CCP22phoeAb3dfbWen0YYAHl61_j1AlHgvrlWl3mE_E9WbMBkqysYs tfGgDhsim2cvFblje8uotTb1uetyF–8FA7z9oZahgS0SokuZWB-wqAFj_5YPMLvBBdQ_ya tUi5XZQpCHtJOU6H2tSZIFgOGI1Oct7qnchwAY26A6330NJger9TRqIJhHeP50IC8ir6GQP eppuN3LM7C03SyMaxIP2bRFQg
{
  "principal": "120508A950F",
  "aud": "d43cfeb4-6b07-4b36-98ee-cc1a8f29b8a4",
  "sub": "Authorization",
  "response": "ALLOWED",
  "iss": "Suomi.fi-Valtuudet",
  "iat": 1516778069,
  "jti": "c6a9e80f-24a8-4d99-910a-b7a7b7953ae2",
  "hetu": "120978-9038"
}
AuthorizationList eyJhbGciOiJSUzI1NiJ9.eyJwcmluY2lwYWwiOiIzMTA4MTNBOTUxRiIsImF1ZCI6ImQ0M2 NmZWI0LTZiMDctNGIzNi05OGVlLWNjMWE4ZjI5YjhhNCIsInN1YiI6IkF1dGhvcml6YXRpb 25MaXN0IiwicmVzcG9uc2UiOiJbXCJBTExcIl0iLCJpc3MiOiJTdW9taS5maS1WYWx0dXVk ZXQiLCJpYXQiOjE1MTY3NzgyMDYsImp0aSI6IjYwYjFjZjJiLTdiMjctNGUxYS05MjNkLWU zM2FlNzhkNzBjYyIsImhldHUiOiIxMjA5NzgtOTAzOCJ9.V9JROf9ZsCDtXVr4Mrs1Z2c9P 2h4WcQ8kKvVRgWNhBpThcute8pZbHZNf4jeVt57-MEsuTVf9Hz-eYBGbdMeH8qwzF_vo4fl p687b6Y7S_PwA-2M01i4rwqWKrVl9Ed37q-PdLuYY7KobDtvQuFa7NPRuQiAFqhsQXPBY7D 6szKQSWP8wlga8CijwSQCVdoUFnr0wVM8mHNq2n60VHFGua1qmlohrsLz0ZDNVSe6xSyO1T EXWYkHAQJB5aWM68Z7Qk722uOaJiDRUCI14M79vrg4zb1lGz47ZhXjQPDtvrOkdmmDutz4T feyOy-OpGcsQDU1927Ew1YExQ1UiKM4dw
{
   "principal": "310813A951F",
   "aud": "d43cfeb4-6b07-4b36-98ee-cc1a8f29b8a4",
   "sub": "AuthorizationList",
   "response": "[\"ALL\"]",
   "iss": "[Suomi.fi-Valtuudet",
   "iat": 1516778206,
   "jti": "60b1cf2b-7b27-4e1a-923d-e33ae78d70cc",
   "hetu": "120978-9038"
}
organizationRoles(kaikki valitut) eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJkNDNjZmViNC02YjA3LTRiMzYtOThlZS1jYzFhOG YyOWI4YTQiLCJzdWIiOiJPcmdhbml6YXRpb25hbFJvbGVzIiwicmVzcG9uc2UiOiJbe1wib mFtZVwiOlwiTHVtaSBHbG9iYWwgT3lcIixcImlkZW50aWZpZXJcIjpcIjEyMzQ1NjctMVwi LFwiY29tcGxldGVcIjp0cnVlLFwicm9sZXNcIjpbXCJOSU1LT1wiLFwiVEpcIl19XSIsIml zcyI6IlN1b21pLmZpLVZhbHR1dWRldCIsImlhdCI6MTUxNjc3ODQ4NCwianRpIjoiNTU4Yz E1MTgtMWJlMy00OGJhLWE5NDYtNTAxZTAzMDcxNDAyIiwiaGV0dSI6IjAxMDE4MC05MDI2I n0.i7X37jLjbnSujrtQ3sZyu5XUcJOz7DFpXii9M5FHfeWj9cWUPcrOJwUKnO0tyXqkBltf KsghoMpKH1iu4K0tvA8gm_HSG4cn9r_3Y7zfWsu2ulYwJ57IvKadqB1HMhCo-nWhpE2wt0D HmMTu88sVlvWRcfl3bt2K92xwquz3IJnQTiTpTNOtkOcevag7UWS173fY0fex1YFbIkan3t XOn_mbKw4KghM8m614n_PIUfpaJlDT__lSdqOCYeV5mq05Ekbi0esZzlkJ-mdfqnQKUX2sZ tXqnwExCtcBoN1ee2cKktZmVdmRkxO3D5IC5uE4acwFW-59K7CyqfrE3lAHgQ
{
   "aud": "d43cfeb4-6b07-4b36-98ee-cc1a8f29b8a4",
   "sub": "OrganizationalRoles",
   "response": "[{\"name\":\"Lumi Global Oy\",\"identifier\":\"1234567-1\",\"complete\":true,\"roles\":[\"NIMKO\",\"TJ\"]}]",
   "iss": "[Suomi.fi-Valtuudet",
   "iat": 1516778484,
   "jti": "558c1518-1be3-48ba-a946-501e03071402",    
   "hetu": "010180-9026"
}
organizationRoles(token pyyntö vastauksen lataamista varten) eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJkNDNjZmViNC02YjA3LTRiMzYtOThlZS1jYzFhOG YyOWI4YTQiLCJzdWIiOiJPcmdhbml6YXRpb25hbFJvbGVzIiwiaXNzIjoiU3VvbWkuZmktV mFsdHV1ZGV0Iiwic2Vzc2lvbklkIjoiXCJhMDkzYmQxYi0wMmEzLTRiNmQtYjdhOC0zZWIx ZDM5OWQ0NjhcIiIsImlhdCI6MTUxNjc3ODYyNiwianRpIjoiYTM4NmNmOTQtZWNkMS00NjM yLWI0NTYtYmZhYmI5ZGEzZmIyIiwiaGV0dSI6IjAxMDE4MC05MDI2In0.Nr3tVNxdoOa2Xn kv_W8LycR1Phz–wYeVoIalqxD4wpsMAjzvrPzHejT4IG8Hp02jomDwg1Q_LR-osJtwS2it gzoS3cT4mIXshkBH556t2INDHeSSGltkN5Biv-4pUyspOZsRDYXB9MnvldWFzGW2XEpuUZ2 MjUQbQM4FETyfIJp5v1WIC97pK-V_OIISbC2lc0Kd3156x4t2NfOMbUWX3Wa9EgUjmRPe0B 0Y8JLK57MR2UnQRWk1ckFkmeIUyUOPQwRvFshDhpQOdjWAv58qCSoM-LJx6r-GaI8zhuKW5 djb0fS2YcaWzdZtzxIZs_2NI4jXAtvBV9CqjkN6D6ENg
{
  "aud": "d43cfeb4-6b07-4b36-98ee-cc1a8f29b8a4",
  "sub": "OrganizationalRoles",
  "iss": "Suomi.fi-Valtuudet",
  "sessionId": "\"a093bd1b-02a3-4b6d-b7a8-3eb1d399d468\"",
  "iat": 1516778626,
  "jti": "a386cf94-ecd1-4632-b456-bfabb9da3fb2",
  "hetu": "010180-9026"
}

4.8 Authorization REST-rajapinta

Rest-kutsussa välitetään clientId, asioivan henkilön tunniste sekä puolesta-asioinnin kohteen tunniste. Lisäksi pyynnön mukana voi antaa valtuuskoodin jota asiointi koskee.
Authorization-vastaus sisältää tiedon siitä, onko asiamiehellä valitun päämiehen puolesta asiointioikeus. Asiointioikeus ilmaistaan kentässä ”authorization”, jonka arvona palautetaan joko positiivinen päätös ALLOWED tai negatiivinen päätös DISALLOWED. Mikäli vastaus on DISALLOWED ja palvelulle on sallittu näyttää hylkäysperusteet, palautetaan ne listan reason-kentissä.
Onnistuneen kyselyn vastaussanoma kuvataan alla olevassa taulukossa.

Taulukko 5. Authorization-vastaussanoman kuvaus

Elementin nimi

Tyyppi

Kuvaus

Arvojoukko

result string Päätöstieto onko puolesta-asiointi valitussa kontekstissa sallittu ”ALLOWED” tai ”DISALLOWED”
reasons array<DecisionReason> Arvo ehdollinen. ”reason”-elementtejä voi olla useampia, yksi jokaista hylkäämisperustetta kohden. 
Kentän käytöstä sovitaan palvelusopimuksessa erikseen.
n* reason[rule, value]
Kenttä rule sisältää kyseisen säännön tunnisteen ja value syyn lokalisointiavaimen

DecisionReason

Elementin nimi

Tyyppi

Kuvaus

Arvojoukko

reasonRule string
reasonValue string
valueType string ”DESCRIPTION”, ”EXCEPTION”

Rajapinnan osoite ja pyyntöesimerkki

authorization rest {rova_host}/service/rest/hpa/authorization/{delegateId}/{principalId}?requestId={requestId}&issue={issue_uri} GET /service/rest/hpa/authorization/42bbe569/010180-9026/310813A951F?requestId=testClientRequestId HTTP/1.1

X-AsiointivaltuudetAuthorization: 42bbe569 2018-06-04T13:29:34.404Z ULETcXn2xNTb4m7CNeSH++GEgjbKqdaCKF2QFA265DU=

X-userId: rova-demo-user

Host: localhost:8102

Connection: Keep-Alive

Accept: application/json;charset=UTF-8

Accept-Encoding: gzip,deflate

HTTP/1.1 200

Pragma: no-cache

Expires: 0

Cache-control: no-cache, no-store, max-age=0, must-revalidate

X-Content-Type-Options: nosniff

X-XSS-Protection: 1; mode=block

X-Frame-Options: DENY

Set-Cookie: JSESSIONID=F443FAB19C3D112017BC543A705F91C0; Path=/; HttpOnly

Content-Security-Policy: default-src ’self’; style-src ’self’ ’unsafe-inline’;

X-Application-Context: roles-auths-web-api:dev:8102

Content-Type: application/json;charset=UTF-8

Transfer-Encoding: chunked

Date: Mon, 04 Jun 2018 13:29:38 GMT

21

{”reasons”:[],”result”:”ALLOWED”}

0

4.9 Virheviestit

Virheellisistä kutsuista palautetaan virhettä vastaava HTTP status, mahdollinen virheviesti ja ReqId-tunniste, joka on Asiointivaltuudet-palvelun sisäinen tunniste pyynnölle.

Esimerkkivastaus virhetilanteessa
HTTP/1.1 500 Internal Server Error

Server: Apache-Coyote/1.1

Pragma: no-cache

Expires: 0

Cache-control: no-cache, no-store, max-age=0, must-revalidate

X-Content-Type-Options: nosniff

X-XSS-Protection: 1; mode=block

Cache-Control: no-cache, no-store, max-age=0, must-revalidate

Pragma: no-cache

Expires: 0

X-Frame-Options: DENY

Content-Security-Policy: default-src ’self’; script-src ’self’ ’unsafe-inline’; style-src ’self’ ’unsafe-inline’;

X-Application-Context: application:8102

Content-Type: application/json;charset=UTF-8

Transfer-Encoding: chunked

Date: Wed, 15 Jun 2016 10:32:20 GMT

Connection: close

{”errorMessage”:”HTTP 500 Internal Server Error”,”errorCode”:”OTHER_EXCEPTION”,”ReqID”:”0STUQMODABLJ5ZW”}

5. Tarkenteista

Tarkenteiden tyypit ja nimet on määritelty valtuuskoodistossa. Jos valtuuskoodille on määritelty rajaustarkenteita, on ne lisätty vastauksessa valtuuskoodin tunnisteen perään avain-arvo pareina;

  1. PRINCIPAL_ID tyyppisen tarkenteen arvo kertoo valtuuttajan tunnisteen.
  2. DEFAULT tyyppisen tarkenteen arvon merkitys riippuu asiayhteydestä eikä järjestelmä ota siihen kantaa.
  3. Mikäli halutaan käsitellä myös aliorganisaatioihin liittyvät Katso-roolit, tulee valtuuskoodilla olla tarkenne, jonka matcherType on KATSO_SUB_ORGANIZATION.

Aiemmassa organizationRoles esimerkkivastauksessa on principalId niminen tarkenne, joka on tyyppiä PRINCIPAL_ID ja arvo kertoo valtuuttajan. Vastauksessa on myös subOrganization niminen tarkenne, joka on tyyppiä DEFAULT ja jonka matcherType on KATSO_SUB_ORGANIZATION. Tarkenteen nimen perusteella valtuus on rajattu koskemaan tiettyä aliorganisaatiota ja matcherTypen perusteella voidaan päätellä, että valtuus voi tulla joko Valtuusrekisteristä tai Katso-palvelusta.

6. Huomioita tietoturvasta

Asiointivaltuudet-palvelu käyttää OAuth 2.0 -protokollaa valtuutusprosessin tietoturvalliseen käsittelyyn. OAuth:n korrekti käyttö asettaa vaatimuksia valtuutuspalvelua käyttävälle asiointipalvelulle. Yleistä tietoa OAuth 2.0:n tietoturvasta voi lukea OAuth:n määrittelydokumentista: {+}http://tools.ietf.org/html/rfc6749#section-10+

6.1. Asiointipalvelun täytyy olla suojattu CSRF-hyökkäyksiä vastaan

Kun loppukäyttäjä on kirjautuneena asiointipalveluun, on hän potentiaalisesti altis CSRF-hyökkäyksille, joissa toisesta palvelusta käsin linkitetään käyttäjän huomaamatta asiointipalvelun toimintoja. Asiointipalvelun täytyy sisältää CSRF-suojaus, jotta sen toimintoja ei pystytä kutsumaan asiointipalvelun ulkopuolelta.
Lisätietoa: {+}http://en.wikipedia.org/wiki/CSRF+{+}http://tools.ietf.org/html/rfc6749#section-10.12+

6.2. Asiointipalvelun täytyy luoda ja varmentaa OAuth state-parametri

Kun asiointipalvelu aloittaa OAuth-valtuutuksen, täytyy sen tuottaa uniikki tunniste ja liittää se mukaan pyyntöön OAuth:n state-parametrina. Suositeltavia vaihtoehtoja ovat esimerkiksi täysin satunnainen käyttäjäsessioon tallennettu tunniste tai tiiviste käyttäjäsession tunnisteesta ja asiointipalvelun omasta salaisuudesta. Asiointivaltuudet palauttaa state-parametrin OAuth-vastauksen mukana, minkä avulla asiointipalvelun täytyy varmentaa, että käsiteltävä vastaus on peräisin asiointipalvelun aloittamasta tunnistuksesta.
Tämä vaatimus täyttyy käytettäessä roles-auths-client -kirjastoa.
Lisätietoa: {+}http://www.twobotechnologies.com/blog/2014/02/importance-of-state-in-oauth2.html+

6.3. Valtuuttamisen paluuosoite pitää olla kirjattuna sallituksi uudelleenohjausosoitteeksi

Kun asiointipalvelu aloittaa OAuth-valtuutusprosessin se välittää asiointivaltuuspalvelulle uudelleenohjausosoitteen johon käyttäjän selain ohjataan valtuutuksen päätteeksi. Jotta paluupyynnön mukana välitettävä OAuth-avain ei päädy väärin käsiin, rajoittaa asiointivaltuudet-palvelu uudelleenohjauksen vain sille ennalta määriteltyihin osoitteisiin. Asiointipalvelun on toimitettava tieto täsmällisistä uudelleenohjausosoitteista asiontivaltuudet-palvelulle liityntäprosessin yhteydessä.
Lisätietoa: {+}http://security.stackexchange.com/questions/44214/what-is-the-purpose-of-oauth-2-0-redirect-uri-checking+

6.4. Asiointipalvelun täytyy päättää asiointivaltuuspalvelun istunto valtuutuksien tarkistamisen jälkeen

Kun Web APIa käyttävä asiointipalvelu on tehnyt tarvittavat valtuutuskyselyt, on sen suljettava istunto unregister-toiminnolla. Muussa tapauksessa istunnon sulkeminen jää aikakatkaisun vastuulle.

6.5. Asiointipalvelu ei saa paljastaa asiointivaltuuspalvelun palauttamia virheviestejä loppukäyttäjälle

Ongelmatilanteiden selvityksen helpottamiseksi asiointivaltuuspalvelu saattaa palauttaa osana virheviestiä tietoa sisäisten komponenttien toiminnasta, tai tunnisteita jotka ovat tarkoitettu vain asiointi- ja asiointivaltuuspalvelun väliseen käyttöön. Asiointipalvelu ei saa näyttää virheviestejä loppukäyttäjälle sellaisenaan.


Dokumentin tiedot

SELRES_0.0922571393185927SELRES_0.0922571393185927SELRES_0.0922571393185927

Versionro Mitä tehty Pvm/henkilö
1.0 Dokumentti luotu 02.06.16/NP
2.0  Lisätty esimerkkipyynnöt ja -vastaukset, tietoturvavaatimukset  27.06.16 / NP
3.0  Päivityksiä  09.12.16 / NP
4.0 Lisätty tarkistesumman verifiointi ja kohtaan 4 huomio, etteivät kaikki rajapinnat ole välttämättä luvitettuja asiakkaalle. 27.02.17 / NP
5.0 Lisätty kohtaan 4 huomio etteivät kaikki rajapinnat ole välttämättä luvitettuja asiakkaalle.
Lisätty esimerkki AuthorizationList-rajapinnan käytöstä.
28.11.17 / NP
6.0 Lisätty tietoa JWT-rajapinnoista. Täsmennetty api keyn laskentatavan kuvausta, korjattu JWT-tokenien avaimet. Avattu JWT-tokenien sisältö 25.1.1 / EJ
7.0 Dokumenttia päivitetty 01.03.2019/ EJ
7.1 Dokumenttia päivitetty tarkenteiden osalta 08.04.2019/ EJ

Yksilöintitunnus: JTO21