Suomalaisen julkishallinnon Vetuma-palvelu Vetuma-palvelun SAML-kutsurajapinnan metadata-tiedosto Versio: 3.5.2 Vetuma Verkkotunnistus ja -maksaminen
Sisällysluettelo 1. Johdanto... 3 2. Metadata määrityksen vaatimukset... 3 2.1 Pakolliset tiedot... 3 2.1.1 Verkkopalvelun tunnus... 3 2.1.2 Palveluntarjoajan kertakirjauspalvelun kuvaus... 4 2.1.3 Asiakkaan yhteyshenkilöt... 5 2.2 Valinnaiset tiedot... 5 2.2.1 Vastaussanoman salausvarmenne... 5 2.2.2 Organisaation kuvaus... 5 3. Esimerkki metadata-tiedosto... 7 4. Liitteet ja viitteet... 9 4.1 Liitteet... 9 4.2 Viitteet... 9 2 (9)
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. käyttäjähallintaan, 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. 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.2 on päivitetty mobiilivarmennetunnistus ja lisätty tuki laajennetulle VTJ-kyselylle. Laajennetun VTJ-kyselyn käyttöönotosta on lisätietoa tässä dokumentissa. Versiossa 3.3 on lisätty tuki verkkopalvelun nimen näytättämiseksi käyttöliittymässä ensisijaisesti käyttäjäattribuuttien määrittely-elementin palvelunimen arvosta. Lisätietoja löytyy tästä dokumentista. Versiossa 3.4 on lisätty tuki uloskirjauksen Redirect - yhteystyypille (HTTP-Redirect -Binding) ja asiakkaan yhteystiedoille (ContactPerson) sekä päivitetty metadata-esimerkki. Versiossa 3.5.2 on lisätty tuki SAML-sanomien salaukselle. 2. METADATA-MÄÄRITYKSEN VAATIMUKSET Asiointisovelluksien liittyessä käyttämään Vetuma-palvelun SAML-rajapintaa, he toimittavat oman palvelunsa SAML-rajapinnan kuvaavan metadata-tiedoston. Tämä dokumentti on ohje tiedoston vaatimuksista. Vetuman SAML-rajapinnassa käytetään UTF-8 merkistöä. Sovelluksen kannalta tämä tarkoittaa muun muassa sitä, että metadata-tiedostoissa saa esiintyä vain UTF-8 merkistön merkkejä. Vetuma-palvelun käyttämä metadata-tiedosto on liitteenä. 2.1 Pakolliset tiedot Metadata-tiedoston on noudatettava SAML 2.0 version määrityksiä. [SAMLMeta] 2.1.1 Verkkopalvelun tunnus Verkkopalvelun tunnus on yksilöllinen tunniste sille SAML-osapuolelle, joka kuvataan Metadata määrityksessä. Verkkopalvelun tunnus sijaitsee <md:entitydescriptor>-elementin attribuutissa entityid. <md:entitydescriptor>-elementti pitää sisällään kaikki muut elementit. 3 (9)
Verkkopalvelun tunnus on URL-muotoinen osoite, jonka arvo sovitaan liittymisen yhteydessä. Localhost-tyyppisiä osoitteita ei sallita (testiympäristössäkään). 2.1.2 Palveluntarjoajan kertakirjauspalvelun kuvaus Tiedostossa on oltava mukana palveluntarjoajan SAML 2.0 kertakirjauspalvelun kuvaava <md:spssodescriptor> -elementti. Elementti pitää sisällään tiedon viestien allekirjoituksessa käytettävästä varmenteesta sekä erilliset kuvaukset kertakirjautumisen ja kertauloskirjautumisen toteuttavien palveluiden osoitteista. 2.1.2.1 XML-allekirjoituksissa käytettävä varmenne Määrää sen julkisen avaimen varmenteen jota vastaavalla yksityisellä avaimella verkkopalvelu allekirjoittaa Vetumalle lähettämänsä sanoman. Vetuma-palvelu edellyttää, että kaikissa metadata tiedostoissa on mukana <md:keydescriptor > elementti allekirjoitusta varten. Tässä elementissä on oltava <ds:keyinfo>-elementti, joka pitää sisällään käytetyn varmenteen seuraavan rakenteen mukaisesti <ds:x509data><ds:x509certificate>...</ds:x509certificate></ds:x509data>. Esitysmuoto on määritelty SAML-standardissa (metadatamäärittelyn [SAMLMeta] kohdassa 2.4.1.1). Verkkopalvelun käyttämä varmenne sovitaan 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 sijasta. 2.1.2.2 XML-allekirjoituksissa käytettävän varmenteen vaihtaminen Vetuma-palvelun metadatatiedostoon voi määritellä samanaikaisesti useamman varmenteen yhdelle verkkopalvelulle. Varmennetta vaihdettaessa, verkkopalvelu n ylläpitäjä voi toimittaa Vetuma-palvelulle otettavaksi käyttöön useamman varmenteen sisältävän väliaikaisen metadatan. Tällöin verkkopalvelu voi valita käyttämänsä varmenteen ja sen vaihtoajankohdan itsenäisesti. Kun varmenteen vaihto on suoritettu, verkkopalvelu toimittaa uuden metadatan yhdellä varmenteella. Useat varmenteet esitetään metadatatiedostoissa rinnakkaisina <md:keydescriptor > - elementteinä, kuten edellisessä kappaleessa. 2.1.2.3 Kertauloskirjautumista tukeva palvelu Elementti <md:singlelogoutservice> määrittää kertauloskirjautumista käyttävän palvelun paluuosoitteen (Location-attributti) ja käytetyn SAML-yhteystyypin (Binding-attributti). Paluuosoitteen on oltava https-alkuinen ja sen domain-osan tulisi vastata verkkopalvelun tunnuksen (entityid-arvon) domain-osaan. Käytetyn yhteystyypin tuetut arvot ovat: urn:oasis:names:tc:saml:2.0:bindings:http-redirect ja urn:oasis:names:tc:saml:2.0:bindings:http-post. 2.1.2.4 Kertakirjautumista hyödyntävä palvelu Elementti <md:assertionconsumerservice> määrittää kertakirjautumista käyttävän palvelun paluuosoitteen (Location-attributti), indeksin (index-attributti) ja käytetyn SAML yhteystyypin (Binding-attributti). Paluuosoitteen on oltava https-alkuinen ja sen domain-osan tulisi vastata verkkopalvelun tunnuksen (entityid-arvon) domain-osaan. Indeksiä voidaan käyttää kertakirjautumispalvelun valitsemisessa SAML-protokollaviestissä. Käytetyn yhteystyypin arvo on aina: urn:oasis:names:tc:saml:2.0:bindings:http-post. 4 (9)
2.1.3 Asiakkaan yhteyshenkilöt Moniarvoisessa metatietoattribuutissa ContactPerson voidaan antaa seuraavan tyyppisten yhteyshenkilöiden yhteystiedot: technical, support, administrative, billing ja other. Yhteyshenkilöksi on määriteltävä vähintään tekninen yhteyshenkilö, mutta myös hallinnollisen yhteyshenkilön yhteystiedot toivotaan annettavan. Muut yhteystiedot ovat valinnaisia, mutta auttavat ohjaamaan viestit aihepiirin mukaan oikealle taholle. Yhteyshenkilölle määritellään seuraavat tiedot: yhteyshenkilön tyyppi (technical, support, administrative, billing tai other), etunimi, sukunimi, sähköpostiosoite ja puhelinnumero (valinnainen). Esimerkki teknisistä yhteyshenkilöistä: <md:contactperson contacttype="technical"> <md:givenname>vetuma</md:givenname> <md:surname>testi</md:surname> <md:emailaddress>vetuma.testi@fi.fujitsu.com</md:emailaddress> </md:contactperson> <md:contactperson contacttype="administrative"> <md:givenname>vetuma</md:givenname> <md:surname>testi</md:surname> <md:emailaddress>vetuma.testi@fi.fujitsu.com</md:emailaddress> <md:telephonenumber>+358123456789</md:telephonenumber> </md:contactperson> 2.2 Valinnaiset tiedot 2.2.1 Sanomien salausvarmenne Tiedostossa voi olla mukana varmenne Vetuma-palvelun SAML-sanomien salaustoiminnallisuutta varten. Salausvarmenne on merkitty <md:keydescriptor>-elementin use-attribuutin encryption-arvolla. Vaihtoehtoisesti use-attribuutti voi puuttua kokonaan, jolloin kyseistä varmennetta voi käyttää sekä viestien allekirjoittamiseen että salaamiseen. Salausvarmenne mahdollistaa SAML-sanomien salaamisen, mutta toiminnallisuuden aktivointi suoritetaan pyynnöstä erikseen. <md:keydescriptor use="encryption"> <ds:keyinfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> <ds:keyname>esimerkki.asiakas.fi</ds:keyname> <ds:x509data> <ds:x509certificate>[varmenne]</ds:x509certificate> </ds:x509data> </ds:keyinfo> </md:keydescriptor> 2.2.2 Organisaation kuvaus Tiedostossa voi olla mukana palveluntarjoajan organisaation kuvaava <md:organization> - elementti. 2.2.2.1 Verkkopalvelun nimi näytettäväksi käyttöliittymässä Käyttöliittymässä näytettävä verkkopalvelun nimi on ensisijaisesti elementin <md:attributeconsumingservice> määrittämä <ServiceName>-elementin arvo. Elementti 5 (9)
<ServiceName> sisältää kirjautumisen yhteydessä välittyneen tiedon palvelun nimestä. Jos palvelun nimi ei ole saatavilla <ServiceName>-elementissä, näytetään käyttöliittymässä verkkopalvelun nimenä organisaation kuvauksessa mukana olevan <md:organizationdisplayname>-elementin arvo. Käytössä olevan elementin <ServiceName> tai <md:organizationdisplayname> on oltava määritelty erikseen kaikilla verkkopalvelun tukemilla kielillä, jotta nimi saadaan näytettyä käyttäjälle hänen käyttämällään kielellä. Mikäli metatiedossa konfiguroitu arvo on liian pitkä, niin se katkaistaan Vetuma-rajapinnassa sallittuun pituuteen. Esitysmuoto: Merkkijono, pituus enintään 40 merkkiä Sallitut merkit ovat: Numerot, kirjaimet, välilyönti, tavuviiva, piste, pilkku, kaksoispiste, lainausmerkki, puolipiste ja sulkeet. Mikäli verkkopalvelun nimeä ei haluta näytettäväksi käyttöliittymässä, jätetään nämä tiedot joko tyhjäksi tai sitten elementit <ServiceName> ja <md:organizationdisplayname> jätetään pois verkkopalvelun metatiedoista. 2.2.2.2 Verkkopalvelun laskutustunnus tapahtumaraportointia varten Organisaation kuvauksessa on mukana <md:organizationname>-elementti, joka kuvaa organisaation nimen käytettäväksi laskutustunnuksena tapahtumaraportointia varten. Jos metatiedossa konfiguroitu arvo on liian pitkä, niin se katkaistaan Vetuma-rajapinnassa sallittuun pituuteen. Esitysmuoto: Merkkijono, pituus 5..150 merkkiä, sallittuja merkkejä ovat numerot 0..9, isot ja pienet kirjaimet, tavuviiva ( - ) ja alaviiva ( _ ) Mikäli laskutustunnusta ei haluta tapahtumaraporttiin, jätetään tämä tieto tyhjäksi verkkopalvelun metatiedoista tai sitten koko organisaation kuvaus elementti jätetään pois verkkopalvelun metatiedoista. Laskutustunnuksesta poistetaan välilyönnit ennen käyttöönottoa. 2.2.2.3 Verkkopalvelun informaatio-osoite Organisaation kuvauksessa on mukana <md:organizationurl>-elementti, joka määrittää osoitteen jossa käyttäjä saa lisätietoja palvelusta. Osoitetta ei hyödynnetä toistaiseksi Vetumapalvelussa. 2.2.2.4 Kirjautumisen yhteydessä palautettavat käyttäjäattribuutit Elementillä <md:attributeconsumingservice> voidaan määrittää kirjautumisen yhteydessä palautettavat käyttäjäattribuutit, joita kyseinen palvelu tarvitsee. Indeksiä voidaan käyttää SAML-protokollaviestissä valitsemaan tietty attribuuttijoukko. 2.2.2.4.1 Laajennetun VTJ-kyselyn perustiedot Laajennetulla VTJ-kyselyllä saadaan haettua konfiguroidun VTJ-kyselytuotteen mukaiset käyttäjän perustiedot, eli käyttäjän VTJDATA-tiedot. Mikäli VTJ-kysely on aktivoitu kyseiselle palvelulle ja palvelu näitä tietoja tarvitsee, tulee kyseinen attribuutti (urn:vetuma:saml:2.0:attributes:vtjdata) asettaa SP:n metadataan. Alla on esimerkki, jossa toivotut attribuutit on lisätty metadatatiedostoon elementin <md:spssodescriptor> sisälle. <md:spssodescriptor <md:attributeconsumingservice isdefault="true" index="1"> <md:servicename xml:lang="fi">esimerkkipalvelu</md:servicename> <md:servicename xml:lang="en">example service</md:servicename> <md:servicename xml:lang="sv">example service</md:servicename> 6 (9)
Name="urn:oid:2.5.4.3" FriendlyName="cn"> Name= urn:vetuma:saml:2.0:attributes:vtjdata" FriendlyName="extendedVTJData"> Name="urn:oid:1.2.246.21" FriendlyName="nationalIdentificationNumber"> Name="urn:oid:1.3.6.1.4.1.31350.1.11" FriendlyName="authenticationProvider"> Name="urn:oid:1.2.246.22" FriendlyName="electronicIdentificationNumber"> </md:attributeconsumingservice> </md:spssodescriptor> 3. ESIMERKKI METADATA-TIEDOSTO Tässä on esimerkki toimitettavasta metadata-tiedostosta, kun halutaan hyödynnettäväksi kaikki nykyiset käyttäjäattribuutit ilman erillistä laajennetulla VTJ-kyselyllä haettuja käyttäjän perustietoja: <?xml version="1.0" encoding="utf-8" standalone="no"?> <md:entitydescriptor xmlns:md="urn:oasis:names:tc:saml:2.0:metadata" entityid="https://esimerkki.asiakas.fi:8443/client1"> <md:spssodescriptor protocolsupportenumeration="urn:oasis:names:tc:saml:2.0:protocol"> <md:keydescriptor use="signing"> <ds:keyinfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> <ds:keyname>esimerkki.asiakas.fi</ds:keyname> <ds:x509data> <ds:x509certificate>[allekirjoitusvarmenne] </ds:x509certificate> </ds:x509data> </ds:keyinfo> </md:keydescriptor> <md:keydescriptor use="encryption"> <ds:keyinfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> <ds:keyname>esimerkki.asiakas.fi</ds:keyname> <ds:x509data> <ds:x509certificate>[salausvarmenne] 7 (9)
</ds:x509certificate> </ds:x509data> </ds:keyinfo> </md:keydescriptor> <md:singlelogoutservice Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://esimerkki.asiakas.fi:8443/Client1/logout "/> <md:singlelogoutservice Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://esimerkki.asiakas.fi:8443/Client1/logout "/> <md:assertionconsumerservice Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP- POST" Location="https://esimerkki.asiakas.fi:8443/Client1" index="0"/> <md:attributeconsumingservice isdefault="true" index="1"> <md:servicename xml:lang="fi">esimerkkipalvelu</md:servicename> <md:servicename xml:lang="en">example service</md:servicename> <md:servicename xml:lang="sv">example service</md:servicename> Name="urn:oid:2.5.4.3" FriendlyName="cn"> Name="urn:oid:1.2.246.21" FriendlyName="nationalIdentificationNumber"> Name="urn:oid:1.3.6.1.4.1.31350.1.11" FriendlyName="authenticationProvider"> Name="urn:oid:1.2.246.22" FriendlyName="electronicIdentificationNumber"> </md:attributeconsumingservice> </md:spssodescriptor> <md:organization> <md:organizationname xml:lang="en">esimerkki organisaatio</md:organizationname> <md:organizationdisplayname xml:lang="fi">esimerkki organisaatio</md:organizationdisplayname> <md:organizationdisplayname xml:lang="en">example organization</md:organizationdisplayname> <md:organizationdisplayname xml:lang="sv">example organization</md:organizationdisplayname> <md:organizationurl xml:lang="en">http://esimerkki.asiakas.fi</md:organizationurl> </md:organization> <md:contactperson contacttype="technical"> <md:givenname>vetuma</md:givenname> <md:surname>testi</md:surname> <md:emailaddress>vetuma.testi@fi.fujitsu.com</md:emailaddress> </md:contactperson> <md:contactperson contacttype="administrative"> <md:givenname>vetuma</md:givenname> <md:surname>testi</md:surname> 8 (9)
<md:emailaddress>vetuma.testi@fi.fujitsu.com</md:emailaddress> <md:telephonenumber>+358123456789</md:telephonenumber> </md:contactperson> </md:entitydescriptor> 4. LIITTEET JA VIITTEET 4.1 Liitteet 1. Liite5 tunnistus.suomi.fi-idp-metadata (xml) 2. Liite6 testitunnistus.suomi.fi-idp-metadata (xml) 4.2 Viitteet 1. [SAMLMeta] S. Cantor et al. Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0. Document ID saml-metadata-2.0-os http://docs.oasisopen.org/security/saml/v2.0/saml-metadata-2.0-os.pdf 9 (9)