Skapa e-tjänstens metadatafil

Skapa e-tjänstens metadatafil enligt anvisningarna i den här artikeln.

Beskrivning av uppgifterna

Metadatan skapas av elementet md:EntityDescriptor som innehåller elementen:

• md:SPSSODescriptor, en beskrivning av tjänsten
• md:Organization, uppgifter om den organisation som erbjuder e-tjänsten
• md:ContactPerson, e-tjänstens kontaktuppgifter.

E-tjänstens unika identifikationskod

md:EntityDescriptor-elementets entityID-attribut individualiserar e-tjänsten. Innehållet ska vara en URL och basera sig på e-tjänstens domännamn. Identifikationskoden behöver inte leda till någon webbsida. Vid övergångsfasen godkänns även URN.

E-tjänsten ska inkludera identifikationskoden i sina anrop (begäran om identifikation och begäran om utloggning).

Godkända identifieringsverktyg

De identifieringsverktyg som e-tjänsten godkänner fastställs i elementet mdattr:EntityAttributes. Möjliga värden:

Exempel

I exemplen nedan visas hur de godkända tillitsnivåerna (både de som fastställts av kommunikationsverket och de som följer eIDAS-förordningen) ska definieras i metadatan.

Hög tillitsnivå

<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>
 ...
 
</mdattr:EntityAttributes>

Höjd tillitsnivå

<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>

Lägg märke till att hög tillitsnivå

• http://ftn.ficora.fi/2017/loa3, och
• http://eidas.europa.eu/LoA/high

alltid ska definieras i metadatan i tillägg till den höjda nivån. Följande format är alltså inte tillåtet:

<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-stöd

eIDAS-stöd konfigureras med EidasSupport-attribut värden

Standardvärdet är 'full'

Du kan läsa mer om eIDAS i artikeln.

I fall e-tjänsten inte är skyldig att använda eIDAS, vänligen kontakt stöd för tjänsten Identifikations ibruktagande att tunnistus-kayttoonotot@dvv.fi.

Algoritm som används för att kryptera retursvaret

För kryptering av autentiseringssvaret är det möjligt att använda två olika algoritmer under övergångsperioden (2021-2022): AES-GCM och AES-CBC. Standard är AES-GCM-algoritmen:

<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>

Nyckeltransportalgoritm för autentiseringssvaret

Nyckeltransportalgoritmen för autentiseringssvaret kan väljas i metadatan. Som standard är värdet rsa-oaep-mgf1p, men vi rekommenderar att ändra det till en starkare sha256-variant. Du kan ange den i elementet KeyDescriptor.

Rekommenderat värde för nyckeltransport är:

<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>

Om det inte är möjligt att använda det rekommenderade värdet kan även värdet nedan användas, eller så kan det utelämnas för att falla tillbaka till standardvärdet:

<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>

De uppgifter som visas i användargränssnittet

Den information som slutanvändaren visas beskrivs inne i elementet mdui:UIInfo. De uppgifter som visas i användargränssnittet ska levereras i en finsk, en svensk och en engelsk version.

<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>

Tabell 1. De uppgifter som visas i användargränssnittet.

Certifikat

Certifikatet innehåller en offentlig nyckel. E-tjänsten undertecknar det meddelande som skickats till Suomi.fiÖppnas i ett nytt fönster.-identifikationen med den offentliga nyckelns motsvarande privata nyckel. Med underskriften kan Suomi.fiÖppnas i ett nytt fönster.-identifikationen bekräfta meddelandets ursprung. Suomi.fiÖppnas i ett nytt fönster.-identifikationen använder också certifikatet för att kryptera svarsmeddelandet. Den enda stödda nyckeltypen är RSA. ECC-nycklar stöds inte.

