Kiinteistövaihdannan palvelun tunnistautumisrajapinta

Johdanto

Tämän dokumentin tarkoituksena on toimia ohjeistuksena organisaatioille tunnistautumisen toteuttamisesta KVP:n selainpohjaiseen käyttöön. Dokumentissa kuvataan liittymisprosessi, kirjautumisprosessi, tekniset vaatimukset tunnistautumisratkaisulle sekä paluusanoman attribuutit.

KVP tarjoaa tunnistautumisrajapinnan organisaatioille, jotta organisaation työntekijät voivat kirjautua järjestelmään hyödyntäen organisaation omaa kirjautumisratkaisua. Tunnusten hallinta säilyy tällöin yhdessä paikassa. Vastuunäkökulmasta Maanmittauslaitos tunnistaa teknisesti vain organisaation, joka muodostaa yhteyden MML:een ja organisaation vastuulle jää tunnistaa varsinainen käyttäjä. Tieto käyttäjän identiteetistä välitetään MML:lle käyttäjän nimen sekä yksilöivän, mutta sinänsä anonyymin tunnisteen muodossa. Organisaation vastuulla on ilmoittaa pyydettäessä viranomaisille tiettyä tunnistetta vastaavan käyttäjän nimi ja henkilötunnus. Tunnisteiden tulee säilyä pysyvästi yksilöivinä, eikä yksittäistä tunnistetta saa siksi antaa toiselle käyttäjälle sen jälkeen kun sen alkuperäinen omistaja lopettaa tunnisteen käytön. Rajapinnan käyttäminen edellyttää sopimussuhdetta MML:een.

Sanasto

 Termi Selite
SAML 2.0 Security Assertion Markup Language 2.0. Standardi käyttäjän tunnistamiseen sekä käyttöoikeuksien siirtämiseen palveluiden välillä.
IdP Identity Provider. Tunnistautumispalvelu, joka sisältää käyttäjän tiedot sekä käyttöoikeudet.
SP Service Provider. Palveluntarjoaja, joka hyödyntää IdP-palveluita, tässä tapauksessa KVP.
Integraattori Organisaatio, joka vastaa muiden organisaatioiden Idp palvelusta
Alisopimus Organisaatiosopimus, jolla on määritetty integraattori

Selainpohjaisen tunnistautumisen käyttöönotto

Aloittaakseen tunnistautumisrajapinnan käytön, tulee organisaation tehdä sopimus MML:n kanssa rajapinnan käytöstä ja toteuttaa SAML 2.0 -standardin mukainen IdP. Ratkaisussa ei ota kantaa siihen, mitä toteutusta organisaatiot käyttävät IdP-ratkaisussaan, ainoana teknisenä vaatimuksena on SAML 2.0 -standardin toteutus. Liikennöinti tapahtuu SSL-yhteyden sisällä, jossa tunnistetaan palvelin, mutta ei clientia.

Mikäli organisaatio ei halua toteuttaa omaa Idp:tä, voi tämä käyttää integraattorin palvelua. Integraattorin on mahdollista päättää viestissä lähetettävä y-tunnus. Y-tunnus määrää sen yrityksen, jossa sisäänkirjautunut käyttäjä toimii. Jotta integraattori voi käyttää tiettyä y-tunnusta, tulee y-tunnuksen omaavalle organisaatiolle tehdä alisopimus ko. integraattorin alle.

Sopimuksessa ilmoitetaan yhteyshenkilö, joka on vastuussa sopimuksen mahdollisesta jatkamisesta, tekninen yhteyshenkilö, sopimuskausi sekä halutaanko asemavaltuutetulle antaa valtuudet siirtää organisaation nimissä olevia panttikirjoja. Tyypillisesti valtuudet annetaan ainoastaan rahoituslaitosten henkilöstölle. Tekninen yhteys automaattisesti lakkaa toimimasta sopimuskauden umpeutuessa, mikäli sopimusta ei ole uusittu.

Avoimen lähdekoodin ratkaisuja on listattu esimerkiksi SAML XML.org -sivustolla. Myös kaupallisia tuotteita on saatavilla.

Esimerkki avoimen lähdekoodin Shibboleth IdP -sovelluksen konfiguroinnista alustavaan testikäyttöön liitteessä 1.

