OIDC-rajapinta
Suomi.fi-tunnistus ottaa käyttöön OpenID Connect -rajapinnan - muutos vaatii toimenpiteitä asiointipalveluilta
Suomi.fi-tunnistus ottaa käyttöön OpenID Connect -protokollaa tukevan rajapinnan SAML 2.0-standardin sijaan. Muutoksessa korvataan nykyinen SAML-rajapinta uudella OIDC-rajapinnalla. Uuden rajapinnan käyttöönotto vaatii asiointipalveluilta toimenpiteitä. Nykyinen Suomi.fi-tunnistuksen SAML-rajapinta tulee poistumaan siirtymäajan jälkeen.
Uusi OpenID Connect -rajapinta vastaa paremmin asiakasorganisaatioiden tarpeisiin
OpenID Connect on autentikointiprotokolla, joka perustuu OAuth 2.0 -protokollaan. Rajapintamuutoksen myötä asiointipalvelun ja Tunnistus-palvelun välille muodostetaan luottamussuhde OIDC-protokollan mukaisen metadatan avulla.
Uudella OpenID Connect -rajapinnalla vastataan asiakasorganisaatioiden tarpeisiin, saadaan käyttöön modernimpi ja kehittäjäystävällisempi protokolla. Siirtymällä OIDC-rajapintaan parannetaan myös turvallisuutta, sillä avainten vaihto tehdään jatkossa useammin ja henkilötiedot siirtyvät palvelimien välillä.
Muutokset rajapinnassa
SAML 2.0 ja OpenID Connect ovat toiminnallisuuksiltaan samanlaisia, mutta ne eroavat toteutustavoiltaan. SAML-protokollassa käytetään XML-pohjaisia-sanomia ja OIDC-protokolla käyttää JSOnia ja JWT:tä.
OIDC-rajapintaan siirtyminen helpottaa asiointipalveluiden ylläpitokuormaa. OIDC-rajapinnan myötä tehtävä SAML-varmenteiden vaihtaminen poistuu. OIDC-rajapinnassa avainten vaihdon voi automatisoida eikä metadatapäivityksiä tarvita. Kahden vuoden välein tehtävä SAML-varmenteiden vaihtaminen poistuu ja OIDC-rajapinnassa avaimet haetaan urlissa, jonka asiointipalvelu määrittelee metadatassaan. Jatkossa varmenteiden vaihdon takia asiointipalvelun ei tarvitse ladata uutta metadataa.
Alla yhteenveto rajapinnoista.
Ominaisuus | SAML | OIDC |
|---|---|---|
Tekstimuoto / tiedonsiirtomuoto | XML | JSON |
Kertakirjautuminen ja kertauloskirjautuminen | Tuettu toiminnallisuus | Tuettu toiminnallisuus. Säilyy samankaltaisena. Kertakirjautumisistunto on yhteinen rajapintojen välillä. |
Henkilötiedot | Attribuutit | Scope ja claims. Samat tiedot, mutta eri muodossa. |
Metatietojen toimitus / Ympäristön rekisteröinti | Palvelunhallinnan kautta | Palvelunhallinnan kautta. Asiontipalvelun ei enää tarvitse toimittaa varmenteita metadatan yhteydessä, mikä vähentää tarvetta metadatapäivityksille. |
Käyttölupa | Pysyy samana. SAML-puolen lupa käy myös OIDC-puolella | |
Asiointipalvelun ympäristön varmenne | Hallinnoidaan metatatietojen kautta | Hallinnoidaan jwks_uri:en avulla, mikä tarkoittaa, että asiointipalvelu voi vaihtaa varmenteita ilman, että niitä tarvitsee erikseen toimittaa Suomi.fi-tunnistukselle. |
SAML-varmenteiden vaihtaminen | SAML-varmenteiden vaihtaminen kahden vuoden välein | Vaihtuu säännöllisesti |
Tunnistusvälineet | Pysyy samana | |
Käyttäjän näkökulma | Pysyy samana |
Lue lisää OIDC-speksistä täältä: https://openid.net/specs/openid-connect-core-1_0.htmlAvautuu uuteen ikkunaan.
Siirtyminen SAML 2.0-standarista OpenID Connect -protokollaan ei tuo näkyviä muutoksia kansalaisen tunnistautumispolkuun. Käyttöönotto on mahdollista tehdä ilman käyttäjille näkyviä katkoja rekisteröimällä uusi OIDC-ympäristö vanhan rinnalle. Tarkemmat ohjeet käyttöönotosta viestitään asiointipalveluille myöhemmin.
Kertakirjautuminen ja kertauloskirjautuminen säilyvät tuettuina toiminnallisuuksina OIDC-rajapinnassa.
Muutos vaatii asiointipalveluilta toimenpiteitä - toimi näin
Muutos vaatii Suomi.fi-tunnistusta käyttäviltä asiointipalveluilta uuden OIDC-rajapinnan käyttöönoton Suomi.fi-tunnistuksen tuotanto- ja testiympäristössä. Asiointipalvelujen on tehtävä rajapinnan tekninen käyttöönotto itse ja käyttöönoton työmäärä riippuu asiointipalvelun toteutuksesta. OIDC-rajapintaan siirtyminen aloitetaan asiakastestiympäristöstä, jonka jälkeen edetään tuotantoympäristöön. Tiedota mahdollista järjestelmätoimittajaasi tulevasta muutoksesta ja huomioi uuden rajapinnan käyttöönotto asiointipalvelun tuotekehityksen tiekartalla.
OIDC-rajapinnan käyttöönotto vaatii uusien metadatatietojen toimittamisen Palvelunhallinnan kautta. Ilmoitamme erikseen kun asiakastestiympäristön ja tuotantoympäristön voi ottaa käyttöön. Suomi.fi-tunnistus julkaisee ohjeet OIDC-rajapinnan käyttöönottoon suomi.fi-kehittäjille -sivustolla sekä antaa tukea rajapinnan käyttöönotossa. OIDC-rajapinnan käyttöönotto ei vaadi uutta Suomi.fi-tunnistuksen käyttölupaa.
OIDC-rajapinnan käyttöönoton aikataulu
OIDC-rajapinta julkaistaan loppuvuonna 2026 Suomi.fi-tunnistuksen asiakastestiympäristöön ja tuotantoympäristöön. Ilmoitamme tarkemmat julkaisuaikataulut erikseen. Asiakastestiympäristön ja tuotantoympäristön käyttöönottoa ei ole pakko tehdä samaan aikaan, kun Suomi.fi-tunnistus julkaisee OIDC-rajapinnat. Asiointipalvelut voivat tehdä siirtymisen omien aikataulujen puitteissa, rajapintamuutoksen siirtymäajan huomioiden. Asiointipalvelun vastuulla on testata muutos ennen tuotantoon siirtymistä.
Asiointipalveluiden tulee siirtyä käyttämään OIDC-rajapintaa 1.6.2028 mennessä. Nykyinen Suomi.fi-tunnistuksen SAML-rajapinta säilyy siirtymäajan tuettuna rajapintana ja asiointipalvelut voivat aikatauluttaa oman siirtymänsä OIDC-rajapintaan siirtymäajan puitteissa. Siirtymän aikataulutus ja suunnittelu kannattaa aloittaa organisaatiossasi heti, jotta asiointipalvelusi siirtymä saadaan toteutettua siirtymäajan puitteissa.
Nykyinen SAML-rajapinta poistuu käytöstä Suomi.fi-tunnistuksessa 1.6.2028 . Tämän jälkeen tunnistautuminen ei toimi SAML-rajapinnan kautta.