I produktionsmiljön ska certifikatet vara undertecknat av någon känd CA (t.ex. Myndigheten för digitalisering och befolkningsdata, Telia, DigiCert...). Under de kommande åren kommer det att ske betydande ändringar i TLS-certifikatens giltighetstider och giltighetstiderna kommer stegvis att förkortas upp till 47 dagar senast den 15 mars 2029. Därför rekommenderar vi att man använder Myndigheten för digitalisering och befolkningsdatas systemsignaturcertifikat med två års giltighetstid. Mer information om hur du beställer MDB:s certifikat finns på adressen
https://dvv.fi/sv/bestallning-av-servicecertifikatÖppnas i ett nytt fönster.. Vi rekommenderar också att man inte använder samma certifikat i testmiljön som i produktionen. Det går också att använda självundertecknade certifikat i testmiljön.

Certifikatet är ett systemsignaturcertifikat. För att certifikatet ska kunna beviljas ska produktionscertifikatet beställas med rätt format av CN-namn (Fully Qualified Domain Name).

Använd undertypen ”systemsignaturcertifikat” för typen ”servicecertifikat” vid beställning av certifikat.

Certifikatet finns i md:KeyDescriptor-elementets element ds:KeyInfo:

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

I certifikatet beskrivs den publika nyckeln med vars motsvarande privata nyckel e-tjänsten signerar det meddelande som skickas till identifieringstjänsten för att identifieringstjänsten kan säkerställa meddelandets ursprung.

Certifikatet är av typen SERVER CERTIFICATE, produktionssertifikatet måste beställas med CN-namnet i rätt format (Fullt kvalificerat domännamn) för att certifikatet ska kunna utfärdas.

Identifieringstjänsten förutsätter att e-tjänstens metadata alltid innehåller KeyDescriptor-elementet för signering. I det här elementet måste ds:KeyInfo-elementet finnas som ska innehålla det använda certifikatet enligt följande struktur:

<ds:X509Data>
  <ds:X509Certificate>...</ds:X509Certificate>
</ds:X509Data>

Bekanta dig närmare med certifikatets format (w3.org, på engelska)Öppnas i ett nytt fönster..

E-tjänsten kan samtidigt fastställa flera certifikat i e-tjänstens metadata. E-tjänstens administratör kan till exempel då certifikattet byts ut leverera Suomi.fi-identifikationen metadata som innehåller flera certifikat. Då kan e-tjänsten välja självständigt vid vilken tidpunkt det använda certifikatet byts ut. Om certifikaten är flera till antalet anges de parallellt som md:KeyDescriptor-element i metadatafilen.

Även om endast den publika nyckeln utnyttjas av uppgifterna i e-tjänstens certifikat rekommenderar vi att man utnyttjar ett annat certifikat i utbytet av SAML-meddelanden än det som används för att kryptera e-tjänstens trafik.

Bekanta dig närmare med hur man byter certifikat.

Returadressen för utloggningssvaret

Elementet md:SingleLogoutService definierar returadressen för utloggningssvaret i Location-attributet och den SAML-förbindelsetyp som används i Binding-attributet. Värden som stöds för den förbindelsetyp som används är:

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

Vänligen använd bara en bindelsetyp, svaret skickas alltid till den första addressen/bindelsen.

I returadressens URL måste HTTPS-protokollet användas. Exempel:

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

Returadress för identifikationssvaret

Elementet md:AssertionConsumerService definierar returadressen för inloggningssvaret i Location-attributet och den SAML-förbindelsetyp som används i Binding-attributet. Den enda förbindelsetyp som stöds är urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST. Flera returadresser kan anges. Det går att hänvisa till önskad returadress i identifikationsanropet genom att använda det obligatoriska index-attributet som kopplats till adressen.

I returadressens URL måste HTTPS-protokollet användas. Exempel:

<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" />

E-tjänstens namn och de personuppgifter som begärs

md:AttributeConsumingService-elementet innehåller e-tjänstens namn samt en lista på de uppgifter som e-tjänsten begär om användaren av Suomi.fi-identifikation. Bara ett md:AttributeConsumingService-element stöds och den måste ha attributen index="1" och isDefault="true".

