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

Print Friendly, PDF & Email

 


1. Yleistä

Web-API rajapinta tarjoaa valintakäyttöliittymän toisen puolesta asioinnin kohteiden valintaan sekä REST-kyselyrajapinnat asiointioikeuskyselyiden tekemiseen.

Rajapinnan kutsumisessa hyödynnetään REST / JSON -rajapintoja, jotka on suojattu joko API key-, OAuth2- +API key-suojauksella.

Asiointipalvelua rekisteröidessä Valtuudet-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

2. 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
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önneinen erotettuna. Lähdeaineistosta lasketaan HMACSHA256 -tiiviste, jonka salaus avaimena 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.
 

Web Api Client ID

Asiointipalvelukohtainen asiakastunniste

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 osoitteesta http://tools.ietf.org/html/rfc6749.

OAuth2-rajapinnan kutsumiseen tarvitaan seuraavat tiedot:

Kuvaus
client_id Asiakkaan tunniste
client_secret Asiakkaan salasana

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 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=
User-Agent: Java/1.8.0_91
Host: localhost:18102
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
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=
User-Agent: Java/1.8.0_91
Host: localhost:18102
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
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?requestId=requestId HTTP/1.1
X-AsiointivaltuudetAuthorization: f5f0d662 2016-09-14T08:48:15.503Z Kt2vtNGi3FIDsTeEgAcJfqR17N+jYAOOW/XA48VEGf0=
User-Agent: Java/1.8.0_73
Host: localhost:18102
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
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 GMT64
{”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?requestId=requestId HTTP/1.1
X-AsiointivaltuudetAuthorization: f5f0d662 2016-09-14T08:56:20.32Z gKmAJz9XpqhQFlvGcLLqTxxWaGrfbJOLdZtzgRiQRiY=
User-Agent: Java/1.8.0_73
Host: localhost:8102
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
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 GMT64
{”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 asiakasorganisaation käytettävissä.

Vastaus:

 Vastauskenttä 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. Henkilön puolesta asiointi

HPA REST-kutsujen palveluosoitteet:

Get URL Esimerkkipyyntö Esimerkkivastaus
Delegate {rova_host}/service/hpa/api/delegate/{sessionId}?requestId={requestId} 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=
User-Agent: Java/1.8.0_91
Host: localhost:18102
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
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}  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=
User-Agent: Java/1.8.0_91
Host: localhost:18102
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
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} 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=
User-Agent: Java/1.8.0_111
Host: localhost:8102
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
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
hetu string Register-pyynnössä välitetty hetu
 principals  array<Principal>  Lista päämiesten perustiedoista  Lista n*[principal [personId,name]] tai tyhjä lista
 service  string  Register-pyynnössä välitetty service_id:tä vastaava XRoadServiceIdentifier
 sessionId  string  Register-pyynnön vastauksessa annettu sessionId
 type  string  ”HPA”

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ä oikeus asioida valitun päämiehen puolesta. 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 2. Authorization-vastaussanoman kuvaus.

Elementin nimi Tyyppi Kuvaus Arvojoukko
result string Päätöstieto, onko toisen 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 lokalisointiavaimenn* 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, asiointioikeustarkistuksen kohteen personId.

AuthorizationList-vastaus sisältää tiedon asiointirooleista, joihin asiamiehellä on oikeus asioida valitun päämiehen puolesta. 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 3. 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  ”DESCRIPTION”, ”EXCEPTION”

 

4.4. YPA

YPA REST-kutsujen palveluosoitteet:

Get URL Esimerkkipyyntö  Esimerkkivastaus
organiszationRoles (all selected) {rova_host}/service/ypa/api/organizationRoles/{sessionId}?requestId={requestId} 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=
User-Agent: Java/1.8.0_91
Host: localhost:18102
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
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”], ”complete”:true}]
organiszationRoles (one) {rova_host}/service/ypa/api/organizationRoles/{sessionId}/{organizationId}?requestId={requestId} 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=
User-Agent: Java/1.8.0_91
Host: localhost:18102
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
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”],
”complete”:true}]

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

Taulukko 3. OrganizationRoles-vastaussanoman kuvaus.

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

OrganizationList-elementin kuvaus:

Elementin nimi Tyyppi 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 yksi 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 siirto tunniste (transfer_token), joka välitetään seuraavalle asiointipalvelulle. Katso-session aloitus siirto-siirto -toiminnallisuus.

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=
User-Agent: Java/1.8.0_73
Host: localhost:8102
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
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 GMT8UYQjnIY4vpU8DQVzviGDqH7Kxt9sW5W
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=
User-Agent: Java/1.8.0_73
Host: localhost:18102
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
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 GMTLWrF1SN4OE6ZaTrnolyfxf1JdFFcHT-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=
User-Agent: Java/1.8.0_91
Host: localhost:18102
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
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 GMTtrue
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=
User-Agent: Java/1.8.0_91
Host: localhost:18102
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
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 GMTtrue

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ö

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

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}  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: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
connection”: keep-alive
Host: localhost:8102
User-Agent”: Java/1.8.0_161
A-AsiointivaltuudetAuthorization: 42bbe569 2018-01-24T07:14:28.431Z 2LAP79FYt/GQh9Xisc/00bobUbQWhG9Vuu0HtoXDXfs=
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=blockeyJhbGciOiJSUzI1NiJ9.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}  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: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2″
Connection: keep-alive
Host: localhost:8102
User-Agent:
Java/1.8.0_161
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=blockeyJhbGciOiJSUzI1NiJ9.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}  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: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive
Host: localhost:8102
User-Agent: Java/1.8.0_161
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=blockeyJhbGciOiJSUzI1NiJ9.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}  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: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive
Host: localhost:8102
User-Agent: Java/1.8.0_161
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=blockeyJhbGciOiJSUzI1NiJ9.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}  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: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive
Host: localhost:8102
User-Agent: Java/1.8.0_161
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” ] }

Esimerkkivastausten 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 Virheviestit

Virheellisistä kutsuista palautetaan virhettä vastaava HTTP-status, mahdollinen virheviesti ja ReqId-tunniste, joka on Valtuudet-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 Huomioita tietoturvasta

Valtuudet-palvelu käyttää OAuth 2.0 -protokollaa valtuutusprosessin tietoturvalliseen käsittelyyn. OAuth:n oikea käyttö asettaa vaatimuksia Valtuudet-palvelua 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

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

Kun loppukäyttäjä on kirjautuneena asiointipalveluun, hän on potentiaalisesti altis CSRF-hyökkäyksille, joissa linkitetään käyttäjän huomaamatta toisesta palvelusta 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

5.2 Asiointipalvelun täytyy luoda ja varmentaa OAuth state-parametri

Kun asiointipalvelu aloittaa OAuth-valtuutuksen, sen täytyy 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. Valtuudet-palvelu 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

5.3 Valtuuttamisen paluuosoite pitää olla kirjattuna sallituksi uudelleenohjausosoitteeksi

Kun asiointipalvelu aloittaa OAuth-valtuutusprosessin, se välittää Valtuudet-palvelulle uudelleenohjausosoitteen, johon käyttäjän selain ohjataan valtuuttamisen päätteeksi. Jotta paluupyynnön mukana välitettävä OAuth-avain ei päädy väärin käsiin, Valtuudet-palvelu rajoittaa uudelleenohjauksen vain sille ennalta määriteltyihin osoitteisiin. Asiointipalvelun on toimitettava tieto täsmällisistä uudelleenohjausosoitteista Valtuudet-palvelulle liityntäprosessin yhteydessä.

Lisätietoa: http://security.stackexchange.com/questions/44214/what-is-the-purpose-of-oauth-2-0-redirect-uri-checking

5.4 Asiointipalvelun täytyy päättää Valtuudet-palvelun 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.

5.5 Asiointipalvelu ei saa paljastaa Valtuudet-palvelun palauttamia virheviestejä loppukäyttäjälle

Ongelmatilanteiden selvityksen helpottamiseksi Valtuudet-palvelu saattaa palauttaa osana virheviestiä tietoa sisäisten komponenttien toiminnasta tai tunnisteita, jotka ovat tarkoitettu vain asiointipalvelun ja Valtuudet-palvelun 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

Yksilöintitunnus: JTO21