Testausympäristöön integroituminen

Esivaatimukset
  • Sopimus MML:n kanssa testausvaiheesta allekirjoitettu
  • SAML 2.0:n mukainen, sopimuksen vaatimukset täyttävä IdP -testiympäristö
Vaiheet
  • MML toimittaa organisaatiolle SP:n SAML 2.0:n mukaisen XML-muotoisen metadatan
  • Organisaatio toimittaa MML:lle IdP:n SAML 2.0:n mukaisen XML-muotoisen metadatan
  • Organisaatio konfiguroi SP:n IdP:hen
  • MML ilmoittaa organisaatiolle, milloin tämä voi alkaa testata integraatiota

Tuotantoympäristöön integroituminen

Esivaatimukset
  • Sopimus MML:n kanssa tuotantovaiheesta allekirjoitettu
  • SAML 2.0:n mukainen, sopimuksen vaatimukset täyttävä IdP -tuotantoympäristö
  • Integraation toteutus on verifioitu kehitys tai testiympäristössä
Vaiheet

Kts. "KVP-testausympäristöön integroituminen"

Kirjautumisprosessi

Tunnistautumistransaktio

  1. Käyttäjä pyrkii kirjautumaan palveluun organisaation sivuilla olevan linkin kautta (esim. www.kiinteistoasiat.fi/auth/saml/organisaatioabc/v1). Käytettävä IdP määräytyy tämän osoitteen perusteella.
  2. KVP rakentaa SAML tunnistautumispyyntösanoman.
  3. KVP lähettää uudelleenohjauksen IdP:hen käyttäjän selaimelle, sisällyttäen SAML pyyntösanoman URL:iin.
  4. IdP parsii tunnistaumispyyntösanoman ja tunnistaa käyttäjän valitsemallaan menetelmällä.
  5. IdP rakentaa SAML vastaussanoman, joka sisältää KVP:n tarvitsemat käyttäjän tiedot. Sanoma on salattu KVP:n julkisella avaimella ja allekirjoitettu IdP:n julkisella avaimella.
  6. IdP palauttaa sanoman käyttäjän selaimelle, josta se välitetään KVP:lle POST -metodilla (esim. piilolomakkeen avulla).
  7. KVP verifioi sanoman, ottaa sen sisältämät attribuutit talteen ja kirjaa käyttäjän sisään palveluun.

XML-esimerkit

Tunnistautuminen ja attribuutit

Tunnistautumisintegraatiota käytettäessä autentikoimispyyntö tulee ohjata osoitteeseen:
https://<ympäristön osoite>/auth/saml/<MML:n antama integraattorin tunniste>/v<tunnisterajapinnan versionumero>
Esimerkiksi https://www.kiinteistoasiat.fi/auth/saml/organisaatiotunnisteabc/v1

Tunnistautumisen yhteydessä tulee välittää kaikki pakolliset attribuutit, muuten tunnistautuminen hylätään.

Käyttäjän yksilöinti tapahtuu tunnistautumispalvelun välittämällä yksilöivällä käyttäjätunnisteella, joka tulee olla jäljitettävissä pyydettäessä. MML ei ota kantaa tämän muotoon tai sisältöön, mutta organisaation tulee voida viranomaisen pyynnöstä toimittaa tieto siitä, kuka henkilö kyseisellä tunnisteella on palvelussa tehnyt toimia.

Palvelussa näytettävät tiedot muille käyttäjille ovat käyttäjän nimi, sähköpostiosoite (jos lupa annettu erikseen palvelussa) sekä yrityksen Y-tunnus. Yrityksen nimi noudetaan YTJ:stä automaattisesti Y-tunnuksen perusteella.

Attribuutit

Versio 1

Attribuutti Kuvaus
Esimerkki
Pakollisuus
Muotovaatimukset
Oletusarvo
skv.userid Uniikki yksilöivä käyttäjätunnus
org_matti_437612555
Kyllä
   
skv.firstname Käyttäjän etunimi
Matti
Kyllä
   
skv.lastname Käyttäjän sukunimi
Meikäläinen
Kyllä
   
