Asiointipalvelun metadatatiedoston muodostaminen

Tässä ohjeessa kerrotaan, miten asiointipalvelun metadatatiedosto muodostetaan.

Tietojen kuvaukset

Metadata muodostuu 

md:EntityDescriptor

• md:SPSSODescriptor

  , palvelun kuvaus

• md:Organization

  , asiointipalvelua tarjoavan organisaation tiedot

• md:ContactPerson

  , asiointipalvelun yhteystiedot.

Asiointipalvelun yksilöivä tunniste

md:EntityDescriptor-elementin entityID-attribuutti yksilöi asiointipalvelun. Sisällön tulee olla URL perustuen asiointipalvelun verkkotunnukseen. Tunnisteen ei tarvitse ohjata millekään verkkosivulle. Siirtymävaiheessa hyväksytään myös URN.

Asiointipalvelun on sisällytettävä tunniste kutsuihinsa (tunnistuspyyntö ja uloskirjautumispyyntö).

Hyväksytyt tunnistusvälineet

Asiointipalvelun hyväksymät tunnistusvälineet määritellään mdattr:EntityAttributes-elementissä. Mahdolliset arvot:

Esimerkkejä

Alla olevissa esimerkeissä on esitetty, kuinka hyväksytyt varmuustasot (sekä viestintäviraston määrittelemät että eIDAS-asetuksen mukaiset) määritellään metadatassa.

Korkea varmuustaso

<mdattr:EntityAttributes xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute">
 <saml:Attribute xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Name="FinnishAuthMethod" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
 <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">http://ftn.ficora.fi/2017/loa3</saml:AttributeValue>
 <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">http://eidas.europa.eu/LoA/high</saml:AttributeValue>
 </saml:Attribute>

Korotettu varmuustaso

<mdattr:EntityAttributes xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute">
 <saml:Attribute xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Name="FinnishAuthMethod" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
 <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">http://ftn.ficora.fi/2017/loa3</saml:AttributeValue>
 <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">http://eidas.europa.eu/LoA/high</saml:AttributeValue>
 <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">http://ftn.ficora.fi/2017/loa2</saml:AttributeValue>
 <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">http://eidas.europa.eu/LoA/substantial</saml:AttributeValue>
 
 ...
 
</mdattr:EntityAttributes>

Huomioi, että korkeat varmuustasot on aina määriteltävä metadatassa korotetun tason lisäksi. Seuraava muoto ei siis ole sallittu:

<mdattr:EntityAttributes xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute">
 <saml:Attribute xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Name="FinnishAuthMethod" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
 <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">http://ftn.ficora.fi/2017/loa2</saml:AttributeValue>
 <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">http://eidas.europa.eu/LoA/substantial</saml:AttributeValue>
 </saml:Attribute>
 ...
 
</mdattr:EntityAttributes>

eIDAS-tuen määrittäminen

eIDAS-tuen taso määritetään EidasSupport-attribuutin arvoilla.

Oletuksena käytetään tasoa 'full'.

Lue artikkeli eIDAS-tunnistamisesta, jos tarvitset lisätietoa aiheesta.

Jos palvelu ei kuulu eIDAS-velvoitteen piiriin, ota yhteyttä Tunnistus-palvelun käyttöönottojen tukeen osoitteeseen tunnistus-kayttoonotot@dvv.fi.

Paluuvastauksen salauksessa käytettävä algoritmi

Autentikaatiovastauksen salauksessa on mahdollista käyttää siirtymäaikana (2021-2022) kahta mahdollista algoritmia: AES-GCM ja AES-CBC. Oletuksena käytetään AES-GCM -algoritmia:

<saml:Attribute xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" FriendlyName="CipherName" Name="urn:oid:1.2.246.517.3003.111.26" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
          <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">AES-GCM</saml:AttributeValue>
        </saml:Attribute>

Paluuvastauksen avaimen salauksessa käytettävä algoritmi

