Suomalaisen julkishallinnon Vetuma-palvelu Versio: 3.5.2 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 2.6 SAML-vastausviestien salaus... 8 3. Vetuma-palvelun SAML-kertakirjautuminen... 8 3.1 Tunnistustapojen osoittaminen... 9 3.2 Tunnistuskutsun hyötykuormaparametrit... 9 3.3 Tunnistusvastauksen hyötykuormaparametrit... 12 4. Vetuma-palvelun SAML-kertauloskirjautuminen... 16 4.1 Uloskirjauskutsun hyötykuormaparametrit... 16 4.2 Uloskirjausvastauksen hyötykuormaparametrit... 18 5. Vetuma-palvelun 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... 23 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... 24 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.2 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. Vetuma-palvelun 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. Versiossa 3.5.2 on lisätty tuki SAML-viestien salaukselle. 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, Symantec ja Entrust. Huomaa, että uusissa varmenteissa tulisi jatkossa käyttää SHA-256 -algoritmia SHA-1 -algoritmin sijan. 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"> Copyright Fujitsu Finland Oy 6 (25)
2.3 Parametrikäytännöt Kun Vetuma-palvelu käsittelee sovellukselta saamaansa tunnistuskutsua, niin tunnistus voi onnistua tai se voi jäädä eri syistä suorittamatta. Vetuma palauttaa SAMLtunnistusvastauksessaan 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 (myös aikaisempaa algoritmia RSAwithSHA1 tuetaan toistaiseksi). Vetuma tukee seuraavia XMLallekirjoitusstandardin 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 XMLallekirjoituksen samalla tavalla. Vetuma-palvelua kutsuvan asiointisovelluksen tulee tarkastaa saamansa allekirjoitukset. Palveluntarjoajien XML-allekirjoituksissa käyttämät varmenteet Copyright Fujitsu Finland Oy 7 (25)
rekisteröidään liittymisen yhteydessä. Vetuma-palvelu hyväksyy palveluntarjoajien varmentajina seuraavat CA:t: VRK, VeriSign, Thawte, Symantec ja Entrust. Huomaa, että uusissa varmenteissa tulisi jatkossa käyttää SHA-256 -algoritmia SHA-1 -algoritmin sijan. 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. 2.6 SAML-viestien salaus Vetuma-palvelu tukee SAML 2.0 -määrityksen mukaista viestien salausta. Mikäli toiminnallisuus on käytössä, palautetaan vastausviestin seloste ja sen sisältämät käyttäjätiedot salattuina. Vastausviestissä on tällöin <Assertion>-elementin tilalla <EncryptedAssertion>-elementti. SAML-sanomaesimerkit dokumentissa on esitetty salatun vastaussanoman esimerkki. Salaustoiminnallisuus voidaan ottaa käyttöön asiakaskohtaisesti. Sen edellytyksenä on että toimitettu metadata sisältää salausvarmenteen ja että salauksen käyttöönotosta on sovittu Vetuma-palvelun kanssa. Metadata on kuvattu tarkemmin Vetuma-palvelun SAMLkutsurajapinnan metadata-tiedosto dokumentissa. 3. VETUMA-PALVELUN 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äytetään Vetuma-palvelun SAML-tunnistuskutsu- ja SAML-tunnistusvastauksia. Alla on yhteenveto siitä mitä Web Browser SSO Profile -standardissa määriteltyjä kutsuja/vastauksia ja sidoksia (bindings) Vetuma-palvelun versiossa 3.5.2 tuetaan. Profiili Sanomat Sidos (Binding) Versio 3.5.2 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 -standardin sanomista ja sidoksista Vetuma-palvelua kutsuvalle verkkopalvelulle kertakirjautuminen tarkoittaa sitä, että käyttäjän näkemä palvelu Vetuma-palvelussa vaihtelee sen mukaan onko hän jo samalla selaimella tunnistautunut Vetuma-palveluun ja tullut sinne sellaisen verkkopalvelun kautta, joka kutsui Vetuma-palvelua SAML-rajapinnalla. 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. Copyright Fujitsu Finland Oy 8 (25)
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 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 Vetuma-palvelun SAML-rajapinnan kautta annetaan SAMLtunnistuskutsussa (<AuthnRequest>) seuraavat tunnistusta ohjaavat hyötykuormatiedot. Sarakkeessa P on kerrottu onko parametri pakollinen vai valinnainen. Copyright Fujitsu Finland Oy 9 (25)
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 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 Vetuma-palvelua sovellus voi määrätä, mitä tuettua kieltä Vetumapalvelun 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: Copyright Fujitsu Finland Oy 10 (25)
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 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]. Osoitteen domain-osan tulisi vastata verkkopalvelun tunnuksen domain-osaa. 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 Copyright Fujitsu Finland Oy 11 (25)
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-palvelu palauttaa SAML-rajapinnan tunnistusvastauksessa (<Response>) seuraavat tiedot tunnistetusta henkilöstä ja tunnistustapahtumasta: 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: Vetuma-palvelun 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: Merkkijono. Kuvattu kohdassa 3.1. Esimerkki: <saml:authncontextclassref>http://www.valtiokonttori.fi/vip/authncontext/strong </saml:authncontextclassref> (Tunnistus suoritettiin vahvan tunnistuksen 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ä. Copyright Fujitsu Finland Oy 12 (25)
Esitysmuoto: Max 80 tavua Henkilöllisyys Vetuma-palvelu palauttaa aina istuntoa varten muodostetun henkilöllisyyden tunnisteen, transient IDn. Lisäksi palvelu palauttaa selosteessa ne tiedot jotka ovat saatavilla (riippuen tunnistustavasta): SATU (jos käyttäjä tunnistautui kansalaisvarmenteeseen perustuvalla menetelmällä) HETU (Tunnistauduttaessa kansalaisvarmenteeseen perustuvalla menetelmällä suoritetaan VTJ-haku. Tämä edellyttää asiakasorganisaatiolta VTJ-tietolupaa.) VTJDATA (VTJ-kyselytuotteen mukaiset käyttäjän perustiedot jos käyttäjä tunnistautui, asiakasorganisaatiolla on VTJ-tietolupa ja sovellus pyysi VTJ-tietoja) Nimitiedot tunnistuslähteestä Henkilöllisyyden tunniste Merkitys vastauksessa: Vetuma-palvelun 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 Vetuma-palvelun 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-palvelu käsittelee sovellukselta saamaansa tunnistuskutsua, niin tunnistus voi onnistua tai se voi jäädä eri syistä suorittamatta. Vetuma-palvelu 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: Vetuma-palvelun palauttamat paluustatukset Status-elementissä saattaa olla mukana <StatusMessage>-elementti jossa annetaan tarkentavaa tietoa virhetilanteesta. 4. VETUMA-PALVELUN 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-palvelusta tulevien uloskirjauskutsujen käsittely ja niihin vastaaminen. Alla on yhteenveto siitä mitä Single Logout Profile:lle standardissa määriteltyjä kutsuja/vastauksia ja sidoksia (bindings) Vetuma-palvelun versiossa 3.5.2 tuetaan. Profiili Sanomat Sidos (Binding) Versio 3.5.2 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 Vetuma-palvelun SAML-rajapinnan kautta annetaan SAMLuloskirjauskutsussa (<LogoutRequest>) seuraavat uloskirjausta ohjaavat hyötykuormatiedot. Vetuma-palvelun 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: Vetuma-palvelun 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: Vetuma-palvelun 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 Vetuma-palvelua sovellus voi määrätä, mitä tuettua kieltä Vetuman käyttöliittymän tulee käyttää. Määräys koskee selainkäyttöliittymää. Vetuma-palvelu 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-palvelu palauttaa sille ominaiset hyötykuormatiedot uloskirjaustapahtumasta. Vastattaessa uloskirjauskutsuun Vetuma-palvelun SAML-rajapinnan kautta palautetaan uloskirjausvastauksessa (<LogoutResponse>) seuraavat tiedot uloskirjaustapahtumasta. Vetuma-palvelun lähettämä uloskirjauskutsu noudattaa samaa rakennetta. Copyright Fujitsu Finland Oy 18 (25)
Tieto Vastauksen aikaleima Tapahtumatunnus Paluustatus P p v p Taulukko 10: Vetuma-palvelun 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-palvelu käsittelee sovellukselta saamaansa uloskirjauskutsua, niin uloskirjaus voi onnistua tai se voi jäädä eri syistä suorittamatta. Vetuma-palvelu palauttaa SAML-uloskirjausvastauksessaan <StatusCode> -elementin, jolla kerrotaan onnistuiko uloskirjaus vai jäikö se jostain syystä suorittamatta Sijainti uloskirjausvastauksessa: <LogoutResponse>-elementin <Status>-elementti. Esitysmuoto: Vetuma-palvelu 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. VETUMA-PALVELUN SAML-TUNNISTUSLÄHDEKYSELY Vetuma-palvelun tunnistuslähteen selvityspyyntö tarkoittaa sitä, että aktiivista tunnistuslähdettä kysytään Vetuma-palveluun SAML-rajapinnan kautta. Tunnistuslähdekysely toteutetaan käyttäen SAML-mää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 Vetumapalvelussa 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 -kutsuina, eli ohjataan käyttäjän selain siirtymään muodostettuun osoitteeseen, joka kutsuu Vetuma-palvelua määrittelyn mukaisesti. Vastausviesti välitetään vastaavasti käyttäjän selaimen avulla annettuun paluuosoitteeseen. 5.2 Tunnistuslähdekyselyn parametrit SAML-tunnistuslähdekyselyn (HTTP GET) rakenne on määritelty [SAMLDisco-standardissa]. Tässä luvussa on kuvattu, miten kyselyllä voidaan ohjata Vetuma-palvelua selvitystapahtuman suorittamisessa. Copyright Fujitsu Finland Oy 20 (25)
Pyydettäessä selvitystä Vetuma-palvelun SAML-rajapinnan kautta annetaan kutsussa seuraavat tunnistusta ohjaavat hyötykuormatiedot. Sarakkeessa P on kerrottu onko parametri pakollinen vai valinnainen. 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: Vetuma-palvelun 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. Copyright Fujitsu Finland Oy 21 (25)
Esitysmuoto: Max 80 merkkiä. Tyyppi: Valinnainen 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 Vetuma-palvelu 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-palvelu 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-palvelu 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-palvelu eikä Vetuman kutsuma taustapalvelu. Asiointisovellusten tekijöiden tulee silti olla tietoisia tästäkin virhemahdollisuudesta. Copyright Fujitsu Finland Oy 22 (25)
6.1 Vetuma-palvelun havaitsemat poikkeustilanteet Vetuma-palvelussa voi esiintyä seuraavanlaisia palvelun havaitsemia virhetilanteita: Sovelluksen lähettämä kutsu on virheellinen joko syntaktisesti, allekirjoituksen tarkistuksen perusteella, tai virheellisten parametrien arvojen perusteella. Esimerkkejä viimeksi mainitusta ovat syntaktisesti oikea asiakkaan tunnus, joka ei kuitenkaan viittaa mihinkään Vetumaan rekisteröityyn asiakkaaseen. Vetuma-palvelun kutsuma taustapalvelu hylkää toiminnon suorittamisen ja palauttaa siitä tiedon Vetumalle, esimerkiksi pankin verkkopalvelu hylkää käyttäjän tunnistautumisen. Vetuma-palvelu 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. Vetuma-palvelun loppukäyttäjä peruu tunnistautumisen. Tämä voi tapahtua seuraavilla tavoilla: o o 6.1.1 Paluu sovellukseen poikkeustilanteissa 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. Kaikissa Vetuma-palvelun 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 Vetuma-palvelun 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 Vetuma-palvelulle ja vastaukset Vetuma-palvelulta asiointisovelluksille välitetään käyttäjän työaseman kautta. Myös kutsut Vetuma-palvelulta sellaisille vuorovaikutteisille tunnistuslähteille joihin käyttäjä ohjataan Vetuma-palvelusta (kuten pankkien verkkopalvelut) sekä vastaukset näiltä tunnistuslähteiltä Vetuma-palvelulle 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. Copyright Fujitsu Finland Oy 23 (25)