E-tjänstens namn definieras i elementet md:ServiceName. Namnet ska anges på finska, svenska och engelska. Namnet kan vara annat än den namnuppgift som visas för slutanvändaren (mdui:DisplayName). Elementet är ett obligatoriskt underelement till md:AttributeConsumingService.

<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>

Med elementet md:RequestedAttribute definieras de personuppgifter som begärs om en identifierad användare. De personuppgifter som finns tillgängliga vid identifikationen förmedlas alltid. Både de uppgifter som returneras med finländska identifieringsverktyg och de som returneras med eIDAS-identifieringsverktyg kan listas upp sida vid sida i metadatan.

Läs mer om uppfgifter som förmedlas vid identifikationshändelser.

I exemplet nedan begär e-tjänsten om personbeteckning och personens namn.

<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>

För att utnyttja uppgifterna i befolkningsdatasystemet krävs ett datatillstånd. Suomi.fi-identifikationen förmedlar endast uppgifter enligt datatillståndet åt e-tjänsten. I testmiljön behövs inget datatillstånd. Läs mer om hur du ansöker om tjänsten Identifikations datatillstånd.

Identifikation vid undantagstillstånd utan granskning av uppgifterna i befolkningsdatasystemet

Suomi.fi-identifikation granskar användarens uppgifteri befolkningsdatasystemet när ett identifieringsverktyg används som returnerar användarens personbeteckning.

Identifikationen kan utföras i e-tjänsten även utan att uppgifterna granskas om detta önskas. Den här funktionen är avsedd för undantagstillstånd där uppgifterna inte på grund av en störning kan granskas i befolkningsdatasystemet. I e-tjänstens genomförande måste beaktas att om uppgifterna inte granskas så förmedlas endast den personbeteckning samt namnuppgift (cn) som erbjuds av identifieringsverktyget.

Funktionaliteten kan testas genom att ange 151070-9138 till testidentifieraren (... 110 999) i testmiljön.

Identifiering vid undantagstillstånd utan granskning av uppgifterna i befolkningsdatasystemet definieras genom att ge attributet VtjVerificationRequired värdet ”false”. Standardinställningen är att elementet läggs till i metadatan med värdet "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>

Definition av dynamisk returadress

En dynamisk reuradres för SAML2-kommunikation kan tas i bruk genom att ange attributet SkipEndpointValidationWhenSigned värdet ”true”. Då kan e-tjänsten fastställa den returadress dit SAML2 AuthenticationResponse skickas per begäran om identifikation.

Observera att definitionen i fråga endast gäller svaret på begäran om identifikation. LogoutResponse och LogoutRequest skickas alltid till den adress som definierats i metadatan.

Användningen av den dynamiska returadressen förutsätter att olika nycklar används i SAML2-kommunikationen och i TSL-datatrafiken.

<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>

Uppgifter om den organisation som begär identifikation

Uppgifterna för den organisation som äger e-tjänsten anges i elementet md:Organization. Uppgifterna ska levereras i en finsk, en svensk och en engelsk version. Om någon av språkversionerna inte används kan elementet anges samma värde som till exempel i den finskspråkiga versionen.

<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>

Tabell 2. Uppgifter om den organisation som begär identifikation.

E-tjänstens kontaktpersoner och uppgifter om stödtjänsten

Uppgifterna om e-tjänstens kontaktpersoner anges i attributet md:ContactPerson. Typerna av kontaktpersoner är

• technical
• support
• administrative
• other.

Som kontaktperson måste åtminstone den tekniska kontaktpersonen anges, men vi hoppas att även den administrativa kontaktpersonens och stödtjänsternas kontakinformation anges.

Följande uppgifter fastställs för kontaktpersonen:

• typ av kontaktperson (technical, support, administrative eller other)
• förnamn (specialtecken måste vara HTML -kodade)
• efternamn (specialtecken måste vara HTML -kodade)
• e-postadress
• telefonnummer (valfritt).

<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>