Salausvarmenteelle voi määritellä avaimen salaukseen käytettävän algoritmin metadatassa. Oletusarvo algoritmille on rsa-oaep-mgf1p, mutta suosittelemme käyttämään vahvempaa sha256 versiota. Määritys tulee KeyDescriptor elementin sisälle.

Suositeltu arvo avaimen salaukselle on:

<md:KeyDescriptor>
  <ds:KeyInfo>
    <ds:X509Data>
      <ds:X509Certificate>...</ds:X509Certificate>
    </ds:X509Data>
  <ds:/KeyInfo>
  <md:EncryptionMethod Algorithm="http://www.w3.org/2009/xmlenc11#rsa-oaep">
    <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
    <xenc11:MGF Algorithm="http://www.w3.org/2009/xmlenc11#mgf1sha256"/>
  </md:EncryptionMethod>
<md:/KeyDescriptor>	

Jos suositellun algoritmin käyttö ei ole mahdollista, voidaan käyttää allaolevaa arvoa, tai sen voi jättää pois jolloin oletusarvo tulee käyttöön:

<md:KeyDescriptor>
  <ds:KeyInfo>
    <ds:X509Data>
      <ds:X509Certificate>...</ds:X509Certificate>
    </ds:X509Data>
  <ds:/KeyInfo>
  <md:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p"/>
  </md:EncryptionMethod>
<md:/KeyDescriptor>

Käyttöliittymässä näytettävät tiedot

Loppukäyttäjälle esitettävät tiedot kuvataan mdui:UIInfo-elementin sisällä. Käyttöliittymässä näytettävistä tiedoista on toimitettava suomen-, ruotsin- ja englanninkielinen versio.

<mdui:UIInfo>
 <mdui:DisplayName xml:lang="en">Fishing license online</mdui:DisplayName>
 <mdui:DisplayName xml:lang="sv">Fisketillstånd e-tjänst</mdui:DisplayName>
 <mdui:DisplayName xml:lang="fi">Sähköinen kalastuslupapalvelu</mdui:DisplayName>
 <mdui:Description xml:lang="en">Online service for fishing licenses in Modelcity</mdui:Description>
 <mdui:Description xml:lang="sv">E-tjänst för fisketillstånd i Examplekommun</mdui:Description>
 <mdui:Description xml:lang="fi">Mallikunnan sähköinen kalastuslupapalvelu</mdui:Description>
</mdui:UIInfo>

Taulukko 1. Käyttöliittymässä näytettävät tiedot

Varmenne

Varmenne sisältää julkisen avaimen, jota vastaavalla yksityisellä avaimella asiointipalvelu allekirjoittaa Suomi.fiAvautuu uuteen ikkunaan.-tunnistukselle lähettämänsä sanoman. Allekirjoituksen avulla Suomi.fiAvautuu uuteen ikkunaan.-tunnistus voi varmistua välitettävän sanoman alkuperästä. Suomi.fiAvautuu uuteen ikkunaan.-tunnistus käyttää varmennetta myös vastaussanoman salaukseen. Ainoa tuettu avaintyyppi on RSA. ECC avaimet eivät ole tuettu.

Tuotantoympäristössä varmenteen tulee olla jonkin tunnetun CA:n allekirjoittama (esim. Digi- ja väestötietovirasto, Telia, DigiCert…). TLS-varmenteiden voimassaoloaikoihin on tulevina vuosina tulossa merkittäviä muutoksia ja voimassaoloajat tulevat asteittain lyhenemään aina 47 päivään 15.3.2029 mennessä. Tämän vuoksi suosittelemme käyttämään Digi- ja väestötietoviraston järjestelmäallekirjoitusvarmenteita, joiden voimassaoloaika on kaksi vuotta. Lisätietoa DVV:n varmenteiden tilauksesta löydät osoitteesta https://dvv.fi/miten-tilaan-palveluvarmenteenAvautuu uuteen ikkunaan.. Suosittelemme myös, että testiympäristössä ei käytetä samaa varmennetta kuin tuotannossa. Testiympäristössä voidaan käyttää myös itseallekirjoitettuja varmenteita.

