Vetuma-palvelu
Suomalaisen julkishallinnon Vetuma-palvelu SAML-kutsurajapinnan käyttötapaukset Versio: 3.4 Vetuma Verkkotunnistus ja -maksaminen Vetuma-palvelu SAML-kutsurajapinnan määrittely Versio: 3.4 14.1.2015 14.1.2015 Sisällysluettelo 1. Johdanto ........................................................................................................................ 3 2. Käyttäjän tunnistaminen Vetumalla SAML-rajapinnan kautta .................................... 4 2.1 Käyttötapauksen kuvaus ........................................................................................ 4 2.1.1 2.1.2 2.1.3 2.1.4 2.1.5 2.1.6 2.1.7 2.2 3. Toiminta teknisestä näkökulmasta.......................................................................... 5 Kertakirjautuminen Vetuman avulla SAML-rajapinnan kautta ................................... 8 3.1 Käyttötapauksen kuvaus ........................................................................................ 8 3.1.1 3.1.2 3.1.3 3.1.4 3.1.5 3.1.6 3.1.7 3.2 4. Yhteenveto................................................................................................................................. 8 Toimijat ...................................................................................................................................... 8 Lähtötilanne ............................................................................................................................... 8 Lopputulos ................................................................................................................................. 8 Tyypillinen tapahtumien kulku .................................................................................................... 8 Valinnaiset tapahtumien kulut .................................................................................................... 9 Poikkeustilanteet........................................................................................................................ 9 Toiminta teknisestä näkökulmasta.......................................................................... 9 Uloskirjautuminen Vetuma-kertakirjautumisistunnosta ........................................... 11 4.1 Käyttötapauksen kuvaus ...................................................................................... 11 4.1.1 4.1.2 4.1.3 4.1.4 4.1.5 4.1.6 4.1.7 4.2 5. Yhteenveto................................................................................................................................. 4 Toimijat ...................................................................................................................................... 4 Lähtötilanne ............................................................................................................................... 4 Lopputulos ................................................................................................................................. 4 Tyypillinen tapahtumien kulku .................................................................................................... 4 Valinnaiset tapahtumien kulut .................................................................................................... 5 Poikkeustilanteet........................................................................................................................ 5 Yhteenveto............................................................................................................................... 11 Toimijat .................................................................................................................................... 11 Lähtötilanne ............................................................................................................................. 11 Lopputulos ............................................................................................................................... 11 Tyypillinen tapahtumien kulku .................................................................................................. 11 Valinnaiset tapahtumien kulut .................................................................................................. 12 Poikkeustilanteet...................................................................................................................... 12 Toiminta teknisestä näkökulmasta........................................................................ 12 Tunnistuslähteen hakeminen Vetuman SAML-rajapinnan kautta ............................ 14 5.1 Käyttötapauksen kuvaus ...................................................................................... 14 5.1.1 5.1.2 5.1.3 5.1.4 5.1.5 5.1.6 5.1.7 5.2 Yhteenveto............................................................................................................................... 14 Toimijat .................................................................................................................................... 15 Lähtötilanne ............................................................................................................................. 15 Lopputulos ............................................................................................................................... 15 Tyypillinen tapahtumien kulku .................................................................................................. 15 Valinnaiset tapahtumien kulut .................................................................................................. 15 Poikkeustilanteet...................................................................................................................... 16 Toiminta teknisestä näkökulmasta........................................................................ 16 Copyright Fujitsu Finland Oy 2 (17) Pag Vetuma-palvelu SAML-kutsurajapinnan määrittely Versio: 3.4 14.1.2015 14.1.2015 1. JOHDANTO Vetuma-palvelu on kansalaisten verkkotunnistus- ja maksamispalvelu joka on tarkoitettu julkishallinnon organisaatioiden asiointisovelluksien käyttöön. Fujitsu Finland Oy tuottaa palveluntuottajan ominaisuudessa Vetuma-palvelun valtion ja kuntien eri organisaatioiden käyttöön. Vetuma-palvelun sovellusohjelmille tarjoama toiminnallisuus on kuvattu erillisessä dokumentissa ”Suomalaisen julkishallinnon Vetuma-palvelu, sovelluksille tarjotun toiminnallisuuden kuvaus”. Vetuma-palvelukokonaisuus sisältää sovelluksille tarjotun toiminnallisuuden lisäksi mm. laskutukseen ja raportointiin liittyviä toimintoja. Edellä mainitussa toiminnallisuuden kuvausdokumentissa on kuitenkin kuvattu ainoastaan sovelluksille tarjottu toiminnallisuus. Sovellukset voivat käyttää Vetuma-palvelun niille tarjoamaa toiminnallisuutta Vetuman oman kutsurajapinnan kautta, joka on määritelty dokumentissa ”Suomalaisen julkishallinnon Vetumapalvelu Kutsurajapinnan määrittely”. Lisäksi sovellukset voivat käyttää Vetuma-palvelun tunnistustoimintoja sekä SAML-kertakirjautumista ja kertauloskirjautumista Vetuman SAMLkutsurajapinnan kautta. Sen käyttö on kuvattu dokumentissa: Vetuma-palvelun SAMLkutsurajapinnan määrittely. Tämä dokumentti kuvaa seuraavat Vetuma-palvelun SAML-kutsurajapinnan käyttötapaukset: Käyttäjän tunnistaminen Vetumalla SAML-rajapinnan kautta Kertakirjautuminen Vetumaan SAML-rajapinnan kautta liittyneiden verkkopalveluiden kesken Uloskirjautuminen Vetuma-kertakirjautumisistunnosta Tunnistuslähteen hakeminen Vetuman versiossa 3.4 toteutettavaan SAML-toiminnallisuuteen ei sisälly kertakirjautumista sellaisten verkkopalveluiden kanssa jotka käyttävät muita Identity Providereita (esimerkiksi tunnistus.fi tai Haka-luottamusverkon Identity Providerit) käyttäjien tunnistamiseen. Kertakirjautuminen sellaisten verkkopalveluiden kesken jotka käyttävät joko Vetuman tai tunnistus.fi:n SAML-rajapintaa tunnistamiseen tullaan tukemaan myöhemmässä Vetuman versiossa. Käyttötapausten tekniset kuvaukset perustuvat siihen, että Vetuma tukee SAML:in HTTP POST-sidosta (binding) kutsujen ja vastausten välittämisessä. SAML:in HTTP Redirectsidos (binding) on tuettu tunnistuskutsujen ja uloskirjauksen välittämisessä. Versiossa 3.3 on palveluun lisätty SAML tunnistuslähdekysely. Versiossa 3.4. on lisätty tuki HTTP Redirect-sidokselle ja päivitetty tuki pankkien nykyisille rajapinnoille. Version myötä siirrytään tukemaan julkishallinnon SAML-profiilia. Tunnistusvastauksissa käytetään jatkossa XML-allekirjoituksissa algoritmia RSAwithSHA256 ja määrityksen mukaista arvoa vahvan tunnistuksen menetelmille. Copyright Fujitsu Finland Oy 3 (17) Pag Vetuma-palvelu SAML-kutsurajapinnan määrittely Versio: 3.4 14.1.2015 14.1.2015 2. KÄYTTÄJÄN TUNNISTAMINEN VETUMALLA SAML-RAJAPINNAN KAUTTA 2.1 Käyttötapauksen kuvaus 2.1.1 Yhteenveto Tässä käyttötapauksessa Vetuma-asiakkaan (Ankkalinnan kaupunki) verkkopalvelu (Ankkalinnan päivähoidon verkkopalvelu) tunnistaa käyttäjänsä Vetuman tarjoamalla SAMLstandardin mukaisella tunnistuksella joka mahdollistaa myös kertakirjautumisen muiden Vetuman SAML-tunnistusta käyttävien verkkopalveluiden kesken. 2.1.2 Toimijat Käyttäjä (Ankkalinnan päivähoidon verkkopalvelua käyttävä henkilö). «System» Vetuma (SAML-roolissa Identity Provider) «System» Ankkalinnan päivähoidon verkkopalvelu (SAML-roolissa Service Provider). 2.1.3 Lähtötilanne Ankkalinnan kaupunki on Vetuma-asiakas. Ankkalinnan päivähoidon verkkopalvelu on liitetty Vetuman SAML-luottamusrenkaaseen ja se käyttää Vetuma-tunnistusta SAML-rajapinnan kautta. Käyttäjä on muuttamassa Ankkalinnaan. Hän aikoo käyttää Ankkalinnan päivähoidon verkkopalvelua hakeakseen lapselleen päivähoitopaikkaa. Hoitopaikan hakeminen vaatii kirjautumista kyseiseen verkkopalveluun, joka puolestaan vaatii tunnistuksen. 2.1.4 Lopputulos Käyttäjä on tunnistettu ja kirjautunut Ankkalinnan kaupungin päivähoidon verkkopalveluun, ja hänellä on kertakirjautumisistunto Vetumassa. 2.1.5 Tyypillinen tapahtumien kulku 1. Käyttäjä ottaa selaimellaan yhteyden Ankkalinnan päivähoidon verkkopalveluun ja pyytää päivähoitopaikan varaamista. Varaaminen on toiminto joka edellyttää kirjautumista ja sen myötä tunnistamista. 2. Verkkopalvelu toteaa tarpeen tunnistaa käyttäjä, ja lähettää tunnistuspyynnön Vetumalle. 3. Vetuma tarjoaa käyttäjän valittavaksi SAML-rajapinnan yhteydessä tuetut tunnistusmenetelmät (Tupas, kansalaisvarmennetunnistus ja mobiilivarmennetunnistus) ja tunnistaa käyttäjän hänen valitsemallaan tavalla. o Mikäli käyttäjä tunnistautuu kansalaisvarmenteeseen perustuvalla menetelmällä, haetaan aina VTJstä käyttäjän HETU. o Tämä vaatii, että kaikilla Vetuman SAML-asiakkailla on HETUn hakusopimus VRKn kanssa. o Vetuman SAML-asiakkailla on myös mahdollista käyttää laajennettua VTJ-kyselyä, mikäli VRK:n kanssa on näin sovittu. 4. Vetuma luo käyttäjälle kertakirjautumisistunnon ja tallettaa siihen tunnistuksesta saamansa tiedot, sekä rakentaa niistä tunnistusvastauksen, jonka lähettää Ankkalinnan päivähoidon verkkopalvelulle. Laajennetun VTJ-kyselyn tulos on käytettävissä ainoastaan tässä käyttötapauksessa kun käyttäjä tunnistautuu. Tieto Vetuma-tunnistuksen käyttämisestä Copyright Fujitsu Finland Oy 4 (17) Pag Vetuma-palvelu SAML-kutsurajapinnan määrittely Versio: 3.4 14.1.2015 14.1.2015 tunnistuslähteenä tallennetaan myös istunnon ajaksi käyttäjän selaimeen hyödyntäen osoitetta, joka kuuluu valittuun domainiin. 5. Ankkalinnan päivähoidon verkkopalvelu toteaa tunnistuksen onnistuneeksi, poimii vastauksesta käyttäjän henkilöllisyyden ja muut tarvitsemansa tiedot, ja luo käyttäjälle oman verkkopalveluistuntonsa. 2.1.6 Valinnaiset tapahtumien kulut Käyttäjä peruu tunnistuksen Tällöin Vetuma palauttaa vastauksen jossa tämä kerrotaan. Tunnistus epäonnistuu Tällöin Vetuma palauttaa vastauksen jossa tämä kerrotaan. 2.1.7 Poikkeustilanteet Verkkopalvelun lähettämä tunnistuskutsu on jossain suhteessa virheellinen. Tällöin Vetuma palauttaa vastauksen jossa tämä todetaan, mikäli Vetuma pystyy todentamaan kutsun lähettäneen verkkopalvelun. Kutsut asiointisovelluksilta Vetumalle ja vastaukset Vetumalta asiointisovelluksille välitetään käyttäjän työaseman kautta. Myös kutsut Vetumalta pankkien verkkopalveluihin sekä vastaukset niiltä Vetumalle välitetään käyttäjän työaseman kautta. Kutsujen ja vastausten välittäminen selaimen kautta saattaa epäonnistua, esimerkiksi jos käyttäjä sulkee selaimen, työasema ”kaatuu”, tai yhteys lähettävästä tai vastaanottavasta palvelimesta työasemaan katkeaa. Tällöin kutsu- tai vastausviestin aiottu saaja ei saa viestiä, mutta myöskään viestin lähettäjä ei saa tietoa välityksen epäonnistumisesta. 2.2 Toiminta teknisestä näkökulmasta Tässä käyttötapauksessa Vetuma-palvelu toimii identiteetintarjoajana (SAML-standardin käsitemaailmassa Identity Provider), ja Ankkalinnan päivähoidon verkkopalvelu toimii palveluntarjoajana (SAML-standardin käsitemaailmassa Service Provider). Teknisesti tunnistus toimii seuraavasti: 1. Käyttäjän pyytäessä Ankkalinnan päivähoidon verkkopalvelulta päivähoitopaikan varaamista, hänen selaimestaan lähtee verkkopalvelulle HTTP-kutsu jonka verkkopalvelu tulkitsee ja toteaa tarpeen tunnistaa käyttäjä. 2. Verkkopalvelu lähettää SAML-tunnistuspyynnön käyttäjän selaimen kautta Vetumalle. Tarkemmin sanoen verkkopalvelu: o Rakentaa SAML-standardin mukaisen tunnistuspyynnön (<AuthnRequest>) jossa pyytää Vetuman tekemään tunnistuksen. o Lähettää pyynnön Vetumalle käyttäen SAML-standardissa määriteltyä Redirectsidosta (HTTP Redirect binding) tai POST-sidosta (HTTP POST binding). 3. Vetuma vastaanottaa tunnistuspyynnön HTTP Redirect-kutsuna tai HTTP POST-kutsuna. Koska kutsussa ei ole Vetuman käyttäjälle tekemää tunnistusevästettä, Vetuma toteaa että käyttäjä pitää tunnistaa. Vetuma tulkitsee kutsussa annetut määräykset tunnistuksen suorittamiselle, sekä käy käyttäjän kanssa tunnistuskeskustelun käyttäjän selaimen välityksellä. Tunnistuksen eri vaiheita ei ole tarkemmin purettu auki kuvassa 1. o Mikäli käyttäjä valitsee Tupas-tunnistuksen, Vetuma ohjaa käyttäjän tunnistautumaan hänen valitsemansa pankin verkkopalveluun. o Mikäli käyttäjä tunnistautui kansalaisvarmenteeseen perustuvalla menetelmällä, Vetuma hakee käyttäjän HETUn VTJ-palvelusta. Copyright Fujitsu Finland Oy 5 (17) Pag Vetuma-palvelu SAML-kutsurajapinnan määrittely Versio: 3.4 14.1.2015 14.1.2015 4. Vetuma luo käyttäjälle Vetuma-kertakirjautumisistunnon ja tallettaa siihen käyttäjän tunnistuksesta saadut tiedot (henkilöllisyyden, muut käyttäjää kuvaavat tiedot, sekä tiedot tunnistustapahtumasta). Vetuma merkitsee myös Ankkalinnan päivähoidon verkkopalvelun kyseiseen istuntoon osallistuvaksi palveluksi. Lisäksi Vetuma luo tunnistusevästeen jonka avulla se voi myöhemmin todeta tunnistuksen tehdyksi (kun muut verkkopalvelut pyytävät saman käyttäjän tunnistamista). Tieto Vetuma-tunnistuksen käyttämisestä tunnistuslähteenä tallennetaan istunnon ajaksi käyttäjän selaimeen luomalla tunnistuslähde-evästeen, joka asetetaan selaimeen hyödyntäen valittuun domainiin kuuluvaa osoitetta. Evästeitä ei ole esitetty kuvassa 1. 5. Vetuma rakentaa ja lähettää SAML-tunnistusvastauksen käyttäjän selaimen kautta verkkopalvelulle. Tarkemmin sanoen Vetuma: o Rakentaa SAML-standardin mukaisen vastauksen (<Response>) ja laittaa siihen käyttäjän tunnistuksesta saamistaan tiedoista muodostamansa selosteet (<Assertion>-elementit). o Lähettää vastauksen Ankkalinnan päivähoidon verkkopalvelulle käyttäen SAMLstandardissa määriteltyä POST-sidosta (HTTP POST binding). Vetuman tunistuseväste päätyy selaimelle tunnistusvastauksen kulkiessa selaimen kautta 6. Ankkalinnan päivähoidon verkkopalvelu toteaa saamastaan SAML-tunnistusvastauksesta tunnistuksen onnistuneeksi, poimii vastauksesta käyttäjän henkilöllisyyden, ja luo käyttäjälle oman verkkopalveluistuntonsa. Tapaa jolla verkkopalvelu ilmaisee istunnon olemassaolon (esimerkiksi eväste) ei ole esitetty kuvassa 1. 7. Ankkalinnan päivähoidon verkkopalvelu palauttaa käyttäjän selaimelle HTTP-vastauksena sivun, jolta käyttäjä voi jatkaa verkkopalvelun käyttöä kirjautuneena. Copyright Fujitsu Finland Oy 6 (17) Pag Vetuma-palvelu SAML-kutsurajapinnan määrittely Versio: 3.4 14.1.2015 Käyttäjän selain Ankkalinnan päivähoidon verkkopalvelu 14.1.2015 VETUMA 1. Kutsu jolla pyydetään päivähoitopaikan varaamista 2. SAML tunnistuskutsu 3. Tunnistuskeskustelu 4. Luo Kertakirjautumisistunto 5. SAML tunnistusvastaus 6. Luo 7. Vastaus kutsuun jolla pyydettiin päivähoitopaikan varaamista Verkkopalveluistunto Käyttö jatkuu tunnistettuna Kuva 1: Kirjautuminen Vetuman SAML-rajapinnan kautta Copyright Fujitsu Finland Oy 7 (17) Pag Vetuma-palvelu SAML-kutsurajapinnan määrittely Versio: 3.4 14.1.2015 14.1.2015 3. KERTAKIRJAUTUMINEN VETUMAN AVULLA SAML-RAJAPINNAN KAUTTA 3.1 Käyttötapauksen kuvaus 3.1.1 Yhteenveto Tässä käyttötapauksessa käyttäjä on tunnistettu Vetuman SAML-rajapinnan kautta tiettyyn verkkopalveluun (Ankkalinnan päivähoidon verkkopalvelu). Siellä asioituaan käyttäjä siirtyy toiseen Vetuman SAML-tunnistusta käyttävään verkkopalveluun (Hanhivaaran ulkoiluviraston verkkopalvelu) ja pyytää toimintoa joka vaatii tunnistusta. Jälkimmäinen verkkopalvelu pyytää Vetumalta tunnistusta, mutta koska Vetuma voi todeta käyttäjän jo tunnistetuksi, se saa tiedot käyttäjästä ja tunnistustapahtumasta käyttäjän Vetuma-kertakirjautumisistunnosta ja palauttaa ne jälkimmäiselle verkkopalvelulle. Käyttäjää ei siis vaivata tunnistautumaan uudelleen. 3.1.2 Toimijat Käyttäjä (Ankkalinnan ja Hanhivaaran verkkopalveluita käyttävä henkilö). «System» Vetuma (SAML-roolissa Identity Provider) «System» Ankkalinnan päivähoidon verkkopalvelu (SAML-roolissa Service Provider). «System» Hanhivaaran ulkoiluviraston verkkopalvelu (SAML-roolissa Service Provider). 3.1.3 Lähtötilanne Sekä Ankkalinnan kaupunki että Hanhivaaran kaupunki ovat Vetuma-asiakkaita. Sekä Ankkalinnan päivähoidon verkkopalvelu että Hanhivaaran ulkoiluviraston verkkopalvelu on liitetty Vetuman SAML-luottamusrenkaaseen ja ne käyttävät Vetuma-tunnistusta SAMLrajapinnan kautta. Käyttäjä on muuttamassa Ankkalinnaan. Hän on kirjautunut Ankkalinnan päivähoidon verkkopalveluun ja hakenut lapselleen päivähoitopaikkaa. Sen jälkeen hän aikoo käyttää naapurikaupungin Hanhivaaran ulkoiluviraston verkkopalvelua hakeakseen itselleen venepaikkaa. Venepaikan hakeminen vaatii kirjautumista palveluun, joka puolestaan vaatii tunnistuksen. 3.1.4 Lopputulos Käyttäjä on kirjautunut tunnistettuna Hanhivaaran ulkoiluviraston verkkopalveluun, ja tieto tästä on käyttäjän Vetuma-kertakirjautumisistunnossa 3.1.5 Tyypillinen tapahtumien kulku 1. Käyttäjä siirtyy selaimellaan Hanhivaaran ulkoiluviraston verkkopalveluun ja pyytää venepaikan varaamista (toiminto joka edellyttää kirjautumista). 2. Verkkopalvelu toteaa tarpeen tunnistaa käyttäjä, ja lähettää tunnistuspyynnön Vetumalle. 3. Vetuma toteaa, että käyttäjä on jo tunnistettu, ja hänen henkilöllisyytensä, muut tunnistuksesta saadut tietonsa ja tiedot tunnistustapahtumasta ovat jo käytettävissä. 4. Vetuma rakentaa aiemmin tehdystä tunnistuksesta saamistaan tiedoista SAMLtunnistusvastauksen, jonka lähettää Hanhivaaran ulkoiluviraston verkkopalvelulle. 5. Hanhivaaran ulkoiluviraston verkkopalvelu toteaa tunnistuksen onnistuneeksi, poimii vastauksesta käyttäjän henkilöllisyyden ja muut tarvitsemansa tiedot, ja luo käyttäjälle oman istuntonsa. Copyright Fujitsu Finland Oy 8 (17) Pag Vetuma-palvelu SAML-kutsurajapinnan määrittely Versio: 3.4 14.1.2015 14.1.2015 3.1.6 Valinnaiset tapahtumien kulut 3.1.7 Poikkeustilanteet Verkkopalvelun lähettämä tunnistuskutsu on jossain suhteessa virheellinen. Tällöin Vetuma palauttaa vastauksen jossa todetaan tämä. Kutsun tai vastauksen välittäminen selaimen kautta epäonnistuu (katso käyttötapaus ”Käyttäjän tunnistaminen Vetumalla SAML-rajapinnan kautta”). 3.2 Toiminta teknisestä näkökulmasta Tässä käyttötapauksessa Vetuma-palvelu toimii identiteetintarjoajana (SAML-standardin käsitemaailmassa Identity Provider), ja Hanhivaaran ulkoiluviraston verkkopalvelu toimii palveluntarjoajana (SAML-standardin käsitemaailmassa Service Provider). Teknisesti tunnistus toimii seuraavasti: 1. Käyttäjän pyytäessä Hanhivaaran ulkoiluviraston verkkopalvelulta venepaikan varaamista (toimintoa joka edellyttää kirjautumista), hänen selaimestaan lähtee verkkopalvelulle HTTP-kutsu jonka verkkopalvelu tulkitsee ja toteaa tarpeen tunnistaa käyttäjä. 2. Verkkopalvelu lähettää SAML-tunnistuspyynnön käyttäjän selaimen kautta Vetumalle. Tarkemmin sanoen verkkopalvelu: o Rakentaa SAML-standardin mukaisen tunnistuspyynnön (<AuthnRequest>) jossa pyytää Vetuman tekemään tunnistuksen. o Lähettää pyynnön Vetumalle käyttäen SAML-standardissa määriteltyä Redirectsidosta (HTTP Redirect binding) tai POST-sidosta (HTTP POST binding), mukaan lukien kutsun ja vastauksen korrelointiin käytettävän RelayState-tiedon välittämisen kyseiselle sidokselle määrätyllä tavalla). 3. Vetuma vastaanottaa tunnistuspyynnön HTTP Redirect tai HTTP POST-kutsuna. Koska selain on liittänyt kutsuun Vetuman käyttäjälle tekemän tunnistusevästeen, Vetuma toteaa käyttäjän jo tunnistetuksi ja ottaa käyttäjää ja tunnistustapahtumaa koskevat tiedot hänen Vetuma-kertakirjautumisistunnostaan. Vetuma lisää myös Hanhivaaran ulkoiluviraston verkkopalvelun käyttäjän Vetuma-kertakirjautumisistuntoon istuntoon osallistuvaksi palveluksi. 4. Vetuma rakentaa ja lähettää SAML-tunnistusvastauksen käyttäjän selaimen kautta Hanhivaaran ulkoiluviraston verkkopalvelulle. Tarkemmin sanoen Vetuma: o Rakentaa SAML-standardin mukaisen vastauksen (<Response>) ja laittaa siihen käyttäjän tunnistuksesta saamistaan tiedoista muodostamansa selosteet (<Assertion>-elementit). o Lähettää vastauksen Hanhivaaran ulkoiluviraston verkkopalvelulle käyttäen SAMLstandardissa määriteltyä POST-sidosta (HTTP POST binding), mukaan lukien kutsun ja vastauksen korrelointiin käytettävän RelayState-tiedon välittämisen kyseiselle sidokselle määrätyllä tavalla) 5. Hanhivaaran ulkoiluviraston verkkopalvelu toteaa saamastaan SAML-tunnistusvastauksesta tunnistuksen onnistuneeksi, poimii vastauksesta käyttäjän henkilöllisyyden, ja luo käyttäjälle oman verkkopalveluistuntonsa. Tapaa jolla verkkopalvelu ilmaisee istunnon olemassaolon (esimerkiksi eväste) ei ole esitetty kuvassa 2. 6. Hanhivaaran ulkoiluviraston verkkopalvelu palauttaa käyttäjän selaimelle HTTPvastauksena sivun, jolta käyttäjä voi jatkaa verkkopalvelun käyttöä kirjautuneena. Copyright Fujitsu Finland Oy 9 (17) Pag Vetuma-palvelu SAML-kutsurajapinnan määrittely Versio: 3.4 14.1.2015 Käyttäjän selain Ankkalinnan päivähoidon verkkopalvelu 14.1.2015 Hanhivaaran ulkoiluviraston verkkopalvelu VETUMA Käyttö jatkuu tunnistettuna Kertakirjautumisistunto 1. Kutsu jolla pyydetään venepaikan varaamista 2. SAML tunnistuskutsu 3. Ota tiedot, lisää uusi palvelu istuntoon 4. SAML tunnistusvastaus 5. Luo 6. Vastaus kutsuun jolla pyydettiin venepaikan varaamista Verkkopalveluistunto Käyttö jatkuu tunnistettuna Kuva 2: Kertakirjautuminen Vetuman SAML-rajapinnan kautta Copyright Fujitsu Finland Oy 10 (17) Pag Vetuma-palvelu SAML-kutsurajapinnan määrittely Versio: 3.4 14.1.2015 14.1.2015 4. ULOSKIRJAUTUMINEN VETUMA-KERTAKIRJAUTUMISISTUNNOSTA 4.1 Käyttötapauksen kuvaus 4.1.1 Yhteenveto Tässä käyttötapauksessa käyttäjä on tunnistettu Vetuman avulla useisiin Vetuma-asiakkaiden verkkopalveluihin (mukaan lukien Ankkalinnan päivähoidon verkkopalvelu ja Hanhivaaran ulkoiluviraston verkkopalvelu), ja hänellä on kertakirjautumisistunto Vetumassa. Ankkalinnan päivähoidon verkkopalvelu tarjoaa uloskirjautumisen tällaisesta Vetumakertakirjautumisistunnosta. Käyttäjän pyytäessä tätä toimintoa kyseinen verkkopalvelu lähettää Vetumalle kertauloskirjautumispyynnön. Vetuma välittää kertauloskirjautumispyynnön kaikille muille Vetuma-kertakirjautumisistuntoon osallistuville verkkopalveluille. Kukin näistä verkkopalveluista päättää oman istuntonsa. Vetuma päättää oman kertauloskirjautumisistuntonsa ja palauttaa tiedon onnistuneesta kertauloskirjautumisesta Ankkalinnan päivähoidon verkkopalvelulle. 4.1.2 Toimijat Käyttäjä (Ankkalinnan ja Hanhivaaran verkkopalveluita käyttävä henkilö). «System» Vetuma (SAML-roolissa Identity Provider) «System» Ankkalinnan päivähoidon verkkopalvelu (SAML-roolissa Service Provider). «System» Hanhivaaran ulkoiluviraston verkkopalvelu (SAML-roolissa Service Provider). 4.1.3 Lähtötilanne Sekä Ankkalinnan kaupunki että Hanhivaaran kaupunki ovat Vetuma-asiakkaita. Sekä Ankkalinnan päivähoidon verkkopalvelu että Hanhivaaran ulkoiluviraston verkkopalvelu on liitetty Vetuman SAML-luottamusrenkaaseen ja ne käyttävät Vetuma-tunnistusta SAMLrajapinnan kautta. Ankkalinnan päivähoidon verkkopalvelu tarjoaa käyttöliittymässään uloskirjautumisen kertakirjautumisistunnosta. Käyttäjä on tunnistettu Vetuman tarjoaman SAML-kertakirjautumisen avulla Ankkalinnan päivähoidon verkkopalveluun ja Hanhivaaran ulkoiluviraston verkkopalveluun sekä joihinkin muiden Vetuma-asiakkaiden SAML-tunnistusta käyttäviin verkkopalveluihin. 4.1.4 Lopputulos Käyttäjä on uloskirjautunut Ankkalinnan kaupungin päivähoidon verkkopalvelusta ja Hanhivaaran ulkoiluviraston verkkopalvelusta – sekä muista käyttäjän Vetumakertakirjautumisistunnossa mukana olevista verkkopalveluista. 4.1.5 Tyypillinen tapahtumien kulku 1. Käyttäjä pyytää selaimellaan Ankkalinnan päivähoidon verkkopalvelun tarjoamaa kertauloskirjautumista. 2. Ankkalinnan päivähoidon verkkopalvelu lähettää kertauloskirjautumispyynnön Vetumalle. 3. Vetuma toteaa, että käyttäjällä on voimassa oleva Vetuma-kertakirjautumisistunto, ja ottaa siitä tiedon mitkä kaikki verkkopalvelut (mukaan lukien Hanhivaaran ulkoiluviraston verkkopalvelu) osallistuvat kyseiseen kertakirjautumisistuntoon. 4. Vetuma lähettää uloskirjautumispyynnön kullekin kertakirjautumisistuntoon osallistuvista verkkopalveluista (mukaan lukien Hanhivaaran ulkoiluviraston verkkopalvelu). Copyright Fujitsu Finland Oy 11 (17) Pag Vetuma-palvelu SAML-kutsurajapinnan määrittely Versio: 3.4 14.1.2015 14.1.2015 5. Kukin näistä verkkopalveluista päättää oman verkkopalveluistuntonsa, ja kuittaa uloskirjautumisvastauksella Vetumalle päättämisen tehdyksi. 6. Saatuaan kaikki uloskirjautumisvastaukset Vetuma hävittää käyttäjän Vetumakertakirjautumisistunnon ja lähettää uloskirjautumisvastauksen Ankkalinnan päivähoidon verkkopalvelulle. 7. Ankkalinnan päivähoidon verkkopalvelu päättää oman verkkopalveluistuntonsa. 4.1.6 Valinnaiset tapahtumien kulut 4.1.7 Poikkeustilanteet Verkkopalvelun lähettämä uloskirjautumiskutsu on jossain suhteessa virheellinen. Tällöin Vetuma palauttaa vastauksen jossa todetaan tämä. Joku istuntoon mukaan otetuista verkkopalveluista ei vastaa Vetuman sille lähettämään uloskirjautumiskutsuun. (katso käyttötapaus ”Käyttäjän tunnistaminen Vetumalla SAML-rajapinnan kautta”) Kutsun tai vastauksen välittäminen selaimen kautta epäonnistuu (katso käyttötapaus ”Käyttäjän tunnistaminen Vetumalla SAML-rajapinnan kautta”) 4.2 Toiminta teknisestä näkökulmasta Tässä käyttötapauksessa Vetuma-palvelu toimii identiteetintarjoajana (SAML-standardin käsitemaailmassa Identity Provider), ja Hanhivaaran ulkoiluviraston verkkopalvelu toimii palveluntarjoajana (SAML-standardin käsitemaailmassa Service Provider). Tässä käyttötapauksessa palveluntarjoaja pyytää identiteetintarjoajaa tunnistamaan käyttäjän ohjaamalla hänet identiteetintarjoajan tunnistuspalveluun. Teknisesti tunnistus toimii seuraavasti: 1. Käyttäjä pyytää kertauloskirjautumista Ankkalinnan päivähoidon verkkopalvelussa, jolloin hänen selaimestaan lähtee verkkopalvelulle HTTP-kutsu jonka johdosta verkkopalvelussa todetaan halu tehdä kertauloskirjautuminen. 2. Verkkopalvelu lähettää SAML-uloskirjautumispyynnön käyttäjän selaimen kautta Vetumalle. Tarkemmin sanoen verkkopalvelu: o Rakentaa SAML-standardin mukaisen uloskirjautumispyynnön (<LogoutRequest>) jossa pyytää Vetuman tekemään kertauloskirjautumisen. o Lähettää pyynnön Vetumalle käyttäen SAML-standardissa määriteltyä Redirectsidosta (HTTP Redirect binding) tai POST-sidosta (HTTP POST binding). 3. Vetuma vastaanottaa tunnistuspyynnön HTTP Redirect tai HTTP POST-kutsuna. Koska selain on liittänyt kutsuun Vetuman käyttäjälle tekemän tunnistusevästeen, Vetuma toteaa käyttäjän jo tunnistetuksi ja ottaa käyttäjän Vetuma-kertakirjautumisistunnosta tiedon siitä, mitkä verkkopalvelut ovat mukana istunnossa. Yksi näistä on Hanhivaaran ulkoiluviraston verkkopalvelu. 4. Vetuma lähettää SAML-kertauloskirjautumispyynnön käyttäjän selaimen kautta Hanhivaaran ulkoiluviraston verkkopalvelulle. Tarkemmin sanoen Vetuma: o Rakentaa SAML-standardin mukaisen uloskirjautumispyynnön (<LogoutRequest>) jossa pyytää verkkopalvelua tekemään kertauloskirjautumisen. o Lähettää pyynnön Hanhivaaran ulkoiluviraston verkkopalvelulle käyttäen SAMLstandardissa määriteltyä Redirect-sidosta (HTTP Redirect binding) tai POSTsidosta (HTTP POST binding). Copyright Fujitsu Finland Oy 12 (17) Pag Vetuma-palvelu SAML-kutsurajapinnan määrittely Versio: 3.4 14.1.2015 14.1.2015 5. Hanhivaaran ulkoiluviraston verkkopalvelu vastaanottaa SAML-uloskirjautumispyynnön ja päättää käyttäjän verkkopalveluistunnon kyseisessä palvelussa. 6. Hanhivaaran ulkoiluviraston verkkopalvelu rakentaa SAML-uloskirjautumisvastauksen (<LogoutResponse>) ja lähettää sen käyttäjän selaimen kautta Vetumalle. 7. Vetuma lähettää myös kullekin muulle kertakirjautumisistunnossa mukana olevalle verkkopalvelulle SAML-uloskirjautumispyynnön ja vastaanottaa niiden SAMLuloskirjautumisvastaukset. 8. Vetuma lopettaa käyttäjän Vetuma-kertakirjautumisistunnon. 9. Vetuma rakentaa SAML-uloskirjautumisvastauksen (<LogoutResponse>) ja lähettää sen käyttäjän selaimen kautta Ankkalinnan päivähoidon verkkopalvelulle. 10. Ankkalinnan päivähoidon verkkopalvelu lopettaa käyttäjän verkkopalveluistunnon kyseisessä palvelussa. 11. Ankkalinnan päivähoidon verkkopalvelu palauttaa käyttäjän selaimelle HTTP-vastauksen jolla ilmoittaa käyttäjälle kertauloskirjautumisen tapahtuneeksi. Copyright Fujitsu Finland Oy 13 (17) Pag Vetuma-palvelu SAML-kutsurajapinnan määrittely Versio: 3.4 14.1.2015 Käyttäjän selain Ankkalinnan päivähoidon verkkopalvelu 14.1.2015 Hanhivaaran ulkoiluviraston verkkopalvelu VETUMA 1. Kertauloskirjaudu Kertakirjautumisistunto 2. SAML kertauloskirjautumiskutsu 3. Ota istunnossa mukana olevat verkkopalvelut 4. SAML kertauloskirjautumiskutsu Verkkopalveluistunto 5. Lopeta 6. SAML kertauloskirjautumisvastaus 7. Pyydä muilta isunnossa mukana olevilta verkkopalveluilta uloskirjautumista 8. Lopeta 9. SAML kertauloskirjautumisvastaus 11. Vastaus kutsuun jolla pyydettiin kertauloskirjautumista Verkkopalveluistunto 10. Lopeta Kuva 3: Kertauloskirjautuminen 5. TUNNISTUSLÄHTEEN HAKEMINEN VETUMAN SAML-RAJAPINNAN KAUTTA 5.1 Käyttötapauksen kuvaus 5.1.1 Yhteenveto Tässä käyttötapauksessa Vetuma-asiakkaan (Ankkalinnan kaupunki) verkkopalvelu (Ankkalinnan päivähoidon verkkopalvelu) selvittää löytyykö käyttäjältä voimassa olevaa tietoa Copyright Fujitsu Finland Oy 14 (17) Pag Vetuma-palvelu SAML-kutsurajapinnan määrittely Versio: 3.4 14.1.2015 14.1.2015 Vetuma-tunnistuspalvelun käyttämisestä ennen kuin tunnistaa käyttäjänsä Vetuman tarjoamalla SAML-standardin mukaisella tunnistuksella joka mahdollistaa myös kertakirjautumisen muiden Vetuman SAML-tunnistusta käyttävien verkkopalveluiden kesken. 5.1.2 Toimijat Käyttäjä (Ankkalinnan päivähoidon verkkopalvelua käyttävä henkilö). «System» Vetuma (SAML-roolissa Discovery Service) «System» Vetuma (SAML-roolissa Identity Provider) «System» Ankkalinnan kaupungin verkkopalvelu (SAML-roolissa Service Provider). «System» Hanhivaaran ulkoiluviraston verkkopalvelu (SAML-roolissa Service Provider). 5.1.3 Lähtötilanne Sekä Ankkalinnan kaupunki että Hanhivaaran kaupunki ovat Vetuma-asiakkaita. Sekä Ankkalinnan päivähoidon verkkopalvelu että Hanhivaaran ulkoiluviraston verkkopalvelu on liitetty Vetuman SAML-luottamusrenkaaseen ja ne käyttävät Vetuma-tunnistusta SAMLrajapinnan kautta. Käyttäjä aikoo hakea itselleen venepaikkaa. Hän on kirjautunut Hanhivaaran ulkoiluviraston verkkopalveluun ja hakenut venepaikkaa. Sen jälkeen hän siirtyy Ankkalinnan kaupungin verkkopalveluun. 5.1.4 Lopputulos Käyttäjä on kirjautunut tunnistettuna Ankkalinnan kaupungin verkkopalveluun, ja tieto tästä on käyttäjän Vetuma-kertakirjautumisistunnossa. Ankkalinnan kaupungin verkkopalvelu selvitti löytyykö käyttäjältä voimassa olevaa tietoa Vetuma-tunnistuspalvelun käyttämisestä, ja sen löytyessä tunnisti käyttäjän Vetuma-palvelussa, ja mukautti etusivua ilmoittamaan lukemattomasta asiointiviestistä käyttäjälle. Käyttäjä pääsee siirtymään eteenpäin lukemaan Ankkalinnan päivähoidon yhteenvetoa lapsensa kuluvan viikon ohjelmasta. 5.1.5 Tyypillinen tapahtumien kulku 1. Käyttäjä ottaa selaimellaan yhteyden Ankkalinnan verkkopalveluun, jonka etusivun sisältö mukautuu sen mukaan onko käyttäjä tunnistettu Vetuma-palvelussa. 2. Verkkopalvelu selvitti löytyykö käyttäjältä voimassa olevaa tietoa Vetumatunnistuspalvelun käyttämisestä Vetuma-palvelun Discovery Servicen avulla. 3. Vetuma toteaa, että käyttäjällä on voimassa oleva tieto Vetuma-tunnistuspalvelun käyttämisestä. 4. Vetuma rakentaa aiemmin selvittämistään tiedoista SAML-tunnistuslähdevastauksen, jonka lähettää Ankkalinnan verkkopalvelulle. 5. Ankkalinnan verkkopalvelulle toteaa tunnistuslähdehaun onnistuneeksi ja poimii vastauksesta tiedon, että käyttäjä on käyttänyt Vetuma-palvelua. 6. Ankkalinnan verkkopalvelulle ohjaa käyttäjän eteenpäin tunnistautumaan Vetumapalveluun. Eteneminen jatkuu aikaisempien tunnistuksen käyttötapausten mukaisesti. 5.1.6 Valinnaiset tapahtumien kulut Käyttäjällä ei ole voimassa olevaa tietoa Vetuma-tunnistuspalvelun käyttämisestä, joten Ankkalinnan verkkopalvelun mukauttaa sivua tarjoamaan kirjautuminen Vetumapalvelulla automaattisen kirjautumisen sijaan. Copyright Fujitsu Finland Oy 15 (17) Pag Vetuma-palvelu SAML-kutsurajapinnan määrittely Versio: 3.4 14.1.2015 14.1.2015 Käyttäjällä ei ole voimassa olevaa Vetuma kertakirjausistuntoa, tällöin Vetuma palauttaa tunnistuskutsuun vastauksen jossa tämä kerrotaan. Tunnistus epäonnistuu Tällöin Vetuma palauttaa vastauksen jossa tämä kerrotaan. 5.1.7 Poikkeustilanteet Verkkopalvelun lähettämä tunnistuslähdekutsu on jossain suhteessa virheellinen. Tällöin Vetuma palauttaa virheen tai palauttaa selaimen kutsun lähettäneeseen verkkopalvelun mikäli näin kutsussa pyydettiin. Kutsut asiointisovelluksilta Vetumalle ja vastaukset Vetumalta asiointisovelluksille välitetään käyttäjän työaseman kautta. Kutsujen ja vastausten välittäminen selaimen kautta saattaa epäonnistua, esimerkiksi jos käyttäjä sulkee selaimen, työasema ”kaatuu”, tai yhteys lähettävästä tai vastaanottavasta palvelimesta työasemaan katkeaa. Tällöin kutsu- tai vastausviestin aiottu saaja ei saa viestiä, mutta myöskään viestin lähettäjä ei saa tietoa välityksen epäonnistumisesta. 5.2 Toiminta teknisestä näkökulmasta Tässä käyttötapauksessa Vetuma-palvelu toimii tunnistuslähteen hakupalveluna (SAMLstandardin käsitemaailmassa Discovery Service), ja Ankkalinnan verkkopalvelu toimii palveluntarjoajana (SAML-standardin käsitemaailmassa Service Provider). Teknisesti tunnistuslähteen hakeminen toimii seuraavasti: 1. Käyttäjän pyytäessä Ankkalinnan verkkopalvelulta etusivua, hänen selaimestaan lähtee verkkopalvelulle HTTP-kutsu jonka verkkopalvelu tulkitsee ja toteaa tarpeen selvittää käyttäjän käyttämä aktiivinen tunnistuslähde. 2. Verkkopalvelu lähettää SAML-tunnistuslähteen selvityspyynnön käyttäjän selaimen kautta Vetumalle. Tarkemmin sanoen verkkopalvelu: o Rakentaa SAML-standardin mukaisen tunnistuslähdekyselyn sisältävän URL:n parametreineen, jossa pyytää Vetumaa selvittämään aktiivisen tunnistuslähteen. o Lähettää pyynnön Vetumalle ohjaamalla käyttäjän selaimen siirtymään muodostettuun osoitteeseen (HTTP GET). 3. Vetuma vastaanottaa tunnistuslähdepyynnön HTTP GET-kutsuna. Vetuma tulkitsee kutsussa annetut määräykset tunnistuslähde selvityksen suorittamiselle, sekä käy käyttäjän selaimen kanssa keskustelun aktiivisen käyttäjäistunnon selvittämiseksi. Vetuma toteaa että käyttäjä on aktiivinen tunnistuspalvelun käyttäjä, mikäli Vetuman käyttäjälle tekemä tunnistuslähde-eväste löytyy kutsusta. 4. Vetuma rakentaa ja lähettää SAML-tunnistuslähdevastauksen käyttäjän selaimen kautta verkkopalvelulle. Tarkemmin sanoen Vetuma: o Rakentaa SAML-standardin mukaisen URL:n parametreineen ja laittaa siihen tiedoksi käyttäjän käyttämän tunnistuspalvelun tunnisteen mikäli tunnistuslähde on ollut käytössä. Mikäli tunnistuslähde ei selvinnyt tai tapahtui muu virhe, jätetään kyseinen parametri pois vastauksesta. o Lähettää pyynnön Ankkalinnan verkkopalvelulle ohjaamalla käyttäjän selaimen siirtymään muodostettuun osoitteeseen (HTTP GET). 5. Ankkalinnan verkkopalvelulle toteaa saamastaan SAML- tunnistuslähdevastauksesta tunnistuslähdehaun onnistuneeksi ja poimii vastauksesta tiedon, että käyttäjä on käyttänyt Vetuma-palvelua. Mikäli kyseinen tieto puuttui vastauksesta, tulkitsee verkkopalvelu kyselyn epäonnistuneeksi. Copyright Fujitsu Finland Oy 16 (17) Pag Vetuma-palvelu SAML-kutsurajapinnan määrittely Versio: 3.4 14.1.2015 14.1.2015 6. Ankkalinnan verkkopalvelulle ohjaa käyttäjän eteenpäin tunnistautumaan Vetumapalveluun. Eteneminen jatkuu aikaisempien tunnistuksen käyttötapausten mukaisesti. Käyttäjän selain Ankkalinnan verkkopalvelu VETUMA 1. Kutsu jolla pyydet ään etusivua 2. SAML tunnistuslähteen hakukutsu 3. Tunnistuslähteen selvitys 4. SAML tunnistuslähdevastaus 5. Saa tiedon tunnistuslähteestä 6. Vastaus jolla ohjataan eteenpäin selvitettyyn tunnistuspalveluun Käytt ö jatkuu tunnistuksella Kuva 4: Tunnistuslähteen hakeminen Vetuman SAML-rajapinnan kautta Copyright Fujitsu Finland Oy 17 (17) Pag
© Copyright 2024