Sumalaisen julkishallinnn Vetuma-palvelu SAML-kutsurajapinnan käyttötapaukset Versi: 3.4 Vetuma Verkktunnistus ja -maksaminen
Versi: 3.4 14.1.2015 Sisällysluettel 1. Jhdant... 3 2. Käyttäjän tunnistaminen Vetumalla SAML-rajapinnan kautta... 4 2.1 Käyttötapauksen kuvaus... 4 2.1.1 Yhteenvet... 4 2.1.2 Timijat... 4 2.1.3 Lähtötilanne... 4 2.1.4 Lpputuls... 4 2.1.5 Tyypillinen tapahtumien kulku... 4 2.1.6 Valinnaiset tapahtumien kulut... 5 2.1.7 Pikkeustilanteet... 5 2.2 Timinta teknisestä näkökulmasta... 5 3. Kertakirjautuminen Vetuman avulla SAML-rajapinnan kautta... 8 3.1 Käyttötapauksen kuvaus... 8 3.1.1 Yhteenvet... 8 3.1.2 Timijat... 8 3.1.3 Lähtötilanne... 8 3.1.4 Lpputuls... 8 3.1.5 Tyypillinen tapahtumien kulku... 8 3.1.6 Valinnaiset tapahtumien kulut... 9 3.1.7 Pikkeustilanteet... 9 3.2 Timinta teknisestä näkökulmasta... 9 4. Ulskirjautuminen Vetuma-kertakirjautumisistunnsta... 11 4.1 Käyttötapauksen kuvaus... 11 4.1.1 Yhteenvet... 11 4.1.2 Timijat... 11 4.1.3 Lähtötilanne... 11 4.1.4 Lpputuls... 11 4.1.5 Tyypillinen tapahtumien kulku... 11 4.1.6 Valinnaiset tapahtumien kulut... 12 4.1.7 Pikkeustilanteet... 12 4.2 Timinta teknisestä näkökulmasta... 12 5. Tunnistuslähteen hakeminen Vetuman SAML-rajapinnan kautta... 14 5.1 Käyttötapauksen kuvaus... 14 5.1.1 Yhteenvet... 14 5.1.2 Timijat... 15 5.1.3 Lähtötilanne... 15 5.1.4 Lpputuls... 15 5.1.5 Tyypillinen tapahtumien kulku... 15 5.1.6 Valinnaiset tapahtumien kulut... 15 5.1.7 Pikkeustilanteet... 16 5.2 Timinta teknisestä näkökulmasta... 16 Cpyright Fujitsu Finland Oy 2 (17)
Versi: 3.4 14.1.2015 1. JOHDANTO Vetuma-palvelu n kansalaisten verkktunnistus- ja maksamispalvelu jka n tarkitettu julkishallinnn rganisaatiiden asiintisvelluksien käyttöön. Fujitsu Finland Oy tuttaa palveluntuttajan minaisuudessa Vetuma-palvelun valtin ja kuntien eri rganisaatiiden käyttöön. Vetuma-palvelun svellushjelmille tarjama timinnallisuus n kuvattu erillisessä dkumentissa Sumalaisen julkishallinnn Vetuma-palvelu, svelluksille tarjtun timinnallisuuden kuvaus. Vetuma-palvelukknaisuus sisältää svelluksille tarjtun timinnallisuuden lisäksi mm. laskutukseen ja raprtintiin liittyviä timintja. Edellä mainitussa timinnallisuuden kuvausdkumentissa n kuitenkin kuvattu ainastaan svelluksille tarjttu timinnallisuus. Svellukset vivat käyttää Vetuma-palvelun niille tarjamaa timinnallisuutta Vetuman man kutsurajapinnan kautta, jka n määritelty dkumentissa Sumalaisen julkishallinnn Vetumapalvelu Kutsurajapinnan määrittely. Lisäksi svellukset vivat käyttää Vetuma-palvelun tunnistustimintja sekä SAML-kertakirjautumista ja kertaulskirjautumista Vetuman SAMLkutsurajapinnan kautta. Sen käyttö n kuvattu dkumentissa: Vetuma-palvelun SAMLkutsurajapinnan määrittely. Tämä dkumentti kuvaa seuraavat Vetuma-palvelun SAML-kutsurajapinnan käyttötapaukset: Käyttäjän tunnistaminen Vetumalla SAML-rajapinnan kautta Kertakirjautuminen Vetumaan SAML-rajapinnan kautta liittyneiden verkkpalveluiden kesken Ulskirjautuminen Vetuma-kertakirjautumisistunnsta Tunnistuslähteen hakeminen Vetuman versissa 3.4 tteutettavaan SAML-timinnallisuuteen ei sisälly kertakirjautumista sellaisten verkkpalveluiden kanssa jtka käyttävät muita Identity Prvidereita (esimerkiksi tunnistus.fi tai Haka-luttamusverkn Identity Prviderit) käyttäjien tunnistamiseen. Kertakirjautuminen sellaisten verkkpalveluiden kesken jtka käyttävät jk Vetuman tai tunnistus.fi:n SAML-rajapintaa tunnistamiseen tullaan tukemaan myöhemmässä Vetuman versissa. Käyttötapausten tekniset kuvaukset perustuvat siihen, että Vetuma tukee SAML:in HTTP POST-sidsta (binding) kutsujen ja vastausten välittämisessä. SAML:in HTTP Redirectsids (binding) n tuettu tunnistuskutsujen ja ulskirjauksen välittämisessä. Versissa 3.3 n palveluun lisätty SAML tunnistuslähdekysely. Versissa 3.4. n lisätty tuki HTTP Redirect-sidkselle ja päivitetty tuki pankkien nykyisille rajapinnille. Versin myötä siirrytään tukemaan julkishallinnn SAML-prfiilia. Tunnistusvastauksissa käytetään jatkssa XML-allekirjituksissa algritmia RSAwithSHA256 ja määrityksen mukaista arva vahvan tunnistuksen menetelmille. Cpyright Fujitsu Finland Oy 3 (17)
Versi: 3.4 14.1.2015 2. KÄYTTÄJÄN TUNNISTAMINEN VETUMALLA SAML-RAJAPINNAN KAUTTA 2.1 Käyttötapauksen kuvaus 2.1.1 Yhteenvet 2.1.2 Timijat 2.1.3 Lähtötilanne 2.1.4 Lpputuls Tässä käyttötapauksessa Vetuma-asiakkaan (Ankkalinnan kaupunki) verkkpalvelu (Ankkalinnan päivähidn verkkpalvelu) tunnistaa käyttäjänsä Vetuman tarjamalla SAMLstandardin mukaisella tunnistuksella jka mahdllistaa myös kertakirjautumisen muiden Vetuman SAML-tunnistusta käyttävien verkkpalveluiden kesken. Käyttäjä (Ankkalinnan päivähidn verkkpalvelua käyttävä henkilö). «System» Vetuma (SAML-rlissa Identity Prvider) «System» Ankkalinnan päivähidn verkkpalvelu (SAML-rlissa Service Prvider). Ankkalinnan kaupunki n Vetuma-asiakas. Ankkalinnan päivähidn verkkpalvelu n liitetty Vetuman SAML-luttamusrenkaaseen ja se käyttää Vetuma-tunnistusta SAML-rajapinnan kautta. Käyttäjä n muuttamassa Ankkalinnaan. Hän aik käyttää Ankkalinnan päivähidn verkkpalvelua hakeakseen lapselleen päivähitpaikkaa. Hitpaikan hakeminen vaatii kirjautumista kyseiseen verkkpalveluun, jka pulestaan vaatii tunnistuksen. Käyttäjä n tunnistettu ja kirjautunut Ankkalinnan kaupungin päivähidn verkkpalveluun, ja hänellä n kertakirjautumisistunt Vetumassa. 2.1.5 Tyypillinen tapahtumien kulku 1. Käyttäjä ttaa selaimellaan yhteyden Ankkalinnan päivähidn verkkpalveluun ja pyytää päivähitpaikan varaamista. Varaaminen n timint jka edellyttää kirjautumista ja sen myötä tunnistamista. 2. Verkkpalvelu tteaa tarpeen tunnistaa käyttäjä, ja lähettää tunnistuspyynnön Vetumalle. 3. Vetuma tarjaa käyttäjän valittavaksi SAML-rajapinnan yhteydessä tuetut tunnistusmenetelmät (Tupas, kansalaisvarmennetunnistus ja mbiilivarmennetunnistus) ja tunnistaa käyttäjän hänen valitsemallaan tavalla. Mikäli käyttäjä tunnistautuu kansalaisvarmenteeseen perustuvalla menetelmällä, haetaan aina VTJstä käyttäjän HETU. Tämä vaatii, että kaikilla Vetuman SAML-asiakkailla n HETUn hakuspimus VRKn kanssa. Vetuman SAML-asiakkailla n myös mahdllista käyttää laajennettua VTJ-kyselyä, mikäli VRK:n kanssa n näin svittu. 4. Vetuma lu käyttäjälle kertakirjautumisistunnn ja tallettaa siihen tunnistuksesta saamansa tiedt, sekä rakentaa niistä tunnistusvastauksen, jnka lähettää Ankkalinnan päivähidn verkkpalvelulle. Laajennetun VTJ-kyselyn tuls n käytettävissä ainastaan tässä käyttötapauksessa kun käyttäjä tunnistautuu. Tiet Vetuma-tunnistuksen käyttämisestä Cpyright Fujitsu Finland Oy 4 (17)
Versi: 3.4 14.1.2015 tunnistuslähteenä tallennetaan myös istunnn ajaksi käyttäjän selaimeen hyödyntäen sitetta, jka kuuluu valittuun dmainiin. 5. Ankkalinnan päivähidn verkkpalvelu tteaa tunnistuksen nnistuneeksi, pimii vastauksesta käyttäjän henkilöllisyyden ja muut tarvitsemansa tiedt, ja lu käyttäjälle man verkkpalveluistuntnsa. 2.1.6 Valinnaiset tapahtumien kulut 2.1.7 Pikkeustilanteet Käyttäjä peruu tunnistuksen Tällöin Vetuma palauttaa vastauksen jssa tämä kerrtaan. Tunnistus epännistuu Tällöin Vetuma palauttaa vastauksen jssa tämä kerrtaan. Verkkpalvelun lähettämä tunnistuskutsu n jssain suhteessa virheellinen. Tällöin Vetuma palauttaa vastauksen jssa tämä tdetaan, mikäli Vetuma pystyy tdentamaan kutsun lähettäneen verkkpalvelun. Kutsut asiintisvelluksilta Vetumalle ja vastaukset Vetumalta asiintisvelluksille välitetään käyttäjän työaseman kautta. Myös kutsut Vetumalta pankkien verkkpalveluihin sekä vastaukset niiltä Vetumalle välitetään käyttäjän työaseman kautta. Kutsujen ja vastausten välittäminen selaimen kautta saattaa epännistua, esimerkiksi js käyttäjä sulkee selaimen, työasema kaatuu, tai yhteys lähettävästä tai vastaanttavasta palvelimesta työasemaan katkeaa. Tällöin kutsu- tai vastausviestin aittu saaja ei saa viestiä, mutta myöskään viestin lähettäjä ei saa tieta välityksen epännistumisesta. 2.2 Timinta teknisestä näkökulmasta Tässä käyttötapauksessa Vetuma-palvelu timii identiteetintarjajana (SAML-standardin käsitemaailmassa Identity Prvider), ja Ankkalinnan päivähidn verkkpalvelu timii palveluntarjajana (SAML-standardin käsitemaailmassa Service Prvider). Teknisesti tunnistus timii seuraavasti: 1. Käyttäjän pyytäessä Ankkalinnan päivähidn verkkpalvelulta päivähitpaikan varaamista, hänen selaimestaan lähtee verkkpalvelulle HTTP-kutsu jnka verkkpalvelu tulkitsee ja tteaa tarpeen tunnistaa käyttäjä. 2. Verkkpalvelu lähettää SAML-tunnistuspyynnön käyttäjän selaimen kautta Vetumalle. Tarkemmin sanen verkkpalvelu: Rakentaa SAML-standardin mukaisen tunnistuspyynnön (<AuthnRequest>) jssa pyytää Vetuman tekemään tunnistuksen. Lähettää pyynnön Vetumalle käyttäen SAML-standardissa määriteltyä Redirectsidsta (HTTP Redirect binding) tai POST-sidsta (HTTP POST binding). 3. Vetuma vastaanttaa tunnistuspyynnön HTTP Redirect-kutsuna tai HTTP POST-kutsuna. Kska kutsussa ei le Vetuman käyttäjälle tekemää tunnistusevästettä, Vetuma tteaa että käyttäjä pitää tunnistaa. Vetuma tulkitsee kutsussa annetut määräykset tunnistuksen surittamiselle, sekä käy käyttäjän kanssa tunnistuskeskustelun käyttäjän selaimen välityksellä. Tunnistuksen eri vaiheita ei le tarkemmin purettu auki kuvassa 1. Mikäli käyttäjä valitsee Tupas-tunnistuksen, Vetuma hjaa käyttäjän tunnistautumaan hänen valitsemansa pankin verkkpalveluun. Mikäli käyttäjä tunnistautui kansalaisvarmenteeseen perustuvalla menetelmällä, Vetuma hakee käyttäjän HETUn VTJ-palvelusta. Cpyright Fujitsu Finland Oy 5 (17)
Versi: 3.4 14.1.2015 4. Vetuma lu käyttäjälle Vetuma-kertakirjautumisistunnn ja tallettaa siihen käyttäjän tunnistuksesta saadut tiedt (henkilöllisyyden, muut käyttäjää kuvaavat tiedt, sekä tiedt tunnistustapahtumasta). Vetuma merkitsee myös Ankkalinnan päivähidn verkkpalvelun kyseiseen istuntn sallistuvaksi palveluksi. Lisäksi Vetuma lu tunnistusevästeen jnka avulla se vi myöhemmin tdeta tunnistuksen tehdyksi (kun muut verkkpalvelut pyytävät saman käyttäjän tunnistamista). Tiet Vetuma-tunnistuksen käyttämisestä tunnistuslähteenä tallennetaan istunnn ajaksi käyttäjän selaimeen lumalla tunnistuslähde-evästeen, jka asetetaan selaimeen hyödyntäen valittuun dmainiin kuuluvaa sitetta. Evästeitä ei le esitetty kuvassa 1. 5. Vetuma rakentaa ja lähettää SAML-tunnistusvastauksen käyttäjän selaimen kautta verkkpalvelulle. Tarkemmin sanen Vetuma: Rakentaa SAML-standardin mukaisen vastauksen (<Respnse>) ja laittaa siihen käyttäjän tunnistuksesta saamistaan tiedista mudstamansa selsteet (<Assertin>-elementit). Lähettää vastauksen Ankkalinnan päivähidn verkkpalvelulle käyttäen SAMLstandardissa määriteltyä POST-sidsta (HTTP POST binding). Vetuman tunistuseväste päätyy selaimelle tunnistusvastauksen kulkiessa selaimen kautta 6. Ankkalinnan päivähidn verkkpalvelu tteaa saamastaan SAML-tunnistusvastauksesta tunnistuksen nnistuneeksi, pimii vastauksesta käyttäjän henkilöllisyyden, ja lu käyttäjälle man verkkpalveluistuntnsa. Tapaa jlla verkkpalvelu ilmaisee istunnn lemassaln (esimerkiksi eväste) ei le esitetty kuvassa 1. 7. Ankkalinnan päivähidn verkkpalvelu palauttaa käyttäjän selaimelle HTTP-vastauksena sivun, jlta käyttäjä vi jatkaa verkkpalvelun käyttöä kirjautuneena. Cpyright Fujitsu Finland Oy 6 (17)
Versi: 3.4 14.1.2015 Käyttäjän selain Ankkalinnan päivähidn verkkpalvelu VETUMA 1. Kutsu jlla pyydetään päivähitpaikan varaamista 2. SAML tunnistuskutsu 3. Tunnistuskeskustelu 4. Lu 5. SAML tunnistusvastaus 7. Vastaus kutsuun jlla pyydettiin päivähitpaikan varaamista 6. Lu Kertakirjautumisistunt Verkkpalveluistunt Käyttö jatkuu tunnistettuna Kuva 1: Kirjautuminen Vetuman SAML-rajapinnan kautta Cpyright Fujitsu Finland Oy 7 (17)
Versi: 3.4 14.1.2015 3. KERTAKIRJAUTUMINEN VETUMAN AVULLA SAML-RAJAPINNAN KAUTTA 3.1 Käyttötapauksen kuvaus 3.1.1 Yhteenvet 3.1.2 Timijat 3.1.3 Lähtötilanne 3.1.4 Lpputuls Tässä käyttötapauksessa käyttäjä n tunnistettu Vetuman SAML-rajapinnan kautta tiettyyn verkkpalveluun (Ankkalinnan päivähidn verkkpalvelu). Siellä asiituaan käyttäjä siirtyy tiseen Vetuman SAML-tunnistusta käyttävään verkkpalveluun (Hanhivaaran ulkiluvirastn verkkpalvelu) ja pyytää timinta jka vaatii tunnistusta. Jälkimmäinen verkkpalvelu pyytää Vetumalta tunnistusta, mutta kska Vetuma vi tdeta käyttäjän j tunnistetuksi, se saa tiedt käyttäjästä ja tunnistustapahtumasta käyttäjän Vetuma-kertakirjautumisistunnsta ja palauttaa ne jälkimmäiselle verkkpalvelulle. Käyttäjää ei siis vaivata tunnistautumaan uudelleen. Käyttäjä (Ankkalinnan ja Hanhivaaran verkkpalveluita käyttävä henkilö). «System» Vetuma (SAML-rlissa Identity Prvider) «System» Ankkalinnan päivähidn verkkpalvelu (SAML-rlissa Service Prvider). «System» Hanhivaaran ulkiluvirastn verkkpalvelu (SAML-rlissa Service Prvider). Sekä Ankkalinnan kaupunki että Hanhivaaran kaupunki vat Vetuma-asiakkaita. Sekä Ankkalinnan päivähidn verkkpalvelu että Hanhivaaran ulkiluvirastn verkkpalvelu n liitetty Vetuman SAML-luttamusrenkaaseen ja ne käyttävät Vetuma-tunnistusta SAMLrajapinnan kautta. Käyttäjä n muuttamassa Ankkalinnaan. Hän n kirjautunut Ankkalinnan päivähidn verkkpalveluun ja hakenut lapselleen päivähitpaikkaa. Sen jälkeen hän aik käyttää naapurikaupungin Hanhivaaran ulkiluvirastn verkkpalvelua hakeakseen itselleen venepaikkaa. Venepaikan hakeminen vaatii kirjautumista palveluun, jka pulestaan vaatii tunnistuksen. Käyttäjä n kirjautunut tunnistettuna Hanhivaaran ulkiluvirastn verkkpalveluun, ja tiet tästä n käyttäjän Vetuma-kertakirjautumisistunnssa 3.1.5 Tyypillinen tapahtumien kulku 1. Käyttäjä siirtyy selaimellaan Hanhivaaran ulkiluvirastn verkkpalveluun ja pyytää venepaikan varaamista (timint jka edellyttää kirjautumista). 2. Verkkpalvelu tteaa tarpeen tunnistaa käyttäjä, ja lähettää tunnistuspyynnön Vetumalle. 3. Vetuma tteaa, että käyttäjä n j tunnistettu, ja hänen henkilöllisyytensä, muut tunnistuksesta saadut tietnsa ja tiedt tunnistustapahtumasta vat j käytettävissä. 4. Vetuma rakentaa aiemmin tehdystä tunnistuksesta saamistaan tiedista SAMLtunnistusvastauksen, jnka lähettää Hanhivaaran ulkiluvirastn verkkpalvelulle. 5. Hanhivaaran ulkiluvirastn verkkpalvelu tteaa tunnistuksen nnistuneeksi, pimii vastauksesta käyttäjän henkilöllisyyden ja muut tarvitsemansa tiedt, ja lu käyttäjälle man istuntnsa. Cpyright Fujitsu Finland Oy 8 (17)
Versi: 3.4 14.1.2015 3.1.6 Valinnaiset tapahtumien kulut 3.1.7 Pikkeustilanteet Verkkpalvelun lähettämä tunnistuskutsu n jssain suhteessa virheellinen. Tällöin Vetuma palauttaa vastauksen jssa tdetaan tämä. Kutsun tai vastauksen välittäminen selaimen kautta epännistuu (kats käyttötapaus Käyttäjän tunnistaminen Vetumalla SAML-rajapinnan kautta ). 3.2 Timinta teknisestä näkökulmasta Tässä käyttötapauksessa Vetuma-palvelu timii identiteetintarjajana (SAML-standardin käsitemaailmassa Identity Prvider), ja Hanhivaaran ulkiluvirastn verkkpalvelu timii palveluntarjajana (SAML-standardin käsitemaailmassa Service Prvider). Teknisesti tunnistus timii seuraavasti: 1. Käyttäjän pyytäessä Hanhivaaran ulkiluvirastn verkkpalvelulta venepaikan varaamista (timinta jka edellyttää kirjautumista), hänen selaimestaan lähtee verkkpalvelulle HTTP-kutsu jnka verkkpalvelu tulkitsee ja tteaa tarpeen tunnistaa käyttäjä. 2. Verkkpalvelu lähettää SAML-tunnistuspyynnön käyttäjän selaimen kautta Vetumalle. Tarkemmin sanen verkkpalvelu: Rakentaa SAML-standardin mukaisen tunnistuspyynnön (<AuthnRequest>) jssa pyytää Vetuman tekemään tunnistuksen. Lähettää pyynnön Vetumalle käyttäen SAML-standardissa määriteltyä Redirectsidsta (HTTP Redirect binding) tai POST-sidsta (HTTP POST binding), mukaan lukien kutsun ja vastauksen krrelintiin käytettävän RelayState-tiedn välittämisen kyseiselle sidkselle määrätyllä tavalla). 3. Vetuma vastaanttaa tunnistuspyynnön HTTP Redirect tai HTTP POST-kutsuna. Kska selain n liittänyt kutsuun Vetuman käyttäjälle tekemän tunnistusevästeen, Vetuma tteaa käyttäjän j tunnistetuksi ja ttaa käyttäjää ja tunnistustapahtumaa kskevat tiedt hänen Vetuma-kertakirjautumisistunnstaan. Vetuma lisää myös Hanhivaaran ulkiluvirastn verkkpalvelun käyttäjän Vetuma-kertakirjautumisistuntn istuntn sallistuvaksi palveluksi. 4. Vetuma rakentaa ja lähettää SAML-tunnistusvastauksen käyttäjän selaimen kautta Hanhivaaran ulkiluvirastn verkkpalvelulle. Tarkemmin sanen Vetuma: Rakentaa SAML-standardin mukaisen vastauksen (<Respnse>) ja laittaa siihen käyttäjän tunnistuksesta saamistaan tiedista mudstamansa selsteet (<Assertin>-elementit). Lähettää vastauksen Hanhivaaran ulkiluvirastn verkkpalvelulle käyttäen SAMLstandardissa määriteltyä POST-sidsta (HTTP POST binding), mukaan lukien kutsun ja vastauksen krrelintiin käytettävän RelayState-tiedn välittämisen kyseiselle sidkselle määrätyllä tavalla) 5. Hanhivaaran ulkiluvirastn verkkpalvelu tteaa saamastaan SAML-tunnistusvastauksesta tunnistuksen nnistuneeksi, pimii vastauksesta käyttäjän henkilöllisyyden, ja lu käyttäjälle man verkkpalveluistuntnsa. Tapaa jlla verkkpalvelu ilmaisee istunnn lemassaln (esimerkiksi eväste) ei le esitetty kuvassa 2. 6. Hanhivaaran ulkiluvirastn verkkpalvelu palauttaa käyttäjän selaimelle HTTPvastauksena sivun, jlta käyttäjä vi jatkaa verkkpalvelun käyttöä kirjautuneena. Cpyright Fujitsu Finland Oy 9 (17)
Versi: 3.4 14.1.2015 Käyttäjän selain Ankkalinnan päivähidn verkkpalvelu Hanhivaaran ulkiluvirastn verkkpalvelu VETUMA Käyttö jatkuu tunnistettuna 1. Kutsu jlla pyydetään venepaikan varaamista 2. SAML tunnistuskutsu 3. Ota tiedt, lisää uusi palvelu istuntn 4. SAML tunnistusvastaus 6. Vastaus kutsuun jlla pyydettiin venepaikan varaamista 5. Lu Kertakirjautumisistunt Verkkpalveluistunt Käyttö jatkuu tunnistettuna Kuva 2: Kertakirjautuminen Vetuman SAML-rajapinnan kautta Cpyright Fujitsu Finland Oy 10 (17)
Versi: 3.4 14.1.2015 4. ULOSKIRJAUTUMINEN VETUMA-KERTAKIRJAUTUMISISTUNNOSTA 4.1 Käyttötapauksen kuvaus 4.1.1 Yhteenvet 4.1.2 Timijat 4.1.3 Lähtötilanne 4.1.4 Lpputuls Tässä käyttötapauksessa käyttäjä n tunnistettu Vetuman avulla useisiin Vetuma-asiakkaiden verkkpalveluihin (mukaan lukien Ankkalinnan päivähidn verkkpalvelu ja Hanhivaaran ulkiluvirastn verkkpalvelu), ja hänellä n kertakirjautumisistunt Vetumassa. Ankkalinnan päivähidn verkkpalvelu tarjaa ulskirjautumisen tällaisesta Vetumakertakirjautumisistunnsta. Käyttäjän pyytäessä tätä timinta kyseinen verkkpalvelu lähettää Vetumalle kertaulskirjautumispyynnön. Vetuma välittää kertaulskirjautumispyynnön kaikille muille Vetuma-kertakirjautumisistuntn sallistuville verkkpalveluille. Kukin näistä verkkpalveluista päättää man istuntnsa. Vetuma päättää man kertaulskirjautumisistuntnsa ja palauttaa tiedn nnistuneesta kertaulskirjautumisesta Ankkalinnan päivähidn verkkpalvelulle. Käyttäjä (Ankkalinnan ja Hanhivaaran verkkpalveluita käyttävä henkilö). «System» Vetuma (SAML-rlissa Identity Prvider) «System» Ankkalinnan päivähidn verkkpalvelu (SAML-rlissa Service Prvider). «System» Hanhivaaran ulkiluvirastn verkkpalvelu (SAML-rlissa Service Prvider). Sekä Ankkalinnan kaupunki että Hanhivaaran kaupunki vat Vetuma-asiakkaita. Sekä Ankkalinnan päivähidn verkkpalvelu että Hanhivaaran ulkiluvirastn verkkpalvelu n liitetty Vetuman SAML-luttamusrenkaaseen ja ne käyttävät Vetuma-tunnistusta SAMLrajapinnan kautta. Ankkalinnan päivähidn verkkpalvelu tarjaa käyttöliittymässään ulskirjautumisen kertakirjautumisistunnsta. Käyttäjä n tunnistettu Vetuman tarjaman SAML-kertakirjautumisen avulla Ankkalinnan päivähidn verkkpalveluun ja Hanhivaaran ulkiluvirastn verkkpalveluun sekä jihinkin muiden Vetuma-asiakkaiden SAML-tunnistusta käyttäviin verkkpalveluihin. Käyttäjä n ulskirjautunut Ankkalinnan kaupungin päivähidn verkkpalvelusta ja Hanhivaaran ulkiluvirastn verkkpalvelusta sekä muista käyttäjän Vetumakertakirjautumisistunnssa mukana levista verkkpalveluista. 4.1.5 Tyypillinen tapahtumien kulku 1. Käyttäjä pyytää selaimellaan Ankkalinnan päivähidn verkkpalvelun tarjamaa kertaulskirjautumista. 2. Ankkalinnan päivähidn verkkpalvelu lähettää kertaulskirjautumispyynnön Vetumalle. 3. Vetuma tteaa, että käyttäjällä n vimassa leva Vetuma-kertakirjautumisistunt, ja ttaa siitä tiedn mitkä kaikki verkkpalvelut (mukaan lukien Hanhivaaran ulkiluvirastn verkkpalvelu) sallistuvat kyseiseen kertakirjautumisistuntn. 4. Vetuma lähettää ulskirjautumispyynnön kullekin kertakirjautumisistuntn sallistuvista verkkpalveluista (mukaan lukien Hanhivaaran ulkiluvirastn verkkpalvelu). Cpyright Fujitsu Finland Oy 11 (17)
Versi: 3.4 14.1.2015 5. Kukin näistä verkkpalveluista päättää man verkkpalveluistuntnsa, ja kuittaa ulskirjautumisvastauksella Vetumalle päättämisen tehdyksi. 6. Saatuaan kaikki ulskirjautumisvastaukset Vetuma hävittää käyttäjän Vetumakertakirjautumisistunnn ja lähettää ulskirjautumisvastauksen Ankkalinnan päivähidn verkkpalvelulle. 7. Ankkalinnan päivähidn verkkpalvelu päättää man verkkpalveluistuntnsa. 4.1.6 Valinnaiset tapahtumien kulut 4.1.7 Pikkeustilanteet Verkkpalvelun lähettämä ulskirjautumiskutsu n jssain suhteessa virheellinen. Tällöin Vetuma palauttaa vastauksen jssa tdetaan tämä. Jku istuntn mukaan tetuista verkkpalveluista ei vastaa Vetuman sille lähettämään ulskirjautumiskutsuun. (kats käyttötapaus Käyttäjän tunnistaminen Vetumalla SAML-rajapinnan kautta ) Kutsun tai vastauksen välittäminen selaimen kautta epännistuu (kats käyttötapaus Käyttäjän tunnistaminen Vetumalla SAML-rajapinnan kautta ) 4.2 Timinta teknisestä näkökulmasta Tässä käyttötapauksessa Vetuma-palvelu timii identiteetintarjajana (SAML-standardin käsitemaailmassa Identity Prvider), ja Hanhivaaran ulkiluvirastn verkkpalvelu timii palveluntarjajana (SAML-standardin käsitemaailmassa Service Prvider). Tässä käyttötapauksessa palveluntarjaja pyytää identiteetintarjajaa tunnistamaan käyttäjän hjaamalla hänet identiteetintarjajan tunnistuspalveluun. Teknisesti tunnistus timii seuraavasti: 1. Käyttäjä pyytää kertaulskirjautumista Ankkalinnan päivähidn verkkpalvelussa, jllin hänen selaimestaan lähtee verkkpalvelulle HTTP-kutsu jnka jhdsta verkkpalvelussa tdetaan halu tehdä kertaulskirjautuminen. 2. Verkkpalvelu lähettää SAML-ulskirjautumispyynnön käyttäjän selaimen kautta Vetumalle. Tarkemmin sanen verkkpalvelu: Rakentaa SAML-standardin mukaisen ulskirjautumispyynnön (<LgutRequest>) jssa pyytää Vetuman tekemään kertaulskirjautumisen. Lähettää pyynnön Vetumalle käyttäen SAML-standardissa määriteltyä Redirectsidsta (HTTP Redirect binding) tai POST-sidsta (HTTP POST binding). 3. Vetuma vastaanttaa tunnistuspyynnön HTTP Redirect tai HTTP POST-kutsuna. Kska selain n liittänyt kutsuun Vetuman käyttäjälle tekemän tunnistusevästeen, Vetuma tteaa käyttäjän j tunnistetuksi ja ttaa käyttäjän Vetuma-kertakirjautumisistunnsta tiedn siitä, mitkä verkkpalvelut vat mukana istunnssa. Yksi näistä n Hanhivaaran ulkiluvirastn verkkpalvelu. 4. Vetuma lähettää SAML-kertaulskirjautumispyynnön käyttäjän selaimen kautta Hanhivaaran ulkiluvirastn verkkpalvelulle. Tarkemmin sanen Vetuma: Rakentaa SAML-standardin mukaisen ulskirjautumispyynnön (<LgutRequest>) jssa pyytää verkkpalvelua tekemään kertaulskirjautumisen. Lähettää pyynnön Hanhivaaran ulkiluvirastn verkkpalvelulle käyttäen SAMLstandardissa määriteltyä Redirect-sidsta (HTTP Redirect binding) tai POSTsidsta (HTTP POST binding). Cpyright Fujitsu Finland Oy 12 (17)
Versi: 3.4 14.1.2015 5. Hanhivaaran ulkiluvirastn verkkpalvelu vastaanttaa SAML-ulskirjautumispyynnön ja päättää käyttäjän verkkpalveluistunnn kyseisessä palvelussa. 6. Hanhivaaran ulkiluvirastn verkkpalvelu rakentaa SAML-ulskirjautumisvastauksen (<LgutRespnse>) ja lähettää sen käyttäjän selaimen kautta Vetumalle. 7. Vetuma lähettää myös kullekin muulle kertakirjautumisistunnssa mukana levalle verkkpalvelulle SAML-ulskirjautumispyynnön ja vastaanttaa niiden SAMLulskirjautumisvastaukset. 8. Vetuma lpettaa käyttäjän Vetuma-kertakirjautumisistunnn. 9. Vetuma rakentaa SAML-ulskirjautumisvastauksen (<LgutRespnse>) ja lähettää sen käyttäjän selaimen kautta Ankkalinnan päivähidn verkkpalvelulle. 10. Ankkalinnan päivähidn verkkpalvelu lpettaa käyttäjän verkkpalveluistunnn kyseisessä palvelussa. 11. Ankkalinnan päivähidn verkkpalvelu palauttaa käyttäjän selaimelle HTTP-vastauksen jlla ilmittaa käyttäjälle kertaulskirjautumisen tapahtuneeksi. Cpyright Fujitsu Finland Oy 13 (17)
Versi: 3.4 14.1.2015 Käyttäjän selain Ankkalinnan päivähidn verkkpalvelu Hanhivaaran ulkiluvirastn verkkpalvelu VETUMA 1. Kertaulskirjaudu 2. SAML kertaulskirjautumiskutsu 4. SAML kertaulskirjautumiskutsu 3. Ota istunnssa mukana levat verkkpalvelut Kertakirjautumisistunt Verkkpalveluistunt 5. Lpeta 6. SAML kertaulskirjautumisvastaus 7. Pyydä muilta isunnssa mukana levilta verkkpalveluilta ulskirjautumista 8. Lpeta 9. SAML kertaulskirjautumisvastaus Verkkpalveluistunt 11. Vastaus kutsuun jlla pyydettiin kertaulskirjautumista 10. Lpeta Kuva 3: Kertaulskirjautuminen 5. TUNNISTUSLÄHTEEN HAKEMINEN VETUMAN SAML-RAJAPINNAN KAUTTA 5.1 Käyttötapauksen kuvaus 5.1.1 Yhteenvet Tässä käyttötapauksessa Vetuma-asiakkaan (Ankkalinnan kaupunki) verkkpalvelu (Ankkalinnan päivähidn verkkpalvelu) selvittää löytyykö käyttäjältä vimassa levaa tieta 14 (17) Cpyright Fujitsu Finland Oy
Versi: 3.4 14.1.2015 5.1.2 Timijat 5.1.3 Lähtötilanne 5.1.4 Lpputuls Vetuma-tunnistuspalvelun käyttämisestä ennen kuin tunnistaa käyttäjänsä Vetuman tarjamalla SAML-standardin mukaisella tunnistuksella jka mahdllistaa myös kertakirjautumisen muiden Vetuman SAML-tunnistusta käyttävien verkkpalveluiden kesken. Käyttäjä (Ankkalinnan päivähidn verkkpalvelua käyttävä henkilö). «System» Vetuma (SAML-rlissa Discvery Service) «System» Vetuma (SAML-rlissa Identity Prvider) «System» Ankkalinnan kaupungin verkkpalvelu (SAML-rlissa Service Prvider). «System» Hanhivaaran ulkiluvirastn verkkpalvelu (SAML-rlissa Service Prvider). Sekä Ankkalinnan kaupunki että Hanhivaaran kaupunki vat Vetuma-asiakkaita. Sekä Ankkalinnan päivähidn verkkpalvelu että Hanhivaaran ulkiluvirastn verkkpalvelu n liitetty Vetuman SAML-luttamusrenkaaseen ja ne käyttävät Vetuma-tunnistusta SAMLrajapinnan kautta. Käyttäjä aik hakea itselleen venepaikkaa. Hän n kirjautunut Hanhivaaran ulkiluvirastn verkkpalveluun ja hakenut venepaikkaa. Sen jälkeen hän siirtyy Ankkalinnan kaupungin verkkpalveluun. Käyttäjä n kirjautunut tunnistettuna Ankkalinnan kaupungin verkkpalveluun, ja tiet tästä n käyttäjän Vetuma-kertakirjautumisistunnssa. Ankkalinnan kaupungin verkkpalvelu selvitti löytyykö käyttäjältä vimassa levaa tieta Vetuma-tunnistuspalvelun käyttämisestä, ja sen löytyessä tunnisti käyttäjän Vetuma-palvelussa, ja mukautti etusivua ilmittamaan lukemattmasta asiintiviestistä käyttäjälle. Käyttäjä pääsee siirtymään eteenpäin lukemaan Ankkalinnan päivähidn yhteenveta lapsensa kuluvan viikn hjelmasta. 5.1.5 Tyypillinen tapahtumien kulku 1. Käyttäjä ttaa selaimellaan yhteyden Ankkalinnan verkkpalveluun, jnka etusivun sisältö mukautuu sen mukaan nk käyttäjä tunnistettu Vetuma-palvelussa. 2. Verkkpalvelu selvitti löytyykö käyttäjältä vimassa levaa tieta Vetumatunnistuspalvelun käyttämisestä Vetuma-palvelun Discvery Servicen avulla. 3. Vetuma tteaa, että käyttäjällä n vimassa leva tiet Vetuma-tunnistuspalvelun käyttämisestä. 4. Vetuma rakentaa aiemmin selvittämistään tiedista SAML-tunnistuslähdevastauksen, jnka lähettää Ankkalinnan verkkpalvelulle. 5. Ankkalinnan verkkpalvelulle tteaa tunnistuslähdehaun nnistuneeksi ja pimii vastauksesta tiedn, että käyttäjä n käyttänyt Vetuma-palvelua. 6. Ankkalinnan verkkpalvelulle hjaa 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 le vimassa levaa tieta Vetuma-tunnistuspalvelun käyttämisestä, jten Ankkalinnan verkkpalvelun mukauttaa sivua tarjamaan kirjautuminen Vetumapalvelulla autmaattisen kirjautumisen sijaan. Cpyright Fujitsu Finland Oy 15 (17)
Versi: 3.4 14.1.2015 Käyttäjällä ei le vimassa levaa Vetuma kertakirjausistunta, tällöin Vetuma palauttaa tunnistuskutsuun vastauksen jssa tämä kerrtaan. Tunnistus epännistuu Tällöin Vetuma palauttaa vastauksen jssa tämä kerrtaan. 5.1.7 Pikkeustilanteet Verkkpalvelun lähettämä tunnistuslähdekutsu n jssain suhteessa virheellinen. Tällöin Vetuma palauttaa virheen tai palauttaa selaimen kutsun lähettäneeseen verkkpalvelun mikäli näin kutsussa pyydettiin. Kutsut asiintisvelluksilta Vetumalle ja vastaukset Vetumalta asiintisvelluksille välitetään käyttäjän työaseman kautta. Kutsujen ja vastausten välittäminen selaimen kautta saattaa epännistua, esimerkiksi js käyttäjä sulkee selaimen, työasema kaatuu, tai yhteys lähettävästä tai vastaanttavasta palvelimesta työasemaan katkeaa. Tällöin kutsu- tai vastausviestin aittu saaja ei saa viestiä, mutta myöskään viestin lähettäjä ei saa tieta välityksen epännistumisesta. 5.2 Timinta teknisestä näkökulmasta Tässä käyttötapauksessa Vetuma-palvelu timii tunnistuslähteen hakupalveluna (SAMLstandardin käsitemaailmassa Discvery Service), ja Ankkalinnan verkkpalvelu timii palveluntarjajana (SAML-standardin käsitemaailmassa Service Prvider). Teknisesti tunnistuslähteen hakeminen timii seuraavasti: 1. Käyttäjän pyytäessä Ankkalinnan verkkpalvelulta etusivua, hänen selaimestaan lähtee verkkpalvelulle HTTP-kutsu jnka verkkpalvelu tulkitsee ja tteaa tarpeen selvittää käyttäjän käyttämä aktiivinen tunnistuslähde. 2. Verkkpalvelu lähettää SAML-tunnistuslähteen selvityspyynnön käyttäjän selaimen kautta Vetumalle. Tarkemmin sanen verkkpalvelu: Rakentaa SAML-standardin mukaisen tunnistuslähdekyselyn sisältävän URL:n parametreineen, jssa pyytää Vetumaa selvittämään aktiivisen tunnistuslähteen. Lähettää pyynnön Vetumalle hjaamalla käyttäjän selaimen siirtymään mudstettuun sitteeseen (HTTP GET). 3. Vetuma vastaanttaa tunnistuslähdepyynnön HTTP GET-kutsuna. Vetuma tulkitsee kutsussa annetut määräykset tunnistuslähde selvityksen surittamiselle, sekä käy käyttäjän selaimen kanssa keskustelun aktiivisen käyttäjäistunnn selvittämiseksi. Vetuma tteaa että käyttäjä n 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 verkkpalvelulle. Tarkemmin sanen Vetuma: Rakentaa SAML-standardin mukaisen URL:n parametreineen ja laittaa siihen tiedksi käyttäjän käyttämän tunnistuspalvelun tunnisteen mikäli tunnistuslähde n llut käytössä. Mikäli tunnistuslähde ei selvinnyt tai tapahtui muu virhe, jätetään kyseinen parametri pis vastauksesta. Lähettää pyynnön Ankkalinnan verkkpalvelulle hjaamalla käyttäjän selaimen siirtymään mudstettuun sitteeseen (HTTP GET). 5. Ankkalinnan verkkpalvelulle tteaa saamastaan SAML- tunnistuslähdevastauksesta tunnistuslähdehaun nnistuneeksi ja pimii vastauksesta tiedn, että käyttäjä n käyttänyt Vetuma-palvelua. Mikäli kyseinen tiet puuttui vastauksesta, tulkitsee verkkpalvelu kyselyn epännistuneeksi. Cpyright Fujitsu Finland Oy 16 (17)
Versi: 3.4 14.1.2015 6. Ankkalinnan verkkpalvelulle hjaa käyttäjän eteenpäin tunnistautumaan Vetumapalveluun. Eteneminen jatkuu aikaisempien tunnistuksen käyttötapausten mukaisesti. K ä ytt ä j ä n selain Ankkalinnan verkkpalvelu VETUMA 1. Kutsu jlla pyydet ää n etusivua 2. SAML tunnistuslähteen hakukutsu 3. Tunnistuslähteen selvitys 4. SAML tunnistuslähdevastaus 6. Vastaus jlla hjataan eteenpäin selvitettyyn tunnistuspalveluun 5. Saa tiedn tunnistuslähteestä K ä ytt ö jatkuu tunnistuksella Kuva 4: Tunnistuslähteen hakeminen Vetuman SAML-rajapinnan kautta Cpyright Fujitsu Finland Oy 17 (17)