Varmenne on tyypiltään järjestelmäallekirjoitusvarmenne. Tuotannon varmenne tulee tilata siten, että sen CN - nimi on oikean muotoinen (Fully Qualified Domain Name), jotta varmenne voidaan myöntää.

Varmenteen tilauksessa käytetään "palveluvarmenne" -tyypin alatyyppiä "järjestelmäallekirjoitusvarmenne".

Varmenne on md:KeyDescriptor-elementissä olevassa ds:KeyInfo-elementissä:

<md:EntityDescriptor …
  <md:SPSSODescriptor …
    <md:KeyDescriptor>
      <ds:KeyInfo>
        <ds:X509Data>
          <ds:X509Certificate>...</ds:X509Certificate>
        </ds:X509Data>
      <ds:KeyInfo>
    <md:KeyDescriptor>

Varmenteessa kuvataan julkinen avain, jota vastaavalla yksityisellä avaimella asiointipalvelu allekirjoittaa tunnistuspalvelulle lähettämänsä sanoman, jotta tunnistuspalvelu voi varmistua välitettävän sanoman alkuperästä.

Tunnistuspalvelu edellyttää, että asiointipalvelun metatiedoissa on aina mukana 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>

Tutustu tarkemmin varmenteen esitysmuotoon (w3.org, englanniksi)Avautuu uuteen ikkunaan..

Asiointipalvelulle voi määritellä samanaikaisesti useamman varmenteen asiointipalvelun metatietoihin. Esimerkiksi varmennetta vaihdettaessa asiointipalvelun ylläpitäjä voi toimittaa Suomi.fi-tunnistukselle useamman varmenteen sisältävän metadatan. Tällöin asiointipalvelu voi valita käyttämänsä varmenteen vaihtoajankohdan itsenäisesti. Useat varmenteet esitetään metadatatiedostoissa rinnakkaisina md:KeyDescriptor-elementteinä.

Tutustu tarkemmin varmenteen vaihtoon.

Vaikka asiointipalvelun varmenteesta hyödynnetään vain julkista avainta, SAML-viestien vaihdossa suositellaan hyödynnettäväksi eri varmennetta kuin asiointipalvelun liikenteen salaamisessa.

Uloskirjautumisvastauksen palautusosoite

Elementti md:SingleLogoutService määrittää uloskirjautumisvastauksen palautusosoitteen Location-attribuutissa ja käytetyn SAML-yhteystyypin Binding-attribuutissa. Käytetyn yhteystyypin tuetut arvot ovat:

• urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
• urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST.

Vastaus lähetetään vain yhteen osoitteeseen, eli vain toivottava binding tulee esitellä.

Palautusosoitteen URLissa on käytettävä HTTPS-protokollaa. Esimerkki:

<md:EntityDescriptor …
  <md:SPSSODescriptor …
    <md:SingleLogoutService 
          Binding=”urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST”
          Location=”https://kalastus.mallikunta.fi/SAML2SLO/POST" />

Tunnistusvastauksen palautusosoite

Elementti md:AssertionConsumerService määrittää tunnistusvastauksen palautusosoitteen Location-attribuutissa ja käytetyn SAML-yhteystyypin Binding-attribuutissa. Yhteystyyppinä on tuettu vain urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST. Palautusosoitteita voi laittaa useita. Tunnistuskutsussa voi viitata haluttuun palautusosoitteeseen käyttämällä osoitteeseen liitettyä pakollista index-attribuuttia.

Palautusosoitteen URLissa on käytettävä HTTPS-protokollaa. Esimerkki:

<md:EntityDescriptor …
  <md:SPSSODescriptor …
    <md:AssertionConsumerService 
          Binding=”urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST”
          Location=”https://kalastus.mallikunta.fi/SAML/ACS/POST”
          index="1" />

Asiointipalvelun nimi ja pyydetyt henkilötiedot

md:AttributeConsumingService-elementti sisältää asiointipalvelun nimen sekä listan asiointipalvelun Suomi.fi-tunnistukselta pyytämistä käyttäjän tiedoista. Vain yhtä elementtiä tuetaan ja sillä on oltava attribuutit index="1" ja isDefault="true".

