Palveluntarjoajan integraatio-opas
Tällä sivulla ohjeistetaan integraation toteutus, kun käyttäjä ohjataan palveluntarjoajan palvelusta Datahubin valtuutuspalveluun valtuutuspyynnön hyväksymisprosessiin (Käyttötapaus 2).
Vaihe 1: Paluuosoitteen rekisteröinti
Sallittu paluuosoite tulee rekisteröidä ennen valtuutuspalvelun testauksen aloitusta/tuotannon käyttöönottoa. Tarkemmat ohjeet rekisteröintiin sivulla Valtuutuspalvelun testaus.
Paluuosoitteen tulee täyttää seuraavat vaatimukset:
Vain domain ja polku (ei query-parametreja tai hash-merkkejä)
HTTPS vaaditaan tuotantoympäristössä / HTTP sallittu testiympäristössä
Esimerkkejä sallituista paluuosoitteista:
https://sahkopalvelu.fi/authorization/callback
https://api.sahkopalvelu.fi/dhvp/return
https://sahkopalvelu.fi/services/dhvp
Esimerkkejä ei sallituista paluuosoitteista:
https://sahkopalvelu.fi/callback?service=dhvp: Sisältää query-parametreja
https://sahkopalvelu.fi/callback#result: Sisältää hash-merkkejä
https://sahkopalvelu.fi/callback?: Sisältää hakuparametrin
http://sahkopalvelu.fi/callback: HTTP ei sallittu (tuotanto)
Vaihe 2: Käyttäjän ohjaaminen valtuutuspalveluun
URL:n muodostaminen:
https://{dhvp-ympäristö}/{lang}/{requestId}?returnUrl={returnUrl}&relay={relay} URL-parametrit:
Parametri | Tyyppi | Pakollinen | Kuvaus |
|---|---|---|---|
lang | String | Kyllä | Käyttöliittymän kieli. Täytyy olla yksi seuraavista: fi, sv, en |
requestId | UUID v4 | Kyllä | Taustalla luodun valtuutuspyynnön (DH-83X) ulkoinen tunniste (ExternalAuthorisatio nRequestID), jonka osapuoli haluaa käyttäjän hyväksyvän. |
Query-parametrit:
Parametri | Tyyppi | Pakollinen | Kuvaus |
|---|---|---|---|
returnUrl | URL string | Kyllä | Rekisteröity paluuosoite |
relay | Base64 string | Ei | Valinnainen relay state -data (enintään 62 merkkiä, base64-koodattu) |
Esimerkki:
https://dhvp.fingrid.fi/fi/550e8400-e29b-41d4-a716-446655440000?returnUrl=https%3A%2F%2Fsahkopalvelu.fi%2Fcallback&relay=c29tZV9zdGF0ZV9kYXRh Vaihe 3: Käyttäjän palauttaminen valtuutuspalvelusta annettuun paluuosoitteeseen
Kun käyttäjä suorittaa valtuutusprosessin loppuun (tai peruuttaa sen), Datahubin valtuutuspalvelu ohjaa hänet takaisin annettuun paluuosoitteeseen.
Paluuosoitteen parametrit
Datahubin valtuutuspalvelu lisää paluuosoitteeseen seuraavat query-parametrit:
Parametri | Tyyppi | Kuvaus |
|---|---|---|
requestId | UUID v4 | Sama requestId, jonka annettiin uudelleenohjauksessa |
relay | Base64 string | relay state-data (vain jos annettiin uudelleenohjauksessa) |
status | String | Sen mukaan mitä käyttäjä teki pyynnölle: accept, reject. Arvo on tyhjä virhetilanteissa tai käyttäjän peruuttaessa prosessin. |
lang | String | Sama käyttöliittymän kieli, joka annetiin uudelleenohjauksessa fi, sv, en |
Esimerkki ilman relay-parametria:
https://sahkopalvelu.fi/callback?requestId=550e8400-e29b-41d4-a716-446655440000&status=accept&lang=fi Esimerkki relay-parametrin kanssa:
https://sahkopalvelu.fi/callback?requestId=550e8400-e29b-41d4-a716-446655440000&relay=c29tZV9zdGF0ZV9kYXRh&status=accept&lang=fi