Tekninen kuvaus (OIDC)
Tässä ohjeessa kerrotaan, miten Suomi.fi OIDC-rajapinta (OpenID Connect) otetaan käyttöön asiointipalvelussa:
- Tunnistautumisen vaiheet
- Tarvittava metadata
- Käytettävät henkilötietoattribuutit
- Avainten hallinta.
Tekninen toteutus perustuu julkiseen OIDC-core spesifikaatioonAvautuu uuteen ikkunaan., josta löytyy tarkemmat kuvaukset kaikista tässä ohjeessa olevista teknisistä yksityiskohdista. Rajapinta ei toteuta OIDC-core spesifikaation kaikkia valinnaisia (OPTIONAL) osuuksia.
Aloita tästä
Jos integroit Suomi.fi-tunnistusta ensimmäistä kertaa, suosittelemme lukemaan sivut seuraavassa järjestyksessä:
- Metadata OIDC-rajapinnassa: rekisteröi asiointipalvelun tekninen konfiguraatio ja loppukäyttäjälle näkyvät tiedot ennen kuin aloitat.
- Tunnistuspyyntö ja vastaus OIDC-rajapinnassa: käyttäjän ohjaaminen tunnistautumaan ja valtuutuskoodin vastaanottaminen.
- Token-pyyntö ja vastaus OIDC-rajapinnassa: valtuutuskoodin vaihtaminen henkilötietoihin.
- Uloskirjautumispyyntö ja vastaus OIDC-rajapinnassa: käyttäjän istunnon päättäminen asiointipalvelussa ja Suomi.fi-tunnistuksessa.
Muita tärkeitä sivuja
- Scopet ja claimit: tuetut scopet ja niihin liittyvät henkilötietoattribuutit (claimit) ja käyttölupatasot.
- Tunnistusvälineet: tuetut tunnistusvälineet ja niitä vastaavat varmuustasot (ACR, Level of Assurance).
- Suomi.fi-tunnistuksen avainten vaihto OIDC-rajapinnassa: ohje, miten Suomi.fi-tunnistus vaihtaa omat allekirjoitusavaimensa, ja mitä tämä edellyttää asiointipalvelulta.
- Asiointipalveluiden avainten vaihto OIDC-rajapinnassa: asiointipalvelun omien avainten vaihto ja julkisten avainten osoitteen sisältö ja saatavuusvaatimukset.
Jos jokin termi tai lyhenne on epäselvä, tarkista se ensin OIDC-sanasto-sivulta. Sivulta löytyy sanasto hankalasti käännettäville termeille (esimerkiksi client_assertion, authorization code).
Tunnistautuminen OIDC-rajapinnassa
OIDC-rajapinnan tunnistautuminen perustuu valtuuskoodivirtaan (Authorization Code Flow).
Asiointipalvelu muodostaa allekirjoitetun tunnistuspyynnön ja ohjaa käyttäjän selaimen Suomi.fi-tunnistukseen.
Käyttäjä tunnistautuu ja Suomi.fi-tunnistus ohjaa käyttäjän asiointipalveluun valtuutuskoodin kanssa.
Asiointipalvelu vaihtaa valtuutuskoodin henkilötietoihin ja kirjaa käyttäjän sisään asiointipalveluun.

Uloskirjautuminen voi tapahtua kahteen suuntaan:
- Asiointipalvelun aloittamana: Tässä asiointipalvelu ohjaa käyttäjän selaimen end-session-päätepisteeseen, ja onnistuneen uloskirjautumisen jälkeen käyttäjä ohjataan takaisin asiointipalveluun.
- Suomi.fi-tunnistuksen aloittamana: Jos käyttäjällä on samanaikaisesti aktiivinen istunto useammassa asiointipalvelussa (kertakirjautuminen, SSO), Suomi.fi-tunnistus ilmoittaa uloskirjautumisesta myös muille istunnon omaaville asiointipalveluille erillisellä kutsulla. Tällöin kutsutaan asiointipalvelun kertauloskirjautumisen uloskirjauspyynnön osoitetta (frontchannel_logout_uri), joka on määritelty asiointipalvelun metadatassa.