Asiointipalvelun nimi määritetään md:ServiceName-elementissä. Nimi on ilmoitettava suomeksi, ruotsiksi ja englanniksi. Tämä voi olla eri kuin loppukäyttäjälle näytettävä nimitieto (mdui:DisplayName). Elementti on pakollinen md:AttributeConsumingService:n alielementti.

<md:ServiceName xml:lang="fi">Kalastusluvat</md:ServiceName>
<md:ServiceName xml:lang="sv">Fisketillstånd</md:ServiceName>
<md:ServiceName xml:lang="en">Fishing license</md:ServiceName>

md:RequestedAttribute-elementillä määritetään tunnistetusta käyttäjästä pyydettävät henkilötiedot. Henkilötiedoista välitetään aina ne, jotka ovat tunnistustapahtuman yhteydessä saatavilla. Sekä suomalaisten tunnistusvälineiden että eIDAS-tunnistusvälineiden palauttamia tietoja voi listata metadatassa rinnakkain.

Lue tunnistetusta käyttäjästä välitettävistä tiedoista.

Alla olevassa esimerkissä asiointipalvelu pyytää henkilötunnuksen ja henkilön nimen.

<md:EntityDescriptor …
  <md:SPSSODescriptor …
    <md:AttributeConsumingService index="1" isDefault="true">
      <md:ServiceName xml:lang="fi">Kalastusluvat</md:ServiceName>
      <md:ServiceName xml:lang="sv">Fisketillstånd</md:ServiceName>
      <md:ServiceName xml:lang="en">Fishing license</md:ServiceName>>
      <md:RequestedAttribute 
          FriendlyName="displayName" 
          Name="urn:oid:2.16.840.1.113730.3.1.241"  
                    NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"/>
      <md:RequestedAttribute 
          FriendlyName="nationalIdentificationNumber" 
          Name="urn:oid:1.2.246.21" 
          NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"/>
    </md:AttributeConsumingService>

Väestötietojärjestelmän tietojen hyödyntäminen edellyttää käyttölupaa. Suomi.fi-tunnistus välittää asiointipalvelulle ainoastaan käyttöluvan mukaiset tiedot. Testiympäristössä käyttölupaa ei tarvita. Lue lisää Tunnistus-palvelun käyttöluvan hakemisesta.

Tunnistaminen poikkeustilanteessa ilman tietojen tarkastusta väestötietojärjestelmästä

Suomi.fi-tunnistus tarkastaa käyttäjän tiedot väestötietojärjestelmästä silloin, kun käytetään tunnistusvälinettä, joka palauttaa käyttäjän henkilötunnuksen tunnistustapahtuman yhteydessä.

Tunnistus on mahdollista suorittaa asiointipalvelussa myös ilman tietojen tarkastamista, jos niin halutaan. Tämä toiminto on tarkoitettu poikkeustilanteisiin, joissa tietojen tarkastus väestötietojärjestelmästä ei häiriöstä johtuen onnistu. Asiointipalvelun toteutuksessa on otettava huomioon, että jos tietoja ei ole tarkastettu, käyttäjästä välitetään ainoastaan tunnistusvälineen tarjoama henkilötunnus sekä nimitieto (cn).

Toiminnallisuutta voi testata Asiakastestiympäristössä syöttämällä testitunnistajaan (...110.999) hetun 151070-9138 .

Tunnistaminen poikkeustilanteissa ilman tietojen tarkastamista väestötietojärjestelmästä määritetään asettamalla VtjVerificationRequired-attribuutin arvoksi ”false”. Oletuksena elementti lisätään metadataan arvolla ”true”.

<saml:Attribute FriendlyName="VtjVerificationRequired" Name="urn:oid:1.2.246.517.3003.111.3" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"><saml:AttributeValue xsi:type="xs:string">true</saml:AttributeValue></saml:Attribute>

Dynaamisen paluuosoitteen määrittely