skv.businessid Yrityksen Y-tunnus
1234567-8
Kyllä
Validi YTJ:stä löytyvä Y-tunnus  
skv.language Käyttäjän kielikoodi
fi
Ei
fi, sv
fi
skv.email
Käyttäjän sähköpostiosoite
matti@organisaatio.com Ei
Validi sähköpostiosoite
Ei oletusarvoa, mutta käyttäjän tulee
syöttää osoite kirjautumisen yhteydessä.
skv.authorization Käyttäjän käyttöoikeusroolit, roolien mahdollistamat toimet
kuvattu tarkemmin osiossa Käyttöoikeusroolit
asemavaltuutus
Kyllä
Merkkijonolista, [asemavaltuutus]  

XML-esimerkki IdP:n vastaussanoman attribuuteista

Attribuutit IdP:n vastaussanomassa (versio 1)

Rajapinnan versiointi

Palvelun vaatimat attribuutit versioidaan, jolla pyritään välttämään tilannetta, jossa kaikkien IdP:iden tulisi samalla hetkellä ottaa päivitetty rajapinta käyttöönsä. Uusi ja vanha rajapinta pyritään pitämään toiminnassa rinnakkain sovitun siirtymäjakson ajan, jonka aikana IdP:n tulisi ottaa uusi rajapinta käyttöönsä. Käytettävä rajapinta määritellään osoitteessa, jonka kautta organisaation työntekijät KVP-järjestelmään tulevat (esim. www.kiinteistoasiat.fi/auth/saml/organisaatioabc/v1 tai www.kiinteistoasiat.fi/auth/saml/organisaatioabc/v2).

Tällä hetkellä rajapinnasta on olemassa vain versio 1 (v1).

Käyttöoikeusroolit

Alustavasti KVP:ssä organisaatiokäyttäjillä on vain yksi käyttöoikeusrooli. Jos perusteita muille käyttöoikeuksille löytyy, voidaan näiden toteuttamista tarpeen mukaan harkita.

Asemavaltuutus

Käyttäjä voi toimia asiakkaansa nimissä (asiakirjojen luonnostelu ja/tai allekirjoitus) KVP-järjestelmässä niiden valtakirjojen puitteissa, jotka asiakas on organisaatiolle (Y-tunnus rajoittimena) antanut. Lisäksi jos organisaation toimialaan kuuluu luotonanto, voi käyttäjä tehdä panttikirjojen siirtohakemuksia niille sähköisille panttikirjoille, jossa organisaatio on saajana. Tämä toiminto aktivoidaan silloin kun sopimus MML:n kanssa niin määrittelee.

Mahdolliset virhetilanteet

  1. Teknisen yhteyden virhetilanteessa näytetään virhesivu.
  2. Puutteellisista/virheellisistä tunnistautumistiedoista tulee ilmoitus sisäänkirjautumisen epäonnistumisesta.
  3. Mikäli yritykselle tai integraattorille ei ole järjestelmässä voimassa olevaa sopimusta tai käyttöoikeutta, niin tekninen autentikoituminen onnistuu mutta sovellus ilmoittaa että "Ei käyttöoikeutta järjestelmään". Huomioi että integraattorilla itsellään ei välttämättä ole käyttöoikeutta vaan käyttöoikeus voi olla ainoastaan integraattorin välittämien yrityksien käyttäjillä.

Ole tarvittaessa yhteydessä tukeen ongelmien tarkempaa selvitystä varten. Liitä tukipyyntöön mukaan KVP:lle välitettävät tunnistautumistiedot.

Lisätietoja ja linkkejä

SAML 2.0 -standardin spesifikaatio
https://www.oasis-open.org/standards#samlv2.0
Avoimen lähdekoodin SAML -ratkaisuja
http://saml.xml.org/wiki/saml-open-source-implementations

Muutoshistoria

KuvausPvm
1. Versio 1.3.2013
Integraattori- ja alisopimuskuvauksen lisäys4.6.2013
Virhetilannekuvauksen lisäys24.9.2013
Muutokset SAML-tunnistautumisrajapintaan: Lisätty tuki forceAuthn-parametrin asettamiseksi falseksi asiakkuuskohtaisesti. Oletuksena edelleen true kuten nykyisin, mutta voidaan asettaa falseksi pyynnöstä.10.2.2014
Parannettu kuvausta7.4.2014