Suomalaisen julkishallinnon Vetuma-palvelu Versio: 3.5 Vetuma Verkkotunnistus ja -maksaminen
Sisällysluettelo 1. Johdanto... 3 2. Vetuma-palvelun SAML-rajapinnan yleiset ominaisuudet... 3 2.1 Metadata... 3 2.1.1 Verkkopalvelun tunnus... 4 2.1.2 XML allekirjoituksissa käytettävä varmenne... 4 2.1.3 Kertakirjautumista hyödyntävä palvelu... 4 2.1.4 Kertakirjautumisen yhteydessä palautettavat käyttäjäattribuutit... 4 2.1.5 Kertauloskirjautumisen osoite... 4 2.1.6 Organisaation nimi näytettäväksi käyttöliittymässä... 4 2.1.7 Verkkopalvelun nimi näytettäväksi käyttöliittymässä... 5 2.1.8 Verkkopalvelun laskutustunnus tapahtumaraportointia varten... 5 2.2 SAML kutsu- ja vastausviestien välitys... 5 2.3 Parametrikäytännöt... 7 2.4 XML allekirjoituksen muodostaminen... 7 2.5 XML allekirjoitukset kutsu- ja vastausviesteissä... 8 3. Vetuman SAML-kertakirjautuminen... 8 3.1 Tunnistustapojen osoittaminen... 8 3.2 Tunnistuskutsun hyötykuormaparametrit... 9 3.3 Tunnistusvastauksen hyötykuormaparametrit... 11 4. Vetuman SAML-kertauloskirjautuminen... 16 4.1 Uloskirjauskutsun hyötykuormaparametrit... 16 4.2 Uloskirjausvastauksen hyötykuormaparametrit... 18 5. Vetuman SAML-tunnistuslähdekysely... 20 5.1 Tunnistuslähdekysely- ja vastausviestien välitys... 20 5.2 Tunnistuslähdekyselyn parametrit... 20 5.3 Tunnistuslähdevastauksen hyötykuormaparametrit... 22 6. Yleinen poikkeustilanteiden käsittely... 22 6.1 Vetuma-palvelun havaitsemat poikkeustilanteet... 22 6.1.1 Paluu sovellukseen poikkeustilanteissa... 23 6.1.2 Testiympäristön tuki kutsuvirheiden tutkimiselle... 23 6.2 Virhetilanteet kutsu- ja vastausviestien välityksessä... 23 6.2.1 Vetuma-istunnon vanhentuminen... 23 6.2.2 Toistuvat kutsut... 24 7. Liitteet ja viitteet... 24 7.1 Liitteet... 24 7.2 Viitteet... 24 Copyright Fujitsu Finland Oy 2 (25)
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 yhdistettynä SAML-kertakirjautumiseen tässä dokumentissa määritellyn SAML-kutsurajapinnan kautta. Tämä dokumentti kuvaa Vetuma-palvelun version 3.5 SAML-rajapinnan. Dokumentti täydentää ja kuvaa Vetuma-pavelun toimintoja varsinaisen SAML 2.0 määrityksen lisänä. Sanomien muoto, XML-allekirjoitukset ja tarkistukset tulee perustua SAML 2.0 määrityksiin. Vetumapalvelun SAML rajapinta on tarkoitettu yhteensopivaksi Julkishallinnon SAML 2.0 protocol deployment ja attribuutti profiilien kanssa, viite [FinnishSAML2Profile]. SAML-rajapintaa voi käyttää ainoastaan tunnistamiseen. Maksamispalvelu, allekirjoituspalvelu ja hyväksyntäpalvelu ovat käytettävissä ainoastaan Vetuman oman kutsurajapinnan kautta. Vetuma-palvelun SAML-rajapinta tarjoaa kertakirjautumistoiminnallisuuden Vetuma-palveluun SAML-rajapinnalla liittyneiden palveluiden kesken. 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. Versio 3.5 ei sisällä muutoksia SAML-rajapintaan. 2. VETUMA-PALVELUN SAML-RAJAPINNAN YLEISET OMINAISUUDET 2.1 Metadata Tässä luvussa kuvataan Vetuma-palvelussa tarjottavan SAML-rajapinnan yleiset ominaisuudet: kutsu- ja vastausviestien välitys, parametrikäytännöt, sekä viestien XML-allekirjoitukset. Vetuma SAML-rajapinta tarjoaa asiointisovelluksille käyttäjän tunnistamisen käyttämällä Vetuma-rajapinnan vahvoja tunnistustapoja. Vetuma-tunnistusta käyttävälle verkkopalvelulle tarjotaan aina Tupas, kansalaisvarmenteeseen ja mobiilivarmenteeseen perustuvat menetelmät. Nämä toiminnot on kuvattu dokumentissa Suomalaisen julkishallinnon Vetuma-palvelu, sovelluksille tarjotun toiminnallisuuden kuvaus. Tässä luvussa kuvataan näiden toimintojen kutsut ja vastaukset parametreineen SAML-rajapinnan kautta. Asiointisovelluksien liittyessä käyttämään Vetuma-palvelun SAML-rajapintaa, he toimittavat oman palvelunsa SAML rajapinnan kuvaavan metadata-tiedoston. Metadata-tiedoston tulee noudattaa SAML 2.0 määrityksiä. Ohje tiedoston vaatimuksista toimitetaan liittymisen yhteydessä. Copyright Fujitsu Finland Oy 3 (25)
Tässä dokumentissa on kuvattu tarvittavat tiedot, tarkempi kuvaus esimerkkeineen on erillisessä dokumentissa: Vetuma-palvelun SAML-kutsurajapinnan metadata-tiedosto.pdf 2.1.1 Verkkopalvelun tunnus Verkkopalvelun tunnus on asiointisovelluksen SAML palvelun yksilöllinen tunniste. Tunnus on verkkopalvelun SAML rajapinnan kuvaavan metadata-tiedoston entityid-attribuutin arvo. Kyseinen tunnus annetaan tunnistuskutsussa <Issuer> -elementissä viittaamaan kutsuvan verkkopalvelun konfiguraatiotietoihin (metatietoihin). 2.1.2 XML allekirjoituksissa käytettävä varmenne Metadatan KeyDescriptor-elementti määrää sen julkisen avaimen varmenteen, jota vastaavalla yksityisellä avaimella verkkopalvelu allekirjoittaa Vetuma-palvelulle lähettämäänsä sanoman. Vetuma-palvelu edellyttää, että kaikissa metadata-tiedostoissa on mukana varmenne X509Certificate-elementissä. Vetuma-palvelun metadatatiedostoon voi määritellä samanaikaisesti useamman varmenteen yhdelle verkkopalvelulle. Verkkopalvelu voi tarvittaessa toimittaa Vetuma-palvelun käyttöön väliaikaisen useamman varmenteen sisältävän metadatan. Esitysmuoto on määritelty SAML-standardissa (metadatamäärittelyn kohdassa 2.4.1.1). Tarkemmat vaatimukset metadatalle löytyy dokumentista Vetuma-palvelun SAMLkutsurajapinnan metadata-tiedosto. 2.1.3 Kertakirjautumista hyödyntävä palvelu Metatiedoissa määritetään kertakirjautumista käyttävän palvelun paluuosoitteet, indeksit ja käytetyt SAML-yhteystyypit. Indeksiä voidaan käyttää SAML-protokollaviestissä valitsemaan tietty paluuosoite. Vetuman versiosta 3.4 lähtien käytetyn yhteystyypin arvon on aina oltava: urn:oasis:names:tc:saml:2.0:bindings:http-post. 2.1.4 Kertakirjautumisen yhteydessä palautettavat käyttäjäattribuutit Metatiedoissa voidaan määritellä tunnistuksen yhteydessä palautettavia attribuutteja hyödyntävät palvelut ja indeksit ja pyydetyt käyttäjäattribuutit. Indeksiä voidaan käyttää SAML-protokollaviestissä valitsemaan tietty attribuuttijoukko. Käytettävissä olevat attribuutit on määritelty kappaleessa Tunnistusvastauksen hyötykuormaparametrit. 2.1.5 Kertauloskirjautumisen osoite Metatiedoissa määritetään kertauloskirjautumista käyttävän palvelun paluuosoite ja käytetty SAML-yhteystyyppi. Paluuosoitteella kuvataan sitä osoitetta, johon Vetuma lähettää kertauloskirjautumisessa palvelua koskevat uloskirjautumispyynnöt tai uloskirjautumisvastaukset. Vetuman versiosta 3.4 lähtien käytetyn yhteystyypin arvon on oltava: urn:oasis:names:tc:saml:2.0:bindings:http-redirect tai urn:oasis:names:tc:saml:2.0:bindings:http-post. 2.1.6 Organisaation nimi näytettäväksi käyttöliittymässä Metatietojen toimituksen yhteydessä organisaatio nimi talletetaan Vetuma-palveluun. Organisaation nimi voidaan antaa kaikilla niillä kielillä, jotka ovat tuettuina Vetumassa. Vetuma käyttää nimestä sitä kieliversiota joka vastaa tunnistuskutsussa annettavaa käyttöliittymän kielivalintaa. Copyright Fujitsu Finland Oy 4 (25)
2.1.7 Verkkopalvelun nimi näytettäväksi käyttöliittymässä Metatiedoissa verkkopalvelun nimi voidaan antaa kaikilla niillä kielillä, jotka ovat tuettuina Vetumassa. Vetuma käyttää nimestä sitä kieliversiota joka vastaa tunnistuskutsussa annettavaa käyttöliittymän kielivalintaa. Mikäli metatiedossa konfiguroitu arvo on liian pitkä mahtuakseen Vetuman käyttöliittymään, niin se katkaistaan Vetumassa sallittuun pituuteen. Tarkempi kuvaus on erillisessä metatietodokumentissa. Mikäli verkkopalvelun nimeä ei haluta näytettäväksi käyttöliittymässä, jätetään tämä tieto pois verkkopalvelun metatiedoista. Erona Vetuma-palvelun omaan rajapintaan on, että siellä puolella verkkopalvelun nimi annetaan parametrilla APPNAME. 2.1.8 Verkkopalvelun laskutustunnus tapahtumaraportointia varten Metatiedoissa voidaan antaa laskutustunnus tapahtumaraportointi varten. Mikäli metatiedossa konfiguroitu arvo on liian pitkä, niin se katkaistaan Vetuma-rajapinnassa sallittuun pituuteen. Tarkempi kuvaus on erillisessä metatietodokumentissa. Mikäli laskutustunnusta ei haluta tapahtumaraporttiin, jätetään tämä tieto pois verkkopalvelun metatiedoista. Erona Vetuman omaan rajapintaan on, että siellä puolella laskutustunnus annetaan tunnistuskutsun parametrilla APPID. 2.2 SAML kutsu- ja vastausviestien välitys Vetuma-palvelun SAML-rajapinta on viestirajapinta missä viestit on toteutettu käyttäen HTTPyhteyskäytännön Redirect- ja POST-komentoja. Mekanismi on sama, jota käytetään myös Vetuman omassa kutsurajapinnassa. Käytetty välitystapa on SAML 2.0 mukainen HTTP POST Binding tai HTTP Redirect Binding Viite 4 [SAMLBind]. Kun asiointisovellus kutsuu Vetuma-palvelua, se lähettää palvelulle käyttäjän selaimen kautta POST-komennon jossa Vetumalle on annettu HTML-lomakkeen kenttinä SAML-kutsu ja istuntotunnus. HTTP Redirect Binding yhteydessä HTTP GET kutsu on käytössä. Lisätietoja löytyy viitteestä 4. Sovellus voi Vetumalle SAML-kutsussa määrittää paluuosoitteen SAML-käytännön mukaisesti joko AssertionConsumerServiceIndex- tai AssertionConsumerServiceURLattribuutissa. Mikäli osoittetta ei anneta kutsussa, käytetään sovelluksen oletusosoitetta metadata-tiedostosta. Vetuma-palvelu palauttaa vastauksen paluuosoitteeseen seuraavissa tilanteissa: onnistunut toiminto, käyttäjän peruma toiminto, tai virhetilanne. Kun Vetuma-palvelu palauttaa vastauksen sitä kutsuneelle asiointisovellukselle, se lähettää sovellukselle jälleen käyttäjän selaimen kautta POST-komennon jossa Vetuma-palvelulta sovellukselle on annettu HTML-lomakkeen kenttinä SAML-vastaus ja istuntotunnus. Viestinvälityksen luottamuksellisuus (viestien sisällön suojaus paljastumista vastaan) perustuu käytettävien yhteyksien suojaukseen SSL/TLS-yhteyskäytännöllä, eli kutsu- ja vastausviestit välitetään HTTPS-yhteyksiä käyttäen. Ennen kuin sovellus palauttaa käyttäjän selaimelle sen HTTP-vastauksen jonka avulla Vetuma-kutsu lähetetään selaimesta Vetuma-palvelulle, sovelluksen tulee huolehtia siitä, että sen ja käyttäjän selaimen välillä on HTTPS-yhteys. Copyright Fujitsu Finland Oy 5 (25)
Kutsuosoite Vetuma-palveluun (joka on annettava Vetuma SAML-kutsun sisältävän lomakkeen action-elementissä) on https://-alkuinen, eli POST-komento lähetetään selaimesta Vetuma-palvelulle HTTPS-yhteyttä käyttäen. Vetuma-palvelun palauttaessa selaimelle HTTP-vastauksen jonka avulla Vetumavastaus lähetetään selaimesta sovellukselle tämä tapahtuu HTTPS-yhteyttä käyttäen. Vetuma-kutsussa ja metatiedoissa annettujen paluuosoitteiden on oltava https://- alkuisia, jotta ne aiheuttaisivat HTTPS-yhteyden muodostamisen vastauksen sisältävän POST-komennon lähettämiseksi selaimesta sovellukselle. Kutsun tapauksessa Vetumapalvelu tarkistaa, että näin on, ja jos ei ole niin se hylkää kutsun ja palauttaa metadatatiedoston oletusosoitteeseen virhevastauksen virheellinen kutsu (SAML tilakoodi Requester). Vastauksessa on mukana viesti, joka kuvaa miksi annettu osoite ei kelpaa. Vaihdettujen viestien eheys ja lähettäjän tunnistaminen taataan käyttämällä SAML viesteissä XML allekirjoituksia (XML -Signature). Vetuma palvelu hyväksyy palveluntarjoajien varmentajina seuraavat CA:t: VRK, VeriSign, Thawte ja Symantec. Viestien vastaanottajan on tarkistettava viestissä mukana olevat allekirjoitukset ja hylättävä kutsu mikäli allekirjoitukset eivät täsmää. Sovellus voi halutessaan antaa Vetuma-kutsulle tapahtumatunnuksen, jonka Vetuma-palvelu palauttaa vastatessaan kyseiseen kutsuun. Tapahtumatunnus on tarkoitettu helpottamaan tietyn tapahtuman kutsu- ja vastausviestien yhdistämistä toisiinsa. Sovelluksen on itse huolehdittava tapahtumatunnuksen eheydestä käyttämällä apuna esimerkiksi tarkistussummaa. Maksimipituus tapahtumatunnukselle on 80 tavua. Tapahtumatunnus välitetään lomakkeessa RelayStatenimisessä kentässä. Asiointisovellus voi lähettää kutsun Vetuma-palvelulle käyttäjän selaimen kautta esimerkiksi palauttamalla selaimelle HTML-sivun jossa on:... HTML-lomake jossa on Vetuma SAML-kutsuparametrit esitäytettyinä, käyttäjälle näkymättöminä piilokenttinä. <form name= VETUMA method= POST action=https://tunnistus.suomi.fi/vetumasso/app > <input type= hidden name= SAMLRequest value= xdsdd... > <input type= hidden name= RelayState value= 1234567890 >... </form>... Automaattisesti suoritettava skripti joka lähettää lomakkeen Vetuma-palvelulle, esimerkiksi: var form = document.vetuma; form.submit(); Käsikäyttöinen submit-toiminto lomakkeessa Vetuma-palveluun siirtymiseksi, mikäli skriptien suorittaminen on estetty selaimessa, esimerkiksi <INPUT type="submit" value="siirry Vetuma-palveluun tunnistautumaan"> Kun Vetuma-palvelu käsittelee sovellukselta saamaansa tunnistuskutsua, niin tunnistus voi onnistua tai se voi jäädä eri syistä suorittamatta. Vetuma palauttaa SAML- Copyright Fujitsu Finland Oy 6 (25)
2.3 Parametrikäytännöt tunnistusvastauksessaan tiedon siitä, onnistuiko tunnistaminen vai jäikö se jostain syystä suorittamatta. Vetumalle SAML-rajapinnan kautta lähetettävä tunnistuspyyntö annetaan SAML-standardin mukaisessa tunnistuskutsussa (<AuthnRequest>). Valtaosa tunnistustapahtuman ohjaustiedoista määrätään verkkopalvelun konfiguraatiossa, joihin viitataan tunnistuskutsussa. Verkkopalvelu voi kuitenkin tunnistuskutsussa määrätä mitä kieltä Vetuman tulee käyttää tunnistuskäyttöliittymässään. Vetuma-tunnistusta käyttävä sovellus saa tunnistuksesta tunnistautuneen käyttäjän henkilöllisyyden lisäksi määrättyjä lisätietoja käyttäjästä sekä tunnistustapahtumasta: esimerkiksi käyttäjän nimitiedot, Väestötietojärjestelmästä (VTJ) haettava henkilötunnus tai konfiguroidun VTJ-kyselytuotteen mukaiset käyttäjän perustiedot, sekä tiedon käytetystä tunnistustavasta. Vetuma-kohtaiset lisätiedot tunnistautuneesta henkilöstä ja tunnistustapahtumasta annetaan SAML-tunnistusvastauksen (tunnistuksessa käytettävä <Response>) sekä sen sisältämien selosteiden (<Assertion>) asianmukaisissa elementeissä. Vetuma-kohtaisen hyötykuormatiedon välittäminen SAML-standarin mukaisissa tunnistuskutsuissa ja -vastauksissa on kuvattu myöhemmin tässä dokumentissa, omissa luvuissaan. Vetuman SAML-rajapinnassa käytetään UTF-8 merkistöä. Sovelluksen kannalta tämä tarkoittaa muun muassa sitä, että Vetuma-kutsujen parametrien arvoissa saa esiintyä vain UTF-8 merkistön merkkejä. 2.4 XML allekirjoituksen muodostaminen Vetuma-palvelussa käytettyjen SAML viestien XML-allekirjoitukset muodostetaan [SAML 2.0- standardin] mukaisesti käyttäen allekirjoitusalgoritmia RSAwithSHA256. Tuetaan myös aikaisempaa algoritmia RSAwithSHA1). Vetuma tukee seuraavia XML-allekirjoitusstandardin optioita: Digest SHA256 SHA1 Signature RSAwithSHA256 RSAwithSHA1 XML Canonicalization Transform KeyInfo Exclusive Canonicalization (with or without comments) Enveloped Signature <ds:keyinfo><ds:x509data><ds:x509certificate> Taulukko 1: Yhteenveto Vetuma-palvelussa tuetuista XML-allekirjoitusstandardin optioista Vetuma-palvelua kutsuvan asiointisovelluksen tulee muodostaa kutsuviestin XML-allekirjoitus SAML 2.0-standardin mukaisesti. Vetuma-palvelu muodostaa vastausviestin XML allekirjoituksen samalla tavalla. Vetuma-palvelua kutsuvan asiointisovelluksen tulee tarkastaa saamansa allekirjoitukset. Palveluntarjoajien XML allekirjoituksissa käyttämät varmenteet rekisteröidään liittymisen yhteydessä. Vetuma-palvelu hyväksyy palveluntarjoajien Copyright Fujitsu Finland Oy 7 (25)
varmentajina seuraavat CA:t: VRK, VeriSign, Thawte ja Symantec. Huomaa, että uusissa varmenteissa tulisi jatkossa käyttää SHA-256 algoritmia SHA-1 algoritmin sijasta. 2.5 XML allekirjoitukset kutsu- ja vastausviesteissä Kaikissa Vetuma-palvelussa käytetyissä SAML kutsu- ja vastausviesteissä on XMLallekirjoitus tai allekirjoitus. Vastaanottajan tulee tarkistaa allekirjoitus ja varmistua, että se allekirjoittaa jokaisen sanoman juurielementin SAML 2.0 määrityksen mukaisesti. Tunnitusvastauksen tapauksessa (<Response>) on tarkistettava lisäksi sanoman mukana palautettavan selosteen (<Assertion>) allekirjoitus. Liitteestä 3 löytyy SAML sanomaesimerkit dokumentti, joissa on esitetty allekirjoitukset sisältävät sanomat. 3. VETUMAN SAML-KERTAKIRJAUTUMINEN Vetuma kertakirjautuminen tarkoittaa sitä, että kertakirjautuminen toimii Vetuma-palveluun SAML-rajapinnan kautta liittyneiden palveluntarjoajien kesken. Kertakirjautuminen toteutetaan käyttäen SAML-kertakirjautumisprofiilia Web Browser SSO Profile. Kertakirjautumisessa käytettään Vetuma:n SAML-tunnistuskutsu ja Vetuma:n SAML-tunnistusvastauksia. Alla on yhteenveto siitä mitä Web Browser SSO Profile:lle standardissa määriteltyjä kutsuja/vastauksia ja sidoksia (bindings) Vetuman versiossa 3.5 tuetaan. Profiili Sanomat Sidos (Binding) Versio 3.5 Web SSO <AuthnRequest>-sanoman vastaanottaminen HTTP redirect HTTP POST Tuettu Tuettu HTTP artifact Ei tuettu <Response>-sanoman lähetys HTTP POST Tuettu HTTP artifact Ei tuettu Taulukko 2: Yhteenveto Vetuma-palvelussa tuetuista Web Browser SSO Profile:n sanomista ja sidoksista Vetuma-palvelua kutsuvalle verkkopalvelulle kertakirjautuminen tarkoittaa sitä, että käyttäjän näkemä palvelu Vetuma:ssa vaihtelee sen mukaan onko hän jo samalla selaimella tunnistautunut Vetuma:ssa ja tullut sinne sellaisen verkkopalvelun kautta, joka kutsui Vetuma-palvelua SAMLrajapinnalla. Mikäli on ja istunto on vielä voimassa, käyttäjän ei enää tarvitse tunnistautua uudestaan. Kertakirjautumisistunnon maksimikesto viimeisestä istuntoon liittymisestä on 30 minuuttia. Ensimmäisen tunnistuksen yhteydessä käyttäjästä saadaan tietoon henkilötunnus ja nimi. Nämä tiedot tallentuvat kertakirjautumisistuntoon seuraavia verkkopalveluita varten. Istuntoon seuraavaksi liittyvät muut verkkopalvelut saavat nämä tiedot ilman käyttäjän uutta tunnistamista. 3.1 Tunnistustapojen osoittaminen Vetuma-palvelu tarjoaa joukon vaihtoehtoisia tapoja käyttäjän tunnistamiseen. Nämä tunnistustavat (tunnistusmenetelmät) on kuvattu dokumentissa Suomalaisen julkishallinnon Vetuma-palvelu, sovelluksille tarjotun toiminnallisuuden kuvaus. Menetelmien tunnukset sekä kunkin tunnistustavan yhteydessä palautettava käyttäjän tunnisteen tietotyyppi on esitetty allaolevassa taulukossa. Kaikissa tunnistustavoissa sovellus saa käyttäjän tunnisteena myös Copyright Fujitsu Finland Oy 8 (25)
HETU:n. Menetelmä AuthnContextClassRef Käyttäjän henkilöllisyyden osoittamisessa käytettävä tietotyyppi Vahva tunnistus kuten määritelty (laki vahvasta sähköisestä tunnistamisesta ja sähköisestä allekirjoituksesta, 7.8.2009/617) Sirukorttipohjainen kansalaisvarmennetunnistus (HST-tunnistus) SIMkorttipohjainen mobiilivarmennetunnistus (ETSI) Tupas-tunnistus Taulukko 3: Vetumassa tuetut menetelmät http://www.valtiokonttori.fi /vip/authncontext/strong http://www.valtiokonttori.fi /vip/authncontext/strong http://www.valtiokonttori.fi /vip/authncontext/strong SATU HETU HETU Vetuma-palvelun käyttämät pankit on esitetty Vetuma-rajapinnan kutsurajapinnan määrittelyssä. Esimerkkejä valitun tunnistustavan palauttamisesta vastauksessa: http://www.valtiokonttori.fi/vip/authncontext/strong (Tunnistus suoritettiin vahvan tunnistuksen menetelmällä) 3.2 Tunnistuskutsun hyötykuormaparametrit SAML-tunnistuskutsun (<AuthnRequest>) rakenne on määritelty [SAML 2.0-standardissa]. Tässä luvussa on kuvattu, miten SAML-tunnistuskutsulla voidaan ohjata Vetumaa tunnistustapahtuman suorittamisessa. Pyydettäessä tunnistusta Vetuman SAML-rajapinnan kautta annetaan SAML-tunnistuskutsussa (<AuthnRequest>) seuraavat tunnistusta ohjaavat hyötykuormatiedot. Sarakkeessa P on kerrottu onko parametri pakollinen vai valinnainen. Tieto P Vastaava tieto vanhassa kutsurajapinnassa Kutsun aikaleima p TIMESTMP Käyttöliittymäkieli v LG Paluuosoite v RETURL CANURL ERRURL Tapahtumatunnus v TRID Taulukko 4: Vetuman SAML-tunnistuskutsun hyötykuormaparametrit Copyright Fujitsu Finland Oy 9 (25)
Verkkopalvelun tunnus Merkitys tunnistuskutsussa: Vetuma-palvelua kutsuvan verkkopalvelun tunnus, viittauksena verkkopalvelun konfiguraatiotietoihin Vetumassa. Issuer-elementin arvo on oltava sama kuin toimitetun metadatan EntityID-attribuutin arvo. Sijainti tunnistuskutsussa: <AuthnRequest>-elementin elementin <saml:issuer> arvo Esitysmuoto: URL-syntaksin mukainen merkkijono, maksimipituus 1024 merkkiä. Tyyppi: Pakollinen Esimerkki: https://www.example.org/app1 Vastaava tieto vanhassa kutsurajapinnassa APPID Kutsun aikaleima Merkitys tunnistuskutsussa: Määrittää sen hetken, jolloin kutsu luotiin. Sijainti tunnistuskutsussa: <AuthnRequest>-elementin attribuutti IssueInstant Esitysmuoto: Merkkijono, 24 merkkiä. Tyyppiä xs:datetime W3C XML Schema datatyyppimäärityksen mukainen [Schema2] UTC muodossa ilman aikavyöhykettä Tyyppi: Pakollinen Esimerkki: 2008-03-28T12:44:47.693Z Vastaava tieto vanhassa kutsurajapinnassa TIMESTMP Käyttöliittymäkieli Merkitys tunnistuskutsussa: Käyttäjälle avattavan tunnistuskäyttöliittymän kieli. Kutsuessaan Vetumaa sovellus voi määrätä, mitä tuettua kieltä Vetuman käyttöliittymän tulee käyttää. Määräys koskee selainkäyttöliittymää. Vetuma tarjoaa suomen-, ruotsin- ja englanninkielisen käyttöliittymän. Vetuma-palvelu pyrkii välittämään kielivalinnan myös kutsumilleen taustapalveluille. Eräissä tapauksissa Vetuma-palvelu ei kuitenkaan voi vaikuttaa kutsumansa taustapalvelun käyttämään käyttöliittymäkieleen, esimerkiksi: o o Tiettyjen pankkien verkkopalveluissa kieli määrätään kansalaisen pankin kanssa tekemässä verkkopalvelusopimuksessa. Vastaavasti tietyillä mobiilivarmenteen sisältävillä SIM-korteilla ei tueta kielivalintaa tai ei tueta kaikkia Vetuma-palvelussa tuettuja kieliä. Sijainti tunnistuskutsussa: <samlp:extensions>-elementin <vetuma xmlns="urn:vetuma:saml:2.0:extensions">-elementin elementin <LG> arvo Esitysmuoto: Merkkijono, 2 merkkiä ISO 639-1-standardin mukainen 2-kirjaiminen kielikoodi pienillä kirjaimilla. Siis joko fi, sv tai en Tyyppi: Valinnainen Esimerkki: fi Copyright Fujitsu Finland Oy 10 (25)
Esimerkki käytöstä: <samlp:extensions><vetuma xmlns="urn:vetuma:saml:2.0:extensions"><lg>fi</lg></vetuma></sam lp:extensions> Paluuosoite Merkitys tunnistuskutsussa: Paluuosoite sovellukseen tunnistuskutsun käsittelyn jälkeen. Sijainti tunnistuskutsussa: <AuthnRequest>-elementin attribuutti AssertionConsumerServiceURL tai viittaus Metadata-tiedoston osoitteeseen attribuutilla AssertionConsumerServiceIndex. Esitysmuoto: AssertionConsumerServiceURL: Tyyppiä xs:anyuri W3C XML Schema datatyyppimäärityksen mukainen [Schema2] AssertionConsumerServiceIndex: Metadata-tiedoston AssertionConsumerService-elementtiin viittaava indeksi. AssertionConsumerServiceURL:n domain-osa täytyy olla sama kuin toimitetussa metadatassa. Tyyppi: Valinnainen Esimerkki: AssertionConsumerServiceURL= https://www.ankkalinna.fi/portaali/paluu tai AssertionConsumerServiceIndex= 1 Tapahtumatunnus Merkitys tunnistuskutsussa: Mahdollistaa Vetuma-palvelua kutsuvan sovelluksen säilyttää tilatietoa ja saada se takaisin vastauksessa. Sijainti tunnistuskutsussa: Tunnistuskutsun sisältävässä lomakkeessa erillinen RelayState -kenttä. Esitysmuoto: Max 80 tavua Mikäli kutsuva sovellus käyttää tapahtumatunnusta, on sen itse huolehdittava kentän eheydestä esimerkiksi käyttämällä sopivaa tarkistussummaa. Tyyppi: Valinnainen 3.3 Tunnistusvastauksen hyötykuormaparametrit SAML-vastauksen (<Response>) rakenne sekä sen käyttö tunnistusvastauksissa on määritelty [SAML 2.0-standardissa]. Kyseisessä standardissa määritellään myös tunnistusvastauksissa palautettavien selosteiden (<Assertion>) rakenne. Tässä luvussa on kuvattu, miten Vetuma palauttaa sille ominaiset hyötykuormatiedot tunnistustapahtumasta ja tunnistetusta henkilöstä. Vetuma palauttaa SAML-rajapinnan tunnistusvastauksessa (<Response>) seuraavat tiedot tunnistetusta henkilöstä ja tunnistustapahtumasta: Copyright Fujitsu Finland Oy 11 (25)
Tieto P Vastaava tieto vanhassa kutsurajapinnassa Vastauksen aikaleima p TIMESTMP Tunnistustapa p SO Tapahtumatunnus v TRID Henkilöllisyys p USERID, SUBJECTDATA, VTJDATA, EXTRADATA Tunnistuspalvelun tarjoaja p SO Paluustatus p STATUS Taulukko 5: Vetuman SAML-tunnistusvastauksen hyötykuormaparametrit Vastauksen aikaleima Merkitys tunnistusvastauksessa: Määrittää sen hetken, jolloin vastaus luotiin. Sijainti tunnistusvastauksessa: <Response>-elementin attribuutti IssueInstant Esitysmuoto: Merkkijono, 24 merkkiä. Tyyppiä xs:datetime W3C XML Schema datatyyppimäärityksen mukainen [Schema2] UTC muodossa ilman aikavyöhykettä Esimerkki: 2008-03-28T12:50:47.693Z Tunnistustapa Merkitys tunnistusvastauksessa: Se tunnistustapa, jolla käyttäjä tunnistautui. Sijainti tunnistusvastauksessa: <saml:authnstatement>-elementin <saml:authncontext>elementin elementti <saml:authncontextclassref> Esitysmuoto: Käytetään kohdan 3.1 esittämiä tunnistustapakoodeja XML-rakenteessa. Vetumassa käytettävät tunnistustapojen koodit on kuvattu aiemmin tässä dokumentissa, luvussa: Tunnistustapojen osoittaminen. Esimerkkejä: <saml:authncontextclassref>urn:oasis:names:tc:saml:2.0:ac:classes:mobiletwofactorcont ract</saml:authncontextclassref> (Tunnistus suoritettiin kansalaisvarmenteen sisältävällä sirukortilla) <saml:authncontextclassref> urn:oasis:names:tc:saml:2.0:ac:classes:textbasedchallengeresponse </saml:authncontextclassref> (Tunnistus suoritettiin Tupas-menetelmällä) Tapahtumatunnus Merkitys tunnistusvastauksessa: Mahdollistaa Vetuma-palvelua kutsuvan sovelluksen säilyttää tilatietoa ja saada se takaisin vastauksessa. Sijainti tunnistuskutsussa: Tunnistusvastauksen sisältävässä lomakkeessa erillinen RelayState -kenttä. Esitysmuoto: Max 80 tavua Copyright Fujitsu Finland Oy 12 (25)
Henkilöllisyys Palautetaan aina tunnisteena Vetuman istuntoa varten muodostama henkilöllisyyden tunniste, transient ID. Lisäksi palautetaan selosteessa ne tiedot jotka voidaan palauttaa (riippuen tunnistustavasta): SATU (jos tunnistautui kansalaisvarmenteeseen perustuvalla menetelmällä) HETU (jos tunnistautui kansalaisvarmenteeseen perustuvalla menetelmällä, niin suoritetaan VTJ-haku) VTJDATA (VTJ-kyselytuotteen mukaiset käyttäjän perustiedot jos käyttäjä tunnistautui ja kyselytuote konfiguroitu päälle) Nimitiedot tunnistuslähteestä Henkilöllisyyden tunniste Merkitys vastauksessa: Vetuman istuntoa varten muodostama henkilöllisyyden tunniste, jolla uloskirjaus suoritetaan. Sijainti tunnistusvastauksessa <Response>-elementin elementin <saml:nameid> arvo Esitysmuoto: Merkkijono, maksimipituus 1024 merkkiä. Tyyppi: Pakollinen Esimerkki: <saml:nameid Format="urn:oasis:names:tc:SAML:2.0:nameidformat:transient">_adc07330da05-da9a2bf5-be98-47ca-8405-01bba7f4 4321-c23c3c88609c</saml:NameID> SATU Merkitys vastauksessa: Käytetyn kansalaisvarmenteen sähköinen asiointitunnus. Sijainti tunnistusvastauksessa: Attribuutissa, jonka OID tunniste on 1.2.246.22 eli <AttributeStatement>-elementin urn:oid:1.2.246.22 nimisessä <Attribute>-elementissä Esitysmuoto: SATU-syntaksin mukainen merkkijono <Attribute>-elementin syntaksilla. Esimerkki: <saml:attribute FriendlyName="electronicIdentificationNumber" Name="urn:oid:1.2.246.22" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"> <saml:attributevalue>010101123c</saml:attributevalue> </saml:attribute> HETU Merkitys tunnistusvastauksessa: Tunnistetun käyttäjän henkilötunnus (HETU), kuitenkin: Ei mukana vastauksessa, mikäli valittu menetelmä perustui kansalaisvarmenteeseen ja VTJ-kysely ei ole käytössä. VTJ:n palauttama virhekoodi jos kysely epäonnistui. Sijainti tunnistusvastauksessa: Attribuutissa, jonka OID tunniste on 1.2.246.21, eli <AttributeStatement>-elementin urn:oid:1.2.246.21 nimisessä <Attribute>-elementissä Esitysmuoto: HETU-syntaksin mukainen merkkijono <Attribute>-elementin syntaksilla. Copyright Fujitsu Finland Oy 13 (25)
Esimerkki: <saml:attribute FriendlyName="nationalIdentificationNumber" Name="urn:oid:1.2.246.21" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"> <saml:attributevalue>010101-123n</saml:attributevalue> </saml:attribute> VTJDATA Merkitys tunnistusvastauksessa: Tunnistetun käyttäjän VTJ-kyselytuotteen mukaiset käyttäjän perustiedot (VTJDATA), kuitenkin: Mukana, mikäli VTJ-kyselytuote konfiguroitu päälle ja käyttäjä tunnistautui Ei mukana vastauksessa, mikäli käyttäjä hyödynsi kertakirjausistuntoa tai VTJ-kysely ei ole käytössä VTJ:n palauttama virhekoodi jos kysely epäonnistui Sijainti tunnistusvastauksessa: Attribuutissa, jonka nimi on urn:vetuma:saml:2.0:attributes:vtjdata, eli <AttributeStatement>-elementin urn:vetuma:saml:2.0:attributes:vtjdata nimisessä <Attribute>-elementissä Esitysmuoto: Merkkijono, pituus enintään 3000 merkkiä, <Attribute>-elementin syntaksilla. Esitysmuoto on sama XML-muoto kuin kuin VTJ SoSo-kyselyiden vastauksissa. XMLdata on kuitenkin Vetuman paluusanomassa URL encodattuna. Tietyn tietoluvan sisältämien VTJ-kyselytuotteiden vastaustiedot määritellään tietoluvan yhteydessä, ja kunkin tuotteen vastauksen tarkka esitysmuoto kuvataan XML Schema-määrittelynä. VRK on myös julkaissut XML Scheman jossa määritellään vastausten XML-schemoissa esiintyvät VTJ-tietojen tietotyypit. Esimerkki VTJDATA-parametrin arvosta löytyy dokumentista: Vetuma Sanomaesimerkit. Nimitiedot tunnistuslähteestä Merkitys tunnistusvastauksessa: Tunnistuslähteestä saadut käyttäjän nimitiedot (mikäli ne ovat saatavilla). Eri tunnistustavoissa nimitiedot saadaan seuraavista lähteistä: Tunnistustapa Kansalaisvarmenteeseen perustuvat tunnistustavat Tupas Mobiilivarmenne Nimitietojen lähde Tunnistetun käyttäjän varmenteen Subject-kentän sisältämät nimitiedot. Pankin asiakastietokannassa oleva asiakkaan nimi. Tunnistetun käyttäjän varmenteen Subject-kentän sisältämät nimitiedot. Taulukko 6: Nimitietojen lähde eri menetelmätyypeissä Sijainti tunnistusvastauksessa: Attribuutissa, jonka OID tunniste on 2.5.4.3, eli <AttributeStatement>-elementin urn:oid:2.5.4.3 nimisessä <Attribute>-elementissä Esitysmuoto: Henkilön koko nimi JHS 133 mukaisesti. Esimerkkejä: <saml:attribute FriendlyName="cn" Name="urn:oid:2.5.4.3" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"> Copyright Fujitsu Finland Oy 14 (25)
<saml:attributevalue>aallontie Armas Oskari</saml:AttributeValue> </saml:attribute> <saml:attribute FriendlyName="cn" Name="urn:oid:2.5.4.3" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"> <saml:attributevalue>sinisalo-koskinen Maija</saml:AttributeValue> </saml:attribute> Tunnistuspalvelun tarjoaja Merkitys tunnistusvastauksessa: URI mikä yksilöi käytetyn tunnistuspalvelun tarjoajan. Sijainti tunnistusvastauksessa: Attribuutissa, jonka OID tunniste on 1.3.6.1.4.1.31350.1.11, eli <AttributeStatement>-elementin urn:oid:1.3.6.1.4.1.31350.1.11 nimisessä <Attribute>elementissä Esitysmuoto: URI. Esimerkki: <saml:attribute FriendlyName="authenticationProvider" Name="urn:oid:1.3.6.1.4.1.31350.1.11" NameFormat="urn:oasis:names:tc:SAML:2.0:attrnameformat:uri"> <saml:attributevalue>https://kultaraha.osuuspankki.fi/cgi-bin/krcgi</saml:attributevalue> </saml:attribute> Paluustatus Merkitys tunnistusvastauksessa: Miten tunnistus onnistui. Kun Vetuma käsittelee sovellukselta saamaansa tunnistuskutsua, niin tunnistus voi onnistua tai se voi jäädä eri syistä suorittamatta. Vetuma palauttaa SAML-tunnistusvastauksessaan <StatusCode> -elementin, jolla kerrotaan onnistuiko tunnistus vai jäikö se jostain syystä suorittamatta Sijainti tunnistusvastauksessa: <Response>-elementin <Status>-elementti. Esitysmuoto: Vetuma voi palauttaa <Status>-elementin <StatusCode>-elementissä seuraavat paluustatukset, jotka on SAML 2.0-standarssa määritelty nimiavaruudessa urn:oasis:names:tc:saml:2.0:status: SAML 2.0-standardissa määritelty tilakoodi Ylemmän tason tilakoodit: Onnistuminen Copyright Fujitsu Finland Oy Vastaava paluustatus Vetuman vanhassa kutsurajapinnassa Success Tunnistus onnistui SUCCESSFUL Requester Virheellinen kutsu ERROR Responder Kutsun käsittely epäonnistui FAILURE VersionMismatch Kutsussa virheellinen versio ERROR Täydentäviä tilakoodeja: AuthnFailed Tunnistus epäonnistui CANCELLED, FAILURE 15 (25)
RequestDenied Tunnistuslähde hylkäsi tunnistuksen REJECTED Taulukko 7: Vetuman palauttamat paluustatukset Status-elementissä saattaa olla mukana <StatusMessage>-elementti jossa annetaan tarkentavaa tietoa virhetilanteesta. 4. VETUMAN SAML-KERTAULOSKIRJAUTUMINEN Vetuma-palvelua SAML-rajapinnalla käyttävän sovelluksen on tuettava SAMLkertauloskirjautumista (Single Logout Profile) HTTP POST Binding kautta. Toiminnallisuuksista vaaditaan sekä Vetuma uloskirjauksen aloittamisen (palvelun tarjottava käyttäjälle uloskirjautumismahdollisuus), että Vetuma:sta tulevien uloskirjauskutsujen käsittely ja niihin vastaaminen. Alla on yhteenveto siitä mitä Single Logout Profile:lle standardissa määriteltyjä kutsuja/vastauksia ja sidoksia (bindings) Vetuman versiossa 3.5 tuetaan. Profiili Sanomat Sidos (Binding) Versio 3.5 Single Logout <LogoutRequest>-sanoman lähetys ja vastaanottaminen HTTP redirect HTTP POST Tuettu Tuettu HTTP artifact Ei tuettu SOAP Ei tuettu <LogoutResponse>-sanoman lähetys ja vastaanottaminen HTTP redirect HTTP POST Tuettu Tuettu HTTP artifact Ei tuettu SOAP Ei tuettu Taulukko 8: Yhteenveto Vetuma-palvelussa tuetuista Single Logout Profile:n sanomista ja sidoksista 4.1 Uloskirjauskutsun hyötykuormaparametrit SAML-uloskirjauskutsun (<LogoutRequest>) rakenne on määritelty [SAML 2.0- standardissa]. Tässä luvussa on kuvattu, miten SAML-uloskirjauskutsulla voidaan ohjata Vetumaa uloskirjauksen suorittamisessa. Pyydettäessä uloskirjausta Vetuman SAML-rajapinnan kautta annetaan SAMLuloskirjauskutsussa (<LogoutRequest>) seuraavat uloskirjausta ohjaavat hyötykuormatiedot. Vetuman lähettämä uloskirjauskutsu noudattaa samaa rakennetta. Sarakkeessa P on kerrottu onko parametri pakollinen vai valinnainen. Copyright Fujitsu Finland Oy 16 (25)
Tieto Kutsun aikaleima Henkilöllisyyden tunniste Käyttöliittymäkieli Tapahtumatunnus P p p v v Taulukko 9: Vetuman SAML-uloskirjauskutsun hyötykuormaparametrit Verkkopalvelun tunnus Merkitys uloskirjauskutsussa: Vetuma-palvelua kutsuvan verkkopalvelun tunnus, viittauksena verkkopalvelun konfiguraatiotietoihin Vetumassa. Sijainti uloskirjauskutsussa: <LogoutRequest>-elementin elementin <saml:issuer> arvo Esitysmuoto: URL-syntaksin mukainen merkkijono, maksimipituus 1024 merkkiä. Tyyppi: Pakollinen Esimerkki: https://www.example.org/app1 Kutsun aikaleima Merkitys uloskirjauskutsussa: Määrittää sen hetken, jolloin kutsu luotiin. Sijainti uloskirjauskutsussa: <LogoutRequest>-elementin attribuutti IssueInstant Esitysmuoto: Merkkijono, 24 merkkiä. Tyyppiä xs:datetime W3C XML Schema datatyyppimäärityksen mukainen [Schema2] UTC muodossa ilman aikavyöhykettä Tyyppi: Pakollinen Esimerkki: 2008-03-28T12:44:47.693Z Henkilöllisyyden tunniste Merkitys uloskirjauskutsussa: Vetuman tunnistusvastauksessa palauttama henkilöllisyyden tunniste tietyssä kertakirjautumistunnossa (transient ID). Sijainti uloskirjauskutsussa: <LogoutRequest>-elementin elementin <saml:nameid> arvo Esitysmuoto: Merkkijono, maksimipituus 1024 merkkiä. Tyyppi: Pakollinen Esimerkki: <saml:nameid Format="urn:oasis:names:tc:SAML:2.0:nameidformat:transient">_adc07330da05-da9a2bf5-be98-47ca-8405-01bba7f4 4321-c23c3c88609c</saml:NameID> Copyright Fujitsu Finland Oy 17 (25)
Käyttöliittymäkieli Merkitys uloskirjauskutsussa: Käyttäjälle avattavan uloskirjauskäyttöliittymän kieli. Kutsuessaan Vetumaa sovellus voi määrätä, mitä tuettua kieltä Vetuman käyttöliittymän tulee käyttää. Määräys koskee selainkäyttöliittymää. Vetuma tarjoaa suomen-, ruotsin- ja englanninkielisen käyttöliittymän. Vetuma-palvelu pyrkii välittämään kielivalinnan myös kutsumilleen taustapalveluille ja se lisätään myös Vetuman lähettämiin uloskirjauskutsuihin. Eräissä tapauksissa Vetuma-palvelu ei kuitenkaan voi vaikuttaa kutsumansa taustapalvelun käyttämään käyttöliittymäkieleen. Sijainti uloskirjauskutsussa: <samlp:extensions>-elementin <vetuma xmlns="urn:vetuma:saml:2.0:extensions">-elementin elementin <LG> arvo Esitysmuoto: Merkkijono, 2 merkkiä ISO 639-1-standardin mukainen 2-kirjaiminen kielikoodi pienillä kirjaimilla. Siis joko fi, sv tai en Tyyppi: Valinnainen Esimerkki: fi Esimerkki käytöstä: <samlp:extensions><vetuma xmlns="urn:vetuma:saml:2.0:extensions"><lg>fi</lg></vetuma></sam lp:extensions> Tapahtumatunnus Merkitys uloskirjauskutsussa: Mahdollistaa Vetuma-palvelua kutsuvan sovelluksen säilyttää tilatietoa ja saada se takaisin vastauksessa. Sijainti uloskirjauskutsussa: Uloskirjauskutsun sisältävässä lomakkeessa erillinen RelayState -kenttä. Esitysmuoto: Max 80 tavua Mikäli kutsuva sovellus käyttää tapahtumatunnusta, on sen itse huolehdittava kentän eheydestä esimerkiksi käyttämällä sopivaa tarkistussummaa. Tyyppi: Valinnainen 4.2 Uloskirjausvastauksen hyötykuormaparametrit SAML-uloskirjausvastauksen (<LogoutResponse>) rakenne sekä sen käyttö uloskirjausvastauksissa on määritelty [SAML 2.0-standardissa]. Tässä luvussa on kuvattu, miten Vetuma palauttaa sille ominaiset hyötykuormatiedot uloskirjaustapahtumasta. Vastattaessa uloskirjauskutsuun Vetuman SAML-rajapinnan kautta palautetaan uloskirjausvastauksessa (<LogoutResponse>) seuraavat tiedot uloskirjaustapahtumasta. Vetuman lähettämä uloskirjauskutsu noudattaa samaa rakennetta. Copyright Fujitsu Finland Oy 18 (25)
Tieto Vastauksen aikaleima Tapahtumatunnus Paluustatus P p v p Taulukko 10: Vetuman SAML-uloskirjausvastauksen hyötykuormaparametrit Verkkopalvelun tunnus Merkitys uloskirjauskutsussa: Vetuma-palvelua kutsuvan verkkopalvelun tunnus, viittauksena verkkopalvelun konfiguraatiotietoihin Vetumassa. Sijainti uloskirjauskutsussa: <LogoutResponse>-elementin elementin <saml:issuer> arvo Esitysmuoto: URL-syntaksin mukainen merkkijono, maksimipituus 1024 merkkiä. Tyyppi: Pakollinen Esimerkki: https://www.example.org/app1 Vastauksen aikaleima Merkitys uloskirjausvastauksessa: Määrittää sen hetken, jolloin vastaus luotiin. Sijainti uloskirjausvastauksessa: <LogoutResponse>-elementin attribuutti IssueInstant Esitysmuoto: Merkkijono, 24 merkkiä. Tyyppiä xs:datetime W3C XML Schema datatyyppimäärityksen mukainen [Schema2] UTC muodossa ilman aikavyöhykettä Esimerkki: 2008-03-28T12:50:47.693Z Tapahtumatunnus Merkitys uloskirjausvastauksessa: Mahdollistaa Vetuma-palvelua kutsuvan sovelluksen säilyttää tilatietoa ja saada se takaisin vastauksessa. Sijainti uloskirjausvastauksessa: Uloskirjausvastauksen sisältävässä lomakkeessa erillinen RelayState -kenttä. Esitysmuoto: Max 80 tavua Paluustatus Merkitys uloskirjausvastauksessa: Miten uloskirjaus onnistui. Kun Vetuma käsittelee sovellukselta saamaansa uloskirjauskutsua, niin uloskirjaus voi onnistua tai se voi jäädä eri syistä suorittamatta. Vetuma palauttaa SAML-uloskirjausvastauksessaan <StatusCode> - elementin, jolla kerrotaan onnistuiko uloskirjaus vai jäikö se jostain syystä suorittamatta Sijainti uloskirjausvastauksessa: <LogoutResponse>-elementin <Status>-elementti. Esitysmuoto: Vetuma voi palauttaa <Status>-elementin <StatusCode>-elementissä seuraavat paluustatukset, jotka on SAML 2.0-standarssa määritelty nimiavaruudessa urn:oasis:names:tc:saml:2.0:status: Copyright Fujitsu Finland Oy 19 (25)
SAML 2.0-standardissa määritelty tilakoodi Ylemmän tason tilakoodit: Success Requester Responder VersionMismatch Täydentäviä tilakoodeja: PartialLogout RequestDenied Onnistuminen Uloskirjaus onnistui Virheellinen kutsu Kutsun käsittely epäonnistui Kutsussa virheellinen versio Uloskirjaus epäonnistui Kutsuttu palvelu hylkäsi uloskirjauskutsun Taulukko 11: Vetuman palauttamat paluustatukset Status-elementissä voi olla myös valinnainen <StatusMessage>-elementti jossa voi antaa tarkentavan tilakoodin, sekä valinnainen <StatusDetail>-elementti jolla voi antaa yksityiskohtaisia tietoja virhetilanteista. 5. VETUMAN SAML-TUNNISTUSLÄHDEKYSELY Vetuma tunnistuslähteen selvityspyyntö tarkoittaa sitä, että aktiivista tunnistuslähdettä kysytään Vetuma-palveluun SAML-rajapinnan kautta. Tunnistuslähdekysely toteutetaan käyttäen SAMLmäärityksen profiilia Identity Provider Discovery Service Protocol and Profile. [SAMLDisco] Vetuma-palvelua kutsuvalle verkkopalvelulle tunnistuslähdekysely tarkoittaa sitä, että palvelu voi selvittää löytyykö käyttäjältä voimassa olevaa tietoa Vetuma-tunnistuspalvelun käyttämisestä ennen kuin tunnistaa käyttäjänsä Vetuman tarjoamalla SAML-standardin mukaisella tunnistuksella. Tällä voidaan saada aikaan tehokkaammin palveluita, jossa käyttäjän näkemä palvelu vaihtelee sen mukaan onko hän jo samalla selaimella tunnistautunut Vetuma:ssa ja tullut sinne sellaisen verkkopalvelun kautta, joka kutsui Vetuma-palvelua SAMLrajapinnalla. Kohdistamalla kertakirjautumisen tunnistetuille käyttäjille, ja välttämällä turhia tunnistuskyselyitä silloin kun istuntoa ei todennäköisesti ole, voidaan palvelujen etusivuille lisätä laajemmin sisältöä tunnistetuille käyttäjille. 5.1 Tunnistuslähdekysely- ja vastausviestien välitys SAML-tunnistuslähdekysely- ja vastausviestin välitys hoidetaan HTTP GET kustuina, eli ohjataan käyttäjän selaimen siirtymään muodostettuun osoitteeseen, joka kutsuu Vetumapalvelua määrittelyn mukaisesti. Vastausviesti välitetään vastaavasti käyttäjän selaimen avulle annettuun paluuosoitteeseen. 5.2 Tunnistuslähdekyselyn parametrit SAML-tunnistuslähdekysely (HTTP GET) rakenne on määritelty [SAMLDisco-standardissa]. Tässä luvussa on kuvattu, miten kyselyllä voidaan ohjata Vetumaa selvitystapahtuman suorittamisessa. Pyydettäessä selvitystä Vetuman SAML-rajapinnan kautta annetaan kutsussa seuraavat tunnistusta ohjaavat hyötykuormatiedot. Sarakkeessa P on kerrottu onko parametri pakollinen vai valinnainen. Copyright Fujitsu Finland Oy 20 (25)
Tieto P Parametrin nimi Verkkopalvelun tunnus p entityid Paluuosoite v return Käytäntö v policy Paluuparametri v returnidparam Passiivinen käsittely v ispassive Taulukko 12: Vetuman SAML-tunnistuslähdekutsun hyötykuormaparametrit Verkkopalvelun tunnus Merkitys tunnistuslähdekutsussa: Vetuma-palvelua kutsuvan verkkopalvelun tunnus, viittauksena verkkopalvelun konfiguraatiotietoihin Vetumassa. Esitysmuoto: URL-syntaksin mukainen merkkijono, URL-enkoodattuna, maksimipituus 1024 merkkiä. Tyyppi: Pakollinen Esimerkki: https%3a%2f%2fwww.example.org%2fapp1 Paluuosoite Merkitys tunnistuslähdekutsussa: Paluuosoite sovellukseen tunnistuslähdekutsun käsittelyn jälkeen. Esitysmuoto: URL-syntaksin mukainen merkkijono, URL-enkoodattuna, maksimipituus 1024 merkkiä. Ei saa sisältää returnidparam arvoa tai sen puuttuessa arvoa entityid. Tyyppi: Valinnainen Esimerkki: https%3a%2f%2fwww.example.org%2fapp1 Käytäntö Merkitys tunnistuslähdekutsussa: Politiikka, joka määrittää palvelun tunnistuslähde selvityksen käyttäytymisen. Toistaiseksi ainoastaan oletusarvo on käytössä, joten parametri on turha. Esitysmuoto: URI-syntaksin mukainen merkkijono. Arvon puuttuessa oletusarvona on "urn:oasis:names:tc:saml:profiles:sso:idp-discovery-protocol:single. Tyyppi: Valinnainen Esimerkki: urn:oasis:names:tc:saml:profiles:sso:idp-discovery-protocol:single Paluuparametri Merkitys tunnistuslähdekutsussa: Mahdollistaa Vetuma-palvelua kutsuvan sovellukselle asettaa vastauksessa palaavan attribuutin nimi, jossa annetaan kyselyn tuloksena saadun tunnistuspalvelun tunniste. Mikäli arvoa ei anneta, käytetään oletuksena arvoa entityid. Esitysmuoto: Max 80 merkkiä. Tyyppi: Valinnainen Copyright Fujitsu Finland Oy 21 (25)
Passiivinen käsittely Merkitys tunnistuslähdekutsussa: Mahdollistaa Vetuma-palvelua kutsuvalle sovellukselle kertoa saako käyttäjän ottaa mukaan toimimaan käyttöliittymässä tunnistuslähdettä selvitettäessä. Mikäli arvoa ei anneta, käytetään oletuksena arvoa false. Esitysmuoto: Boolean. Tyyppi: Valinnainen 5.3 Tunnistuslähdevastauksen hyötykuormaparametrit 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ä. Paluuosoite muodostetaan tunnistuslähdekutsun paluuosoite parametrin arvon pohjalta. Mikäli tunnistuslähde ei ollut käytössä tai selvitys epäonnistui, palataan ilman tunnistuspalvelun tunnuksen sisältävää parametria. SAML-tunnistuslähdevastauksen URL:n rakenne sekä sen käyttö tunnistusvastauksissa on määritelty SAML 2.0-standardissa [SAMLDisco]. Vetuma palauttaa SAML-rajapinnan tunnistuslähdevastauksen (HTTP GET) seuraavat tiedot tunnistuslähdetapahtumasta: Tieto P Parametrin nimi Tunnistuspalvelun tunnus v entityid tai kutsun returnidparam attribuutin arvo Taulukko 13: Vetuman SAML-tunnistuslähdevastauksen hyötykuormaparametrit Tunnistuspalvelun tunnus Merkitys tunnistuslähdevastauksessa: Tunnistuspalvelun verkkopalvelun tunnus, jos tunnistuslähdekysely onnistui. Esitysmuoto: URL-syntaksin mukainen merkkijono, URL-enkoodattuna, maksimipituus 1024 merkkiä. Tyyppi: Valinnainen Esimerkki: https%3a%2f%2ftunnistus.suomi.fi%2fvetumasso%2fapp 6. YLEINEN POIKKEUSTILANTEIDEN KÄSITTELY Sovellukselta saamaansa kutsua käsitellessään Vetuma voi havaita erityyppisiä poikkeustilanteita joiden takia kutsussa pyydetty toiminto jää suorittamatta. Tässä luvussa on kuvattu tällaisten poikkeustilanteiden käsittely. Lisäksi kutsu- ja vastausviestien välityksessä saattaa esiintyä sellaisia virhetilanteita joita ei pysty havaitsemaan asiointisovellus, Vetuma eikä Vetuman kutsuma taustapalvelu. Asiointisovellusten tekijöiden tulee silti olla tietoisia tästäkin virhemahdollisuudesta. 6.1 Vetuma-palvelun havaitsemat poikkeustilanteet Vetumassa voi esiintyä seuraavanlaisia palvelun havaitsemia virhetilanteita: Sovelluksen lähettämä kutsu on virheellinen joko syntaktisesti, allekirjoituksen tarkistuksen perusteella, tai virheellisten parametrien arvojen perusteella. Esimerkkejä Copyright Fujitsu Finland Oy 22 (25)
viimeksi mainitusta ovat syntaktisesti oikea asiakkaan tunnus, joka ei kuitenkaan viittaa mihinkään Vetumaan rekisteröityyn asiakkaaseen. Vetuman kutsuma taustapalvelu hylkää toiminnon suorittamisen ja palauttaa siitä tiedon Vetumalle, esimerkiksi pankin verkkopalvelu hylkää käyttäjän tunnistautumisen. Vetuma ei jostain muusta syystä pysty palvelemaan kutsua, esimerkiksi: o o o Toimintaympäristössä ilmenee jokin tekninen vika, esimerkiksi kutsua Vetumalle osoitetun pyynnön palvelemisessa tarvittavaan taustapalveluun ei saada lähetettyä. Kutsutulta taustapalvelulta ei tule vastausta. Kutsussa pyydetyn toimenpiteen suorittamisessa tapahtuu virhe, esimerkiksi käyttäjä ei sallittujen yritysten puitteissa onnistu tunnistautumaan mobiilivarmenteella. Vetuman loppukäyttäjä peruu tunnistautumisen. Tämä voi tapahtua seuraavilla tavoilla: o o Käyttäjä keskeyttää tai peruu tunnistautumisen Vetuman käyttöliittymässä. Käyttäjä keskeyttää tai peruu toiminnon Vetuman kutsumassa tunnistuslähteessä (esimerkiksi pankin verkkopalvelussa), ja tunnistuslähde palauttaa perumisesta tiedon Vetuma-palvelulle. 6.1.1 Paluu sovellukseen poikkeustilanteissa Kaikissa Vetuman havaitsemissa poikkeustilanteissa se palauttaa kutsussa annettuun, paluuosoitteeseen lähettämässään tunnistusvastauksessa tiedon tunnistuksen onnistumisesta tai epäonnistumisesta mikäli vain voidaan palata. 6.1.2 Testiympäristön tuki kutsuvirheiden tutkimiselle Vetuman testiympäristö tukee SAML-tunnistuskutsujen testaamista siten, että havaitessaan virheellisen kutsun se avaa käyttäjän (testaajan) selaimeen käyttöliittymän jossa näyttää miksi kutsu on virheellinen (esimerkiksi muotovirhe tai virheellinen parametrin arvo). Tuotantoympäristössä ei tällaisia virheilmoituksia näytetä, eli loppukäyttäjiä ei niillä koskaan häiritä. 6.2 Virhetilanteet kutsu- ja vastausviestien välityksessä Kutsut asiointisovelluksilta Vetumalle ja vastaukset Vetumalta asiointisovelluksille välitetään käyttäjän työaseman kautta. Myös kutsut Vetumalta sellaisille vuorovaikutteisille tunnistuslähteille joihin käyttäjä siirretään Vetumasta (kuten pankkien verkkopalvelut) sekä vastaukset näiltä tunnistuslähteiltä 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ä (joka toimitti viestin HTTP-vastauksena selaimelle) ei saa tietoa välityksen epäonnistumisesta. 6.2.1 Vetuma-istunnon vanhentuminen Käyttäjälle luodaan Vetuma-istunto hänen siirtyessään asiointisovelluksen käyttöliittymästä Vetuman käyttöliittymään. Vetuma-istunto voi päättyä vanhentumiseen seuraavista syistä: Käyttäjä ei anna Vetuman odottamaa syötettä 30 minuutin kuluessa syötteen pyytämisestä. Copyright Fujitsu Finland Oy 23 (25)
Vetuman kutsumalta vuorovaikutteiselta tunnistuslähteeltä ei tule vastausta Vetumalle 30 minuutin kuluessa kutsun lähettämisestä. Vetuma-istunnon päätyttyä vanhentumiseen asiointisovellus ei saa minkäänlaista vastausta Vetumalta, vaan sen on itse varauduttava havaitsemaan vanheneminen. Jos käyttäjän selain kuitenkin yrittää lähettää istunnon lopettamisen jälkeen HTTP-kutsun Vetuma-palvelulle: 6.2.2 Toistuvat kutsut Kyseistä HTTP-kutsua ei palvella koska istuntoa ei enää ole olemassa. Käyttäjälle näytetään yleinen (asiointisovelluksesta riippumaton) ilmoitus istunnon vanhentumisesta. Tieto kutsun hylkäämisestä talletetaan Vetuma-palvelun lokitietoihin mahdollisessa ongelmanselvityksessä käytettäväksi. Yleisesti selainpohjaisissa sovelluksissa on mahdollista käyttäjän toimesta aiheuttaa useampi kuin yksi peräkkäinen identtinen palvelupyyntö (POST-komento). Sovellus saattaa esimerkiksi palauttaa selaimelle vastauksen jossa on sekä JavaScript POST-komennon suorittamiseksi että submit-painike siltä varalta, että skriptien käyttö olisi estetty. Vastauksen saaminen automaattisesti lähetettyyn POST-komentoon voi kuitenkin joskus kestää niin kauan, että käyttäjä olettaa kutsun epäonnistuneen ja aktivoi käsikäyttöisen submit-painikkeen. Tällöin sovellukselle lähtee automaattisesti lähetetyn kutsun kanssa identtinen ylimääräinen kutsu. Vetuman palauttamissa vastauksissa ylimääräisten POST-komentojen lähettämistä on pyritty karttamaan. Kun Vetuma-palvelu havaitsee, että selaimessa on sallittu skriptien käyttö, se ei sisällytä submit-painikkeita sellaisiin selaimelle palauttamiinsa http-vastauksiin joiden tarkoitus on aikaansaada automaattinen siirtyminen vastauksessa annettuun osoitteeseen. 7. LIITTEET JA VIITTEET 7.1 Liitteet 1. Vetuma-palvelun SAML-kutsurajapinnan metadata-tiedosto (pdf) 2. Liite1_Vetuma_palvelinvarmenteet (pdf) 3. Liite3_Vetuma_SAML_sanomaesimerkit (pdf) 7.2 Viitteet [SAML 2.0-standardi] 1. [SAMLCore] S. Cantor et al. Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0. OASIS SSTC, March 2005. Document ID saml-core-2.0- os. http://www.oasis-open.org/committees/security/. 2. [SAMLProfile] Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0. OASIS SSTC, March 2005. Document ID saml-profiles-2.0-os. http://www.oasisopen.org/committees/security/. 3. [SAMLAuthnCxt] J. Kemp et al. Authentication Context for the OASIS Security Assertion Markup Language (SAML) V2.0. OASIS SSTC, March 2005. Document ID samlauthncontext-2.0-os. http://www.oasis-open.org/committees/security/. 4. [SAMLBind] S. Cantor et al. Bindings for the OASIS Security Assertion Markup Language (SAML) V2.0. OASIS SSTC, March 2005. Document ID saml-bindings-2.0-os. http://www.oasis-open.org/committees/security/. Copyright Fujitsu Finland Oy 24 (25)