Dynaaminen paluuosoite SAML2-viestintää varten on mahdollista ottaa käyttöön SkipEndpointValidationWhenSigned-attribuutin arvolla ”true”. Tällöin asiointipalvelu voi määrittää paluuosoitteen, johon SAML2 AuthenticationResponse toimitetaan tunnistuspyyntökohtaisesti.

Huomaathan, että kyseinen määritys koskee vain tunnistuspyynnön vastausta. LogoutResponse ja LogoutRequest lähtevät aina metadatassa määritettyyn yhteen kiinteään osoitteeseen.

Dynaamisen paluuosoitteen käyttö edellyttää eri avainten käyttöä SAML2-viestinnässä ja TLS-tietoliikenteessä.

<saml:Attribute xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
 FriendlyName="SkipEndpointValidationWhenSigned"
 Name="urn:oid:1.2.246.517.3003.111.4"
 NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
 <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:type="xs:string">true</saml:AttributeValue>
</saml:Attribute>

Tunnistusta pyytävän organisaation tiedot

Asiointipalvelun omistajaorganisaation tiedot ilmoitetaan md:Organization-elementissä. Tiedoista on toimitettava suomen-, ruotsin- ja englanninkielinen versio. Jos jotakin kieliversiota ei ole käytössä, kyseisen elementin arvoksi voi kopioida esimerkiksi suomenkielisen version.

<md:EntityDescriptor …
  <md:OrganizationName xml:lang="fi">Mallikunta</md:OrganizationName>
  <md:OrganizationName xml:lang="sv">Examplekommun</md:OrganizationName>
  <md:OrganizationName xml:lang="en">Modelcity</md:OrganizationName>
  <md:OrganizationDisplayName 
        xml:lang="fi">Mallikunnan lupa-asiat</md:OrganizationDisplayName>
  <md:OrganizationDisplayName 
        xml:lang="sv">Tillståndstjänster I Examplekommun
  </md:OrganizationDisplayName>
  <md:OrganizationDisplayName 
        xml:lang="en">License services in Modelcity</md:OrganizationDisplayName>
  <md:OrganizationURL 
        xml:lang="fi">http://www.mallikunta.fi</md:OrganizationURL>
  <md:OrganizationURL 
        xml:lang="sv">http://www.mallikunta.fi/sv</md:OrganizationURL>
  <md:OrganizationURL 
        xml:lang="en">http://www.mallikunta.fi/en</md:OrganizationURL>

Taulukko 2. Tunnistusta pyytävän organisaation tiedot.

Asiointipalvelun yhteyshenkilöt ja tukipalvelun tiedot

Asiointipalvelun yhteyshenkilöiden tiedot ilmoitetaan md:ContactPerson-attribuutissa. Yhteyshenkilötyypit ovat

• technical
• support
• administrative
• other.

Yhteyshenkilöksi on määriteltävä vähintään tekninen yhteyshenkilö, mutta myös hallinnollisen yhteyshenkilön ja tukipalvelun yhteystiedot toivotaan annettavan.

Yhteyshenkilölle määritellään seuraavat tiedot:

• yhteyshenkilön tyyppi (technical, support, administrative tai other)
• etunimi (erikoismerkit nimessä tulee HTML-koodata)
• sukunimi (erikoismerkit nimessä tulee HTML-koodata)
• sähköpostiosoite
• puhelinnumero (valinnainen).

<md:EntityDescriptor …
  <md:ContactPerson contactType="technical">
    <md:GivenName>Teppo</md:GivenName>
    <md:SurName>Tekninen</md:SurName>
    <md:EmailAddress>mailto:teppo.tekninen@mallikunta.fi</md:EmailAddress>
    <md:TelephoneNumber>+358123456789</md:TelephoneNumber>
  </md:ContactPerson>
  <md:ContactPerson contactType="support">
    <md:GivenName>Tiina</md:GivenName>
    <md:SurName>Tuki</md:SurName>
    <md:EmailAddress>tiina.tuki@mallikunta.fi</md:EmailAddress>
    <md:TelephoneNumber></md:TelephoneNumber>
  </md:ContactPerson>