Web API -rajapinta ja valintakäyttöliittymä
Web API -rajapinta tarjoaa valintakäyttöliittymän, jonka kautta valitaan toisen puolesta asioinnin kohteet eli ne henkilöt, joita valtuuksien antaminen koskee. Web API -rajapinta tarjoaa myös REST-kyselyrajapinnat, joiden kautta tehdään asiointioikeuskyselyjä eli selvitetään, onko henkilöllä oikeus asioida toisen puolesta.
Rajapinnan kutsumisessa hyödynnetään REST-/JSON-rajapintoja, jotka on suojattu joko API Key- tai OAuth2 +API Key -suojauksella.
Asiointipalvelu tarvitsee Valtuudet-palvelun kutsumiseen alla näkyvät tiedot. Digi- ja väestötietovirasto toimittaa asiakasorganisaatiolle asiointipalvelun rekisteröinnin yhteydessä Web API Client ID -tunnisteen, API Keyn ja Oauth-salasanan.
- Web API Client ID: 8-merkkinen alfanumeerinen tunniste
- API Key: merkkijono
- Oauth-salasana: OAuth-salasana
Jos Web API -sessio on vanhentunut, rajapinta palauttaa HTTP 401 -vastauksen.
Valtuudet-palvelun kutsumiseen tarvittavat tiedot
Nämä tiedot saa käyttöönottotiimiltä käyttölupahakemuksen käsittelyn jälkeen. Aloita Valtuudet-palvelun käyttöönotto lähettämällä hakemus Palveluhallinta.suomi.fi-sivustollaAvautuu uuteen ikkunaan..
Tunniste | Kuvaus | Käyttötarkoitus |
|---|---|---|
Web API Client ID | 8-merkkinen alfanumeerinen tunniste | Kutsuvan asiointipalvelun yksilöivä käyttäjätunnus Web -APIn rajapinnoissa. |
API Key | merkkijono | Käytetään X-AsiointivaltuudetAuthorization otsakkeessa välitettävän tarkistesumman laskentaan Web-APIn rest-rajapinnoissa. |
client_id | OAuth-tunniste | Käytetään X-AsiointivaltuudetAuthorization otsakkeessa välitettävän tarkistesumman laskentaan Web-APIn OAuth-rajapinnoissa. |
client_secret | OAuth-salasana | Käytetään Authorization otsakkeessa välitettävänä salasanana Web-APIn OAuth -rajapinnoissa. |
API Key -suojattujen rajapintojen kutsumisessa tarvittava API Key -tunnistetieto välitetään X-AsiointivaltuudetAuthorization-HTTP-headerissa. Headerin arvoksi laitetaan Web API Client ID, aikaleima ja tarkistesumma välilyönnein erotettuina. Näiden tarkemmat kuvaukset on esitetty alla näkyvässä taulukossa.
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 ±5 minuuttia. |
tarkistesumma | Tarkistesumma lasketaan pyynnön polusta ja aikaleimasta välilyönnein erotettuina. Lähdeaineistosta lasketaan HMAC-SHA256-tiiviste, jonka salausavain on API Key. Tuloksena saatu binäärimuotoinen tiiviste Base64-enkoodataan.
|
Tarkistesumman laskemiseen toteutetun funktion verifiointi
Alla olevilla syötteillä voit varmistaa, että tarkistesumman laskemiseen toteutettu funktio toimii asianmukaisesti. Kun annat funktiolle alla olevat syötteet, lopputuloksen tulee olla sama kuin alla.
Path = ”/service/hpa/user/register/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=
OAuth2-suojattujen rajapintojen kutsumiseen tarvitaan client_id eli asiakkaan tunniste ja client_secret eli asiakkaan salasana (ks. taulukko 3).
OAuth2-rajapinnan kutsumiseen tarvittavat tiedot:
- client_id: asiakkaan tunniste
- client_secret: asiakkaan salasana
OAuth2-rajapintaan on määritelty kaksi endpointia eli päätepistettä, jotka kuvataan URL- eli verkko-osoitteina. Ne on kuvattu alla näkyvässä taulukossa.
URL | Kuvaus |
|---|---|
{rova_host}/oauth/authorize&client_id=web-api-client&response_type=code | URL, johon käyttäjä ohjataan valintojen tekemistä varten.
Vastaus:
|
Esimerkkipyyntö:
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
Esimerkkivastaus:
Esimerkki uudelleenohjauksesta:
http://localhost:8901/hpa_web_api.html?code=3lN85M&state=fbd24182-016c-45ea-ae9c-630a4b00188f
URL | Kuvaus |
|---|---|
POST {rova_host}/oauth/token?grant_type=authorization_code | Token URL, jossa valintakäyttöliittymältä tullut code voidaan vaihtaa OAuth tokeniin.
|
Esimerkkipyyntö:
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
Esimerkkivastaus:
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”}
Pyyntö- ja loppukäyttäjätunnisteet
Web API -rajapintaan lähetettävissä pyynnöissä tulee olla pyyntötunniste (requestId). Pyyntötunniste on pyynnön yksilöivä tunniste, jolla yksittäinen tapahtuma voidaan tunnistaa lokeista.
Web API -session aloitus eli rekisteröintipyyntö
Taulukossa on kuvattu Web API -session aloittamisessa eli rekisteröintipyynnössä käytettävien REST-kutsujen palveluosoitteet sekä esimerkkipyynnöt ja -vastaukset.
Henkilön puolesta asiointi (HPA)
GET URL: {rova_host}/service/hpa/user/register/{service_id}/{personId}?requestId={requestId}
Esimerkkipyyntö:
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
Esimerkkivastaus:
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″}
Yrityksen puolesta asiointi (YPA)
GET URL: {rova_host}/service/ypa/user/register/{service_id}/{personId}?requestId={requestId}
Esimerkkipyyntö:
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
Esimerkkivastaus:
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″}
Henkilön puolesta asiointi (HPA), siirretty
GET URL: {rova_host}/service/hpa/user/register/transfer/{transfer_token}/{service_id}/{personId}?requestId={requestId}
Esimerkkipyyntö:
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=
Accept: application/json;charset=UTF-8
Host: localhost:18102
Connection: keep-alive
Esimerkkivastaus:
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
Yrityksen puolesta asiointi (YPA), siirretty
GET URL: {rova_host}/service/ypa/user/register/transfer/{transfer_token}/{service_id}/{personId}?requestId={requestId}
Esimerkkipyyntö:
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
Esimerkkivastaus:
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ä.
Rekisteröintipyynnössä tulee olla X-AsiointivaltuudetAuthorization-header.
Alla on kuvattu rekisteröintipyyntöön saadun vastauksen kentät.
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. |
Alla on kuvattu REST-kutsujen palveluosoitteet sekä esimerkkipyynnöt ja -vastaukset henkilön puolesta asioinnissa. Käytössä on kolme rajapintaa:
- Delegate-rajapinnan kautta haetaan asiamiehen henkilötunnuksen tai muun tunnisteen perusteella kaikki hänen päämiehensä eli ne henkilöt, joiden puolesta hänellä on oikeus asioida.
- Authorization-rajapinnan kautta tarkistetaan, onko asiamiehellä oikeus hoitaa tiettyä asiaa päämiehen puolesta.
- AuthorizationList-rajapinnan kautta saadaan selville, missä asioissa asiamiehellä on oikeus asioida päämiehen puolesta.
Access_token luetaan joko Authorization: Bearer -headerista tai URL-parametrista.
Delegate
GET URL: {rova_host}/service/hpa/api/delegate/{sessionId}?requestId={requestId}&access_token={access_token}
Esimerkkipyyntö:
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
Esimerkkivastaus:
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
GET URL: {rova_host}/service/hpa/api/authorization/{sessionId}/{personId}?requestId={requestId}&issues={issues}&access_token={access_token}
Issues-parametrin arvona on URI, johon haetaan valtuutusta. Parametri ei ole pakollinen. Niitä voi olla useita. Parametrissa määritelty URI voi sisältää query-parametreina määriteltyjä tarkenteita. Jos tarkenteita käytetään URIssa, niiden avaimet ja arvot tulee esittää URL-koodatussa muodossa.
Esimerkkipyyntö:
GET /service/hpa/api/authorization/7407df88-8fbe-4e16-94fd-05467963b49e/120508A950F?requestId=testClientRequestId&issues=http%3A%2F%2Fvaltuusrekisteri.suomi.fi%2Fpalkkatietojen_ilmoittaminen%3FprincipalId%3D120508A950F%26subOrganization%3D134567-1 HTTP/1.1
X-AsiointivaltuudetAuthorization: 42bbe569 2016-06-13T11:48:02.087Z vFxeTk/6oJlqHxhkE3YTyuTQh7X2SMrB/XhvAvemIuQ=
Host: localhost:18102
Accept: application/json;charset=UTF-8
Connection: keep-alive
Esimerkkivastaus:
X-AsiointivaltuudetAuthorization: 42bbe569 2016-06-13T11:48:02.087Z vFxeTk/6oJlqHxhkE3YTyuTQh7X2SMrB/XhvAvemIuQ=
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
[{"reasons":[],"result":"ALLOWED","principal":{"personId":"010316A998C","name":"Pekkala Esko-Olli"}}]
AuthorizationList
GET URL: {rova_host}/service/hpa/api/authorizationlist/{sessionId}/{personId}?requestId={requestId}&access_token={access_token}
Esimerkkipyyntö:
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
Esimerkkivastaus:
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"],"principal":{"personId":"010316A998C","name":"Pekkala Esko-Olli"}}]
Delegate
Delegate-rajapinnan kautta haetaan lista päämiehistä eli niistä henkilöistä, joiden puolesta asiamiehellä on oikeus asioida.
REST-kutsussa välitetään rekisteröintipyynnön vastauksena saatu sessionId.
Taulukossa on kuvattu Delegate-vastaussanoman elementit.
Elementin nimi | Tyyppi | Kuvaus | Arvojoukko |
|---|---|---|---|
principals | array<Principal> | lista päämiesten perustiedoista | lista n*[principal [personId,name]] tai tyhjä lista |
Taulukossa on kuvattu Principal-elementti, joka sisältää elementit personId ja name.
Elementin nimi | Tyyppi | Kuvaus |
|---|---|---|
personId | string | henkilötunnus tai UID |
name | string | nimi |
Arvojoukko: Nimi koostuu henkilön sukunimestä ja etunimistä, jotka on oletuksena erotettu toisistaan välilyönnillä. Sukunimen ja etunimien välistä erotinta voi muuttaa palvelukohtaisesti.
Erotin on enintään kahden merkin mittainen ja voi sisältää seuraavia merkkejä: " ,\-.:;_".
Etunimet erotetaan toisistaan aina välilyönnillä. Nimet esitetään, mikäli ne ovat saatavilla.
Authorization
Authorization-rajapinnan kautta tarkistetaan, onko asiamiehellä oikeus hoitaa tiettyä asiaa päämiehen puolesta.
REST-kutsussa välitetään rekisteröintipyynnön vastauksena saatu sessionId, asiointioikeustarkistuksen kohteen personId sekä minkä asian hoitamisen valtuus tarkistetaan.
Authorization-vastaus sisältää tiedon siitä, onko asiamiehellä oikeus asioida päämiehen puolesta. Asiointioikeus ilmaistaan authorization-kentässä, jonka arvona palautetaan joko positiivinen päätös ALLOWED tai negatiivinen päätös DISALLOWED. Jos vastaus on DISALLOWED ja palvelulle on sallittu näyttää hylkäysperusteet, ne palautetaan listan reason-kentissä.
Taulukossa on kuvattu onnistuneen Authorization-kyselyn vastaussanoma.
Elementin nimi | Tyyppi | Kuvaus | Arvojoukko |
|---|---|---|---|
result | string | Tieto siitä, onko asiamiehellä oikeus asioida päämiehen puolesta kyseisessä asiassa. | ALLOWED tai DISALLOWED |
reasons | array<DecisionReason> | Arvo ehdollinen. Elementtejä voi olla useampia, yksi jokaista hylkäämisperustetta kohden. Käytöstä sovitaan palvelusopimuksessa erikseen. | n* reason[rule, value] |
Taulukossa on kuvattu DecisionReason-elementti, joka sisältää elementit reasonRule, reasonValue ja valueType.
Elementin nimi | Tyyppi | Kuvaus | Arvojoukko |
|---|---|---|---|
reasonRule | string | kyseisen säännön tunniste | |
reasonValue | string | syyn lokalisointiavain | |
valueType | string | DESCRIPTION, EXCEPTION |
AuthorizationList
AuthorizationList-rajapinnan kautta tarkistetaan, missä asioissa asiamiehellä on oikeus asioida päämiehen puolesta.
REST-kutsussa välitetään rekisteröintipyynnön vastauksena saatu sessionId ja asiointioikeustarkistuksen kohteen personId.
AuthorizationList-vastaus sisältää tiedon asioista, joissa asiamiehellä on oikeus asioida päämiehen puolesta. Asiointioikeus ilmaistaan roles-kentässä, jonka arvona palautetaan joko ALL (rajoittamaton asiointioikeus), huollonjako- tai tiedoksisaantioikeuskoodi tai lista asioista (issue URI), joita asiointioikeus koskee. Vastauksessa voi olla useampia asiointirooleja. Tyhjä lista tarkoittaa, että asiointioikeutta ei ole.
Taulukossa on kuvattu onnistuneen AuthorizationList-kyselyn vastaussanoma.
Elementin nimi | Elementin tyyppi | Kuvaus | Arvojoukko |
|---|---|---|---|
roles | array<String> | Listaus asiamiehen asiointioikeuksista päämiehen puolesta. Jos toimivalta on saatu edustamisvaltuuden kautta, valtuusasiaan voidaan liittää edustettavan yrityksen yritystunnus URIn fragment-osioon, mikäli näin on määritelty palvelukohtaisessa konfiguraatiossa. Jos vastauksella olevan valtuusasian URIssa esiintyy tarkenteita, niiden avaimet ja arvot esitetään URL-koodatussa muodossa. Jos toimivalta on saatu huollonjakotilanteessa ja asetus "032.001.4.2 Henkilöllä on oltava huollonjakokoodi" on kytketty käyttöön, käytetään huollonjako- tai tiedoksisaantioikeuskoodia roolina. Edunvalvojan tai edunvalvontavaltuutetun kelpoisuuteen perustuva asiointioikeusrooli palautetaan säännöllä 036.010.1.4. | n* ”issue URI”, ”ALL” Huollonjako- tai tiedoksisaantioikeuskoodit:
Edunvalvojan tai edunvalvontavaltuutetun asiointioikeusrooli:
|
reasons | array<DecisionReason> | Arvo ehdollinen. Elementtejä voi olla useampia, yksi jokaista hylkäämisperustetta kohden. Käytöstä sovitaan palvelusopimuksessa erikseen. | n* reason[rule, value]. Attribuutti rule sisältää kyseisen säännön tunnisteen ja attribuutti value syyn lokalisointiavaimen. |
Taulukossa on kuvattu DecisionReason-elementti, joka sisältää elementit reasonRule, reasonValue ja valueType.
Elementin nimi | Tyyppi | Kuvaus | Arvojoukko |
|---|---|---|---|
reasonRule | string | kyseisen säännön tunniste | |
reasonValue | string | syyn lokalisointiavain | |
valueType | string | DESCRIPTION, EXCEPTION |
Alla on kuvattu REST-kutsujen palveluosoitteet sekä esimerkkipyynnöt ja -vastaukset yrityksen puolesta asioinnissa.
OrganizationalRoles-rajapinnan kautta tarkistetaan, onko henkilöllä oikeus asioida yrityksen puolesta ja millaisessa roolissa hän on yritykseen nähden.
Access_token luetaan joko Authorization: Bearer -headerista tai URL-parametrista.
OrganizationRoles (all selected)
GET URL: {rova_host}/service/ypa/api/organizationRoles/{sessionId}?requestId={requestId}&access_token={access_token}
Esimerkkipyyntö:
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
Esimerkkivastaus:
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",
"complete": true,
"roles": [
"NIMKO",
"TJ",
"http://valtuusrekisteri.suomi.fi/palkkatietojen_katselu?principalId=6004971-1&subOrganization=1234",
"http://valtuusrekisteri.suomi.fi/palkkatietojen_katselu?principalId=6004971-1&subOrganization=a%26b"
]
}, {
"name": "Asunto Oy Testikatu 1",
"identifier": "7769189-0",
"complete": true,
"roles": ["PJ"]
}
]
OrganizationRoles (one)
GET URL: {rova_host}/service/ypa/api/organizationRoles/{sessionId}/{organizationId}?requestId={requestId}&access_token={access_token}
Esimerkkipyyntö:
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
Esimerkkivastaus:
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",
"complete": true,
"roles": [
"NIMKO",
"TJ",
"http://valtuusrekisteri.suomi.fi/palkkatietojen_katselu?principalId=6004971-1&subOrganization=1234",
"http://valtuusrekisteri.suomi.fi/palkkatietojen_katselu?principalId=6004971-1&subOrganization=a%26b"
]
}
]
OrganizationRoles-vastaus sisältää listan (organizationList) asiamieheen liittyvistä yrityksistä ja hänen rooleistaan niissä. Jos osa rooleista jää selvittämättä esimerkiksi etäkutsun time out -tilanteen seurauksena, organization-elementin complete-kentän arvoksi tulee false.
Elementin nimi | Kuvaus | Arvojoukko |
|---|---|---|
organizationList | lista yrityksistä | Lista n*[organization] tai tyhjä. Saattaa sisältää useamman elementin vain, mikäli kohteiden monivalinta on käytössä asiointipalvelussa. |
Pääelementti: organization
Elementin nimi | Kuvaus | Arvojoukko |
|---|---|---|
identifier | yrityksen tunniste | yritystunnus (VAT tai kansallinen yritystunnus) |
name | yrityksen nimi | nimi |
roles | listaus rooleista (käytetään vain pyynnöissä, joissa on organisaatiotunnisterajaus, tai jos käyttäjään liittyy vain yksi yritys) | lista n*[role [”NIMKO”, ”TJ”, String]] |
complete | Jos osa rooleista jää selvittämättä, complete-kentän arvoksi tulee false. | true (oletus), false |
Nykyisestä Web API -sessiosta voidaan luoda siirtotunniste (transfer_token), joka välitetään seuraavalle asiointipalvelulle.
Taulukossa on kuvattu Web API -session siirrossa käytettävien REST-kutsujen palveluosoitteet sekä esimerkkipyynnöt ja -vastaukset.
Henkilön puolesta asiointi (HPA)
GET URL: {rova_host}/service/hpa/user/transfer/token/{sessionId}
Esimerkkipyyntö:
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
Esimerkkivastaus:
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
Yrityksen puolesta asiointi (YPA)
GET URL: {rova_host}/service/ypa/user/transfer/token/{sessionId}
Esimerkkipyyntö:
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
Esimerkkivastaus:
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
Web API -session ja käyttäjän tekemät valinnat vapautetaan unregister-toiminnolla.
Alla on kuvattu Web API -session lopetuksessa käytettävien REST-kutsujen palveluosoitteet sekä esimerkkipyynnöt ja -vastaukset.
Henkilön puolesta asiointi (HPA)
GET URL: {rova_host}/service/hpa/user/unregister/{sessionId}
Esimerkkipyyntö:
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
Esimerkkivastaus:
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
Yrityksen puolesta asiointi (YPA)
GET URL: {rova_host}/service/ypa/user/unregister/{sessionId}
Esimerkkipyyntö:
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
Esimerkkivastaus:
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
Seuraavista Web API -rajapinnoista löytyvät myös JSON Web Token (JWT) -versiot:
- Authorization
- AuthorizationList
- organizationRoles (all selected).
Ne palauttavat vastauksen RFC 7519 -standardissa määriteltyinä JSON Web Tokeneina.
OrganizationalRoles-rajapinnasta on saatavilla JWT:n palauttava versio. Sitä käytetään roolien myöhempää hakemista varten oletusvastauksen sijasta. Tämä mahdollistaa useamman valtuuden aiheen palauttamisen vastaussanomassa.
Tokenit tarjoavat lisäturvaa tiedonsiirtoon. Ne sisältävät asiointivaltuuksien vastauksissa allekirjoitettuina taulukon 19 yleiset tiedot ja taulukon 20 asiointivaltuuskohtaiset tiedot.
JWT-vastausten 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' |
JWT-vastausten asiointivaltuuskohtaiset tiedot:
Avain | Arvo/kuvaus |
|---|---|
principal | päämiehen henkilötunnus |
hetu | loppukäyttäjän henkilötunnus |
response | rajapintakohtainen vastaus |
issue | Authorization-pyynnölle annettu aiherajaus |
Rajapintojen JWT-versioita käytettäessä tarvitaan perusrajapintojen edellyttämien asetusten lisäksi taulukon 21 mukaiset asetukset.
JWT-rajapinnat ovat muiden rajapintojen tapaan käytettävissä Valtuudet-palvelun esimerkkiasiakaskirjastolla roles-auths-client. Tällöin JWT-asiakas on alustettava vakioarvojen lisäksi käytettävän palvelun UUID:llä ja julkisella avaimella.
Asetus | Kuvaus |
|---|---|
serviceUUID | käytettävän palvelun UUID |
publicKey | allekirjoituksen tarkistamiseen käytettävä palvelun julkinen avain |
Seuraavassa on esitetty JWT-allekirjoitusten tarkistamiseen käytettävät julkiset avaimet Valtuudet-palvelun tuotanto-, QA- ja testiympäristössä.
Tuotantoympäristö
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAh5dSdhllRgZDvjdSayG+RUcUztSKtiPgFEmRHEW6LPesuafmKMaRQsoLgVKpJySqrkiz4dLXlm5lNJjS3GvsNLJpEVAtLjg/62+knfGxSTAuEOGw1cXgl9JXKUCF+6ROOQm4RzrgjyzJGY4shQdNnU7c7sUPEU1rWPaCwUsvxWxXq++mhrDIWaHArgqNz1vmu4exURgbmuVR4rLbrmuqlGBVKRXI9SY2SHMDlFhkpLwOP60rHw5x3atkwPvCslLGuc7c56gNhV7LxFTRzwSSCXiWC3+/nMeoJPPxlB4H6sXc3A2zfkg/AIxhjojEI1UDyCWRTYR2aAiNmfZiVVlUrGKNl8wEuW3HXTGz0/yxt9++MdLCl7a2/4QkPs3y4vgXBUC91HpFb7vO1nuJRwrcyPKtkfhvZZa8sQn/FqsJXUzcTm079xmt4vLhm5liSUik3uYDueteP3rKyUtrnXeX8VX0NoS2ROXQm7eAZskifH4cCTJU29k5/G1sgaISK/mWFEExdsI8Ua7toYOUmCh3zMc/SC0Pf+9XCPFQOpADpumb6ihoiulndDT9pyN0uXYzbblL6QC+jSZMVOEgFyhJ336BjAcd8Do86nuSTA6gtH6JsfzeKr0E+XO6QB4ayr+62guFpHxHdCV1h5B8V7x4ow2bvsHEpVRRErkNrFpkVckCAwEAAQ==Testiympäristö
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA6/U3FlrDvNZ0ygPK1WGBjDsn0fXFgsEgNgVlY5wlp9fskVZM8efZNqxbhBYHuKUp0sAZrV7Zjj8DDk9j6XXtRRma2CKVjur1G9bm2snKfmwIjfQmdJ8iPCLLhzhsuECsNKFm0kTsc8UUWG8/zv/nWciAfF+tDXTu4K6wxW8cQjOX2u54ZqfbCL5itL/5nZk6b+Qx6eQOD0liZkEQTVZhELm4hXPhsTgIApKsN/+tnFbT7gNBsJuD+JDZBYFapFLlEz5UEjwCF+Z7WlzWy3tHxkHt+MMyJRD/gMb2zjv1W8/hs3qWrJXszW6UX6KbtQenVvfJrAeBSI2UlsE0Yx2rJwIDAQABTaulukossa on kuvattu JWT-vastausta tukevien REST-kutsujen palveluosoitteet sekä esimerkkipyynnöt ja -vastaukset.
Access_token luetaan joko Authorization: Bearer -headerista tai URL-parametrista.
Authorization
GET URL: /api/authorization/jwt/{sessionId}/{principalId}?requestId={requestId}&issues={issues}&access_token={access_token}
Esimerkkipyyntö:
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 URI, johon haetaan valtuutusta. Parametri ei ole pakollinen. Niitä voi olla useita. Parametrissa määritelty URI voi sisältää query-parametreina määriteltyjä tarkenteita. Jos tarkenteita käytetään URIssa, niiden avaimet ja arvot tulee esittää URL-koodatussa muodossa.
Esimerkkivastaus:
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.eyJwcmluY2lwYWwiOiIxMjA1MDhBOTUwRiIsImF1ZCI6ImQ0M2NmZWI0LTZiMDctNGIzNi05OGVlLWNjMWE4ZjI5YjhhNCIsInN1YiI6IkF1dGhvcml6YXRpb24iLCJyZXNwb25zZSI6IkFMTE9XRUQiLCJpc3MiOiJTdW9taS5maS1WYWx0dXVkZXQiLCJpYXQiOjE1MTY3NzgwNjksImp0aSI6ImM2YTllODBmLTI0YTgtNGQ5OS05MTBhLWI3YTdiNzk1M2FlMiIsImhldHUiOiIxMjA5NzgtOTAzOCJ9.uq1vMkVFrBpqQi8JyJHJCvqguyKpgn9o4XGBUe8nMubqMsvt5pGItBbrGFHoqjZf1jNqvPlnGvsowcyHK69VvRm9JMSVx6ldQ0aCxp2J8HvpqRIURV0XeOWU-CCP22phoeAb3dfbWen0YYAHl61_j1AlHgvrlWl3mE_E9WbMBkqysYstfGgDhsim2cvFblje8uotTb1uetyF--8FA7z9oZahgS0SokuZWB-wqAFj_5YPMLvBBdQ_yatUi5XZQpCHtJOU6H2tSZIFgOGI1Oct7qnchwAY26A6330NJger9TRqIJhHeP50IC8ir6GQPeppuN3LM7C03SyMaxIP2bRFQg
AuthorizationList
GET URL: /api/authorizationlist/jwt/{sessionId}/{principalId}?requestId={requestId}&access_token={access_token}
Esimerkkipyyntö:
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
Esimerkkivastaus:
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.eyJwcmluY2lwYWwiOiIzMTA4MTNBOTUxRiIsImF1ZCI6ImQ0M2NmZWI0LTZiMDctNGIzNi05OGVlLWNjMWE4ZjI5YjhhNCIsInN1YiI6IkF1dGhvcml6YXRpb25MaXN0IiwicmVzcG9uc2UiOiJbXCJBTExcIl0iLCJpc3MiOiJTdW9taS5maS1WYWx0dXVkZXQiLCJpYXQiOjE1MTY3NzgyMDYsImp0aSI6IjYwYjFjZjJiLTdiMjctNGUxYS05MjNkLWUzM2FlNzhkNzBjYyIsImhldHUiOiIxMjA5NzgtOTAzOCJ9.V9JROf9ZsCDtXVr4Mrs1Z2c9P2h4WcQ8kKvVRgWNhBpThcute8pZbHZNf4jeVt57-MEsuTVf9Hz-eYBGbdMeH8qwzF_vo4flp687b6Y7S_PwA-2M01i4rwqWKrVl9Ed37q-PdLuYY7KobDtvQuFa7NPRuQiAFqhsQXPBY7D6szKQSWP8wlga8CijwSQCVdoUFnr0wVM8mHNq2n60VHFGua1qmlohrsLz0ZDNVSe6xSyO1TEXWYkHAQJB5aWM68Z7Qk722uOaJiDRUCI14M79vrg4zb1lGz47ZhXjQPDtvrOkdmmDutz4TfeyOy-OpGcsQDU1927Ew1YExQ1UiKM4dw
organizationRoles (all selected)
GET URL: /api/organizationRoles/jwt/{sessionId}?requestId={requestId}&access_token={access_token}
Esimerkkipyyntö:
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=
Esimerkkivastaus:
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.eyJhdWQiOiJkNDNjZmViNC02YjA3LTRiMzYtOThlZS1jYzFhOGYyOWI4YTQiLCJzdWIiOiJPcmdhbml6YXRpb25hbFJvbGVzIiwicmVzcG9uc2UiOiJbe1wibmFtZVwiOlwiTHVtaSBHbG9iYWwgT3lcIixcImlkZW50aWZpZXJcIjpcIjEyMzQ1NjctMVwiLFwiY29tcGxldGVcIjp0cnVlLFwicm9sZXNcIjpbXCJOSU1LT1wiLFwiVEpcIl19XSIsImlzcyI6IlN1b21pLmZpLVZhbHR1dWRldCIsImlhdCI6MTUxNjc3ODQ4NCwianRpIjoiNTU4YzE1MTgtMWJlMy00OGJhLWE5NDYtNTAxZTAzMDcxNDAyIiwiaGV0dSI6IjAxMDE4MC05MDI2In0.i7X37jLjbnSujrtQ3sZyu5XUcJOz7DFpXii9M5FHfeWj9cWUPcrOJwUKnO0tyXqkBltfKsghoMpKH1iu4K0tvA8gm_HSG4cn9r_3Y7zfWsu2ulYwJ57IvKadqB1HMhCoWhpE2wt0DHmMTu88sVlvWRcfl3bt2K92xwquz3IJnQTiTpTNOtkOcevag7UWS173fY0fex1YFbIkan3tXOn_mbKw4KghM8m614n_PIUfpaJlDT__lSdqOCYeV5mq05Ekbi0esZzlkJ-mdfqnQKUX2sZtXqnwExCtcBoN1ee2cKktZmVdmRkxO3D5IC5uE4acwFW-59K7CyqfrE3lAHgQ
organizationRoles (token-pyyntö vastauksen lataamista varten)
GET URL: /api/organizationRoles/session/jwt/{sessionId}?requestId={requestId}&access_token={access_token}
Esimerkkipyyntö:
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=
Esimerkkivastaus:
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.eyJhdWQiOiJkNDNjZmViNC02YjA3LTRiMzYtOThlZS1jYzFhOGYyOWI4YTQiLCJzdWIiOiJPcmdhbml6YXRpb25hbFJvbGVzIiwiaXNzIjoiU3VvbWkuZmktVmFsdHV1ZGV0Iiwic2Vzc2lvbklkIjoiXCJhMDkzYmQxYi0wMmEzLTRiNmQtYjdhOC0zZWIxZDM5OWQ0NjhcIiIsImlhdCI6MTUxNjc3ODYyNiwianRpIjoiYTM4NmNmOTQtZWNkMS00NjMyLWI0NTYtYmZhYmI5ZGEzZmIyIiwiaGV0dSI6IjAxMDE4MC05MDI2In0.Nr3tVNxdoOa2Xnkv_W8LycR1Phz--wYeVoIalqxD4wpsMAjzvrPzHejT4IG8Hp02jomDwg1Q_LR-osJtwS2itgzoS3cT4mIXshkBH556t2INDHeSSGltkN5Biv-4pUyspOZsRDYXB9MnvldWFzGW2XEpuUZ2MjUQbQM4FETyfIJp5v1WIC97pK-V_OIISbC2lc0Kd3156x4t2NfOMbUWX3Wa9EgUjmRPe0B0Y8JLK57MR2UnQRWk1ckFkmeIUyUOPQwRvFshDhpQOdjWAv58qCSoM-LJx6r-GaI8zhuKW5djb0fS2YcaWzdZtzxIZs_2NI4jXAtvBV9CqjkN6D6ENg
organizationRoles (kaikki roolit tokenia käyttäen)
Esimerkkipyyntö:
GET http://localhost:8102/service/ypa/jwt/api/organizationRoles/
eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJkNDNjZmViNC02YjA3LTRiMzYtOThlZS1jYzFhOGYyOWI4YTQiLCJzdWIiOiJPcmdhbml6YXRpb25hbFJvbGVzIiwiaXNzIjoiU3VvbWkuZmktVmFsdHV1ZGV0Iiwic2Vzc2lvbklkIjoiXCJhMDkzYmQxYi0wMmEzLTRiNmQtYjdhOC0zZWIxZDM5OWQ0NjhcIiIsImlhdCI6MTUxNjc3ODYyNiwianRpIjoiYTM4NmNmOTQtZWNkMS00NjMyLWI0NTYtYmZhYmI5ZGEzZmIyIiwiaGV0dSI6IjAxMDE4MC05MDI2In0.Nr3tVNxdoOa2Xnkv_W8LycR1Phz--wYeVoIalqxD4wpsMAjzvrPzHejT4IG8Hp02jomDwg1Q_LR-osJtwS2itgzoS3cT4mIXshkBH556t2INDHeSSGltkN5Biv-4pUyspOZsRDYXB9MnvldWFzGW2XEpuUZ2MjUQbQM4FETyfIJp5v1WIC97pK-V_OIISbC2lc0Kd3156x4t2NfOMbUWX3Wa9EgUjmRPe0B0Y8JLK57MR2UnQRWk1ckFkmeIUyUOPQwRvFshDhpQOdjWAv58qCSoM-LJx6r-GaI8zhuKW5djb0fS2YcaWzdZtzxIZs_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=
Esimerkkivastausten sisällöt
Authorization
JWT-vastaus:
eyJhbGciOiJSUzI1NiJ9.eyJwcmluY2lwYWwiOiIxMjA1MDhBOTUwRiIsImF1ZCI6ImQ0M2NmZWI0LTZiMDctNGIzNi05OGVlLWNjMWE4ZjI5YjhhNCIsInN1YiI6IkF1dGhvcml6YXRpb24iLCJyZXNwb25zZSI6IkFMTE9XRUQiLCJpc3MiOiJTdW9taS5maS1WYWx0dXVkZXQiLCJpYXQiOjE1MTY3NzgwNjksImp0aSI6ImM2YTllODBmLTI0YTgtNGQ5OS05MTBhLWI3YTdiNzk1M2FlMiIsImhldHUiOiIxMjA5NzgtOTAzOCJ9.uq1vMkVFrBpqQi8JyJHJCvqguyKpgn9o4XGBUe8nMubqMsvt5pGItBbrGFHoqjZf1jNqvPlnGvsowcyHK69VvRm9JMSVx6ldQ0aCxp2J8HvpqRIURV0XeOWU-CCP22phoeAb3dfbWen0YYAHl61_j1AlHgvrlWl3mE_E9WbMBkqysYstfGgDhsim2cvFblje8uotTb1uetyF--8FA7z9oZahgS0SokuZWB-wqAFj_5YPMLvBBdQ_yatUi5XZQpCHtJOU6H2tSZIFgOGI1Oct7qnchwAY26A6330NJger9TRqIJhHeP50IC8ir6GQPeppuN3LM7C03SyMaxIP2bRFQgVastauksen sisältö avattuna:
{
"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
JWT-vastaus:
eyJhbGciOiJSUzI1NiJ9.eyJwcmluY2lwYWwiOiIzMTA4MTNBOTUxRiIsImF1ZCI6ImQ0M2NmZWI0LTZiMDctNGIzNi05OGVlLWNjMWE4ZjI5YjhhNCIsInN1YiI6IkF1dGhvcml6YXRpb25MaXN0IiwicmVzcG9uc2UiOiJbXCJBTExcIl0iLCJpc3MiOiJTdW9taS5maS1WYWx0dXVkZXQiLCJpYXQiOjE1MTY3NzgyMDYsImp0aSI6IjYwYjFjZjJiLTdiMjctNGUxYS05MjNkLWUzM2FlNzhkNzBjYyIsImhldHUiOiIxMjA5NzgtOTAzOCJ9.V9JROf9ZsCDtXVr4Mrs1Z2c9P2h4WcQ8kKvVRgWNhBpThcute8pZbHZNf4jeVt57-MEsuTVf9Hz-eYBGbdMeH8qwzF_vo4flp687b6Y7S_PwA-2M01i4rwqWKrVl9Ed37q-PdLuYY7KobDtvQuFa7NPRuQiAFqhsQXPBY7D6szKQSWP8wlga8CijwSQCVdoUFnr0wVM8mHNq2n60VHFGua1qmlohrsLz0ZDNVSe6xSyO1TEXWYkHAQJB5aWM68Z7Qk722uOaJiDRUCI14M79vrg4zb1lGz47ZhXjQPDtvrOkdmmDutz4TfeyOy-OpGcsQDU1927Ew1YExQ1UiKM4dwVastauksen sisältö avattuna:
{
"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 (all selected)
JWT-vastaus:
eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJkNDNjZmViNC02YjA3LTRiMzYtOThlZS1jYzFhOGYyOWI4YTQiLCJzdWIiOiJPcmdhbml6YXRpb25hbFJvbGVzIiwicmVzcG9uc2UiOiJbe1wibmFtZVwiOlwiTHVtaSBHbG9iYWwgT3lcIixcImlkZW50aWZpZXJcIjpcIjEyMzQ1NjctMVwiLFwiY29tcGxldGVcIjp0cnVlLFwicm9sZXNcIjpbXCJOSU1LT1wiLFwiVEpcIl19XSIsImlzcyI6IlN1b21pLmZpLVZhbHR1dWRldCIsImlhdCI6MTUxNjc3ODQ4NCwianRpIjoiNTU4YzE1MTgtMWJlMy00OGJhLWE5NDYtNTAxZTAzMDcxNDAyIiwiaGV0dSI6IjAxMDE4MC05MDI2In0.i7X37jLjbnSujrtQ3sZyu5XUcJOz7DFpXii9M5FHfeWj9cWUPcrOJwUKnO0tyXqkBltfKsghoMpKH1iu4K0tvA8gm_HSG4cn9r_3Y7zfWsu2ulYwJ57IvKadqB1HMhCo-nWhpE2wt0DHmMTu88sVlvWRcfl3bt2K92xwquz3IJnQTiTpTNOtkOcevag7UWS173fY0fex1YFbIkan3tXOn_mbKw4KghM8m614n_PIUfpaJlDT__lSdqOCYeV5mq05Ekbi0esZzlkJ-mdfqnQKUX2sZtXqnwExCtcBoN1ee2cKktZmVdmRkxO3D5IC5uE4acwFW-59K7CyqfrE3lAHgQVastauksen sisältö avattuna:
{
"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)
JWT-vastaus:
eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJkNDNjZmViNC02YjA3LTRiMzYtOThlZS1jYzFhOGYyOWI4YTQiLCJzdWIiOiJPcmdhbml6YXRpb25hbFJvbGVzIiwiaXNzIjoiU3VvbWkuZmktVmFsdHV1ZGV0Iiwic2Vzc2lvbklkIjoiXCJhMDkzYmQxYi0wMmEzLTRiNmQtYjdhOC0zZWIxZDM5OWQ0NjhcIiIsImlhdCI6MTUxNjc3ODYyNiwianRpIjoiYTM4NmNmOTQtZWNkMS00NjMyLWI0NTYtYmZhYmI5ZGEzZmIyIiwiaGV0dSI6IjAxMDE4MC05MDI2In0.Nr3tVNxdoOa2Xnkv_W8LycR1Phz--wYeVoIalqxD4wpsMAjzvrPzHejT4IG8Hp02jomDwg1Q_LR-osJtwS2itgzoS3cT4mIXshkBH556t2INDHeSSGltkN5Biv-4pUyspOZsRDYXB9MnvldWFzGW2XEpuUZ2MjUQbQM4FETyfIJp5v1WIC97pK-V_OIISbC2lc0Kd3156x4t2NfOMbUWX3Wa9EgUjmRPe0B0Y8JLK57MR2UnQRWk1ckFkmeIUyUOPQwRvFshDhpQOdjWAv58qCSoM-LJx6r-GaI8zhuKW5djb0fS2YcaWzdZtzxIZs_2NI4jXAtvBV9CqjkN6D6ENgVastauksen sisältö avattuna:
{
"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"
REST-kutsussa välitetään clientId sekä asiamiehen ja päämiehen tunnisteet. Lisäksi pyynnön mukana voi antaa valtuusasian, joka määrittää, mitä asiointi koskee. Parametrissa määritellyn valtuusasian URI voi sisältää query-parametreina määriteltyjä tarkenteita. Jos tarkenteita käytetään URIssa, niiden avaimet ja arvot tulee esittää URL-koodatussa muodossa.
Authorization-vastaus sisältää tiedon siitä, onko asiamiehellä oikeus asioida päämiehen puolesta. Asiointioikeus ilmaistaan authorization-kentässä, jonka arvona palautetaan joko positiivinen päätös ALLOWED tai negatiivinen päätös DISALLOWED. Jos vastaus on DISALLOWED ja palvelulle on sallittu näyttää hylkäysperusteet, ne palautetaan listan reason-kentissä.
Tunnistautuneen loppukäyttäjän tunniste välitetään X-userId-HTTP-headerissa.
Taulukossa on kuvattu onnistuneen Authorization REST -kyselyn vastaussanoma.
Elementin nimi | Tyyppi | Kuvaus | Arvojoukko |
|---|---|---|---|
result | string | Tieto siitä, onko asiamiehellä oikeus asioida päämiehen puolesta kyseisessä asiassa. | ALLOWED tai DISALLOWED |
reasons | array<DecisionReason> | Arvo ehdollinen. Elementtejä voi olla useampia, yksi jokaista hylkäämisperustetta kohden. Käytöstä sovitaan palvelusopimuksessa erikseen. | n* reason[rule, value] |
Taulukossa on kuvattu DecisionReason-elementti, joka sisältää elementit reasonRule, reasonValue ja valueType.
Elementin nimi | Tyyppi | Kuvaus | Arvojoukko |
|---|---|---|---|
reasonRule | string | kyseisen säännön tunniste | |
reasonValue | string | syyn lokalisointiavain | |
valueType | string | DESCRIPTION, EXCEPTION |
Taulukossa on esitetty Authorization REST -rajapinnan kutsumiseen tarvittavat tiedot.
Parametri | Tyyppi | Arvo/kuvaus |
|---|---|---|
service | polkuparametri | käytettävän palvelun tunniste (Web API Client ID) |
delegateId | polkuparametri | asiamiehen/valtuutetun henkilötunnus |
principalId | polkuparametri | päämiehen/valtuuttajan henkilötunnus |
requestId | pyyntöparametri | pyynnön yksilöivä tunniste |
issue | pyyntöparametri | aiherajaus (valtuusasian URI); valinnainen, voi olla useampia |
Authorization REST
GET URL: {rova_host}/service/rest/hpa/authorization/{service}/{delegateId}/{principalId}?requestId={requestId}&issue={issue_uri}
Esimerkkipyyntö
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
Esimerkkivastaus:
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
Virheviestit
Jos pyynnössä on virhe, vastauksena palautetaan virhettä vastaava HTTP-status ja mahdollinen virheviesti sekä ReqId-tunniste, joka on Valtuudet-palvelun sisäinen tunniste pyynnölle. Seuraavassa on esitetty 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"}
Tarkenteilla rajataan valtuuksien toimivaltaa esimerkiksi aliorganisaatioon tai yksikköön. Oletusarvoisesti valtuusasioilla ei ole tarkennetta, mutta niille voidaan määritellä sellainen tarvittaessa.
Tarkenteiden tyypit ja nimet on määritelty valtuuskoodistossa. Jos valtuuskoodille on määritelty rajaustarkenteita, ne on lisätty vastaukseen valtuuskoodin tunnisteen perään avain-arvoparein.
Authorization
GET URL: {rova_host}/service/hpa/api/authorization/{sessionId}/{personId}?requestId={requestId}&issues={issues}&access_token={access_token}
Issues-parametrin arvona on URI, johon haetaan valtuutusta. Parametri ei ole pakollinen. Niitä voi olla useita. Parametrissa määritelty URI voi sisältää query-parametreina määriteltyjä tarkenteita. Jos tarkenteita käytetään URIssa, niiden avaimet ja arvot tulee esittää URL-koodatussa muodossa.
Esimerkkipyyntö:
GET /service/hpa/api/authorization/7407df88-8fbe-4e16-94fd-05467963b49e/120508A950F?requestId=testClientRequestId&issues=http%3A%2F%2Fvaltuusrekisteri.suomi.fi%2Fpalkkatietojen_ilmoittaminen%3FprincipalId%3D120508A950F%26subOrganization%3D1234567-1 HTTP/1.1
X-AsiointivaltuudetAuthorization: 42bbe569 2016-06-13T11:48:02.087Z vFxeTk/6oJlqHxhkE3YTyuTQh7X2SMrB/XhvAvemIuQ=
Host: localhost:18102
Accept: application/json;charset=UTF-8
Connection: keep-alive
Esimerkkivastaus:
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
[{"reasons":[],"result":"ALLOWED","principal":{"personId":"010316A998C","name":"Pekkala Esko-Olli"}}]
AuthorizationList
GET URL: {rova_host}/service/hpa/api/authorizationlist/{sessionId}/{personId}?requestId={requestId}&access_token={access_token}
Esimerkkipyyntö:
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
Esimerkkivastaus:
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"],"principal":{"personId":"010316A998C","name":"Pekkala Esko-Olli"}}]
Valtuudet-palvelu käyttää OAuth 2.0 -protokollaa valtuutusprosessin tietoturvalliseen käsittelyyn. OAuthin oikea käyttö asettaa vaatimuksia Valtuudet-palvelua käyttävälle asiointipalvelulle.
Yleistä tietoa OAuth 2.0 -protokollan tietoturvasta löytyy OAuthin määrittelydokumentistaAvautuu uuteen ikkunaan..
Asiointipalvelun täytyy olla suojattu CSRF-hyökkäyksiä vastaan
Kun loppukäyttäjä on kirjautuneena asiointipalveluun, hän on altis CSRF-hyökkäyksille. CSRF-hyökkäyksessä asiointipalvelun toimintoja linkitetään loppukäyttäjän huomaamatta toisesta palvelusta käsin. Asiointipalvelun täytyy sisältää CSRF-suojaus, jotta sen toimintoja ei pystytä kutsumaan asiointipalvelun ulkopuolelta.
Tutustu tarkemmin CSRF-hyökkäyksiin.Avautuu uuteen ikkunaan.
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 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 OAuth-vastauksen mukana state-parametrin, jonka 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.
Valtuutuksen paluuosoite pitää olla kirjattuna sallituksi uudelleenohjausosoitteeksi
Kun asiointipalvelu aloittaa OAuth-valtuutusprosessin, se välittää Valtuudet-palvelulle uudelleenohjausosoitteen, johon käyttäjän selain ohjataan valtuutuksen päätteeksi. Jotta paluupyynnön mukana välitettävä OAuth-avain ei päädy vääriin 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ä.
Tutustu tarkemmin OAuth 2.0 -protokollan uudelleenohjaukseen.Avautuu uuteen ikkunaan.
Asiointipalvelun täytyy päättää Valtuudet-palvelun istunto valtuuksien tarkistamisen jälkeen
Kun Web API -rajapintaa käyttävä asiointipalvelu on tehnyt tarvittavat valtuuskyselyt, sen on suljettava istunto unregister-toiminnolla. Muussa tapauksessa istunnon sulkeminen jää aikakatkaisun vastuulle.
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. Ne on tarkoitettu vain asiointipalvelun ja Valtuudet-palvelun väliseen käyttöön. Asiointipalvelu ei saa näyttää virheviestejä loppukäyttäjälle sellaisinaan.
Tuetut TLS-protokollat ja salausalgoritmit
Web API -rajapinnan REST-rajapinnan palveluosoitteessa tuetut TLS-protokollat ja -salausalgoritmit 4.3.2025 alkaen:
TLS-protokollat
- TLS 1.2
- TLS 1.3
TLS 1.3-protokollan salaukset
- TLS_AES_128_GCM_SHA256
- TLS_AES_256_GCM_SHA384
- TLS_CHACHA20_POLY1305_SHA256
TLS 1.2-protokollan salaukset
- ECDHE-ECDSA-AES128-GCM-SHA256
- ECDHE-RSA-AES128-GCM-SHA256
- ECDHE-ECDSA-AES256-GCM-SHA384
- ECDHE-RSA-AES256-GCM-SHA384
Palvelinvarmenteen asettaminen luotetuksi
Palvelinvarmenne saattaa muuttua ennalta ilmoittamattomina ajankohtina. Tästä syystä suosittelemme asettamaan AWS-juurivarmenteet luotetuiksi täsmällisen palvelinvarmenteen sijaan. AWS-juurivarmenteet ovat tyypillisesti järjestelmissä oletuksena luotettuja. Tarvittaessa juurivarmenteet ovat ladattavissa osoitteessa https://www.amazontrust.com/repository/Avautuu uuteen ikkunaan..