Suomi.fi e-Identification – E-service metadata

Print Friendly, PDF & Email
 


Please follow the instructions given in this document when forming the e-service metadata file. Download the metadata file template: metadata_malli.xml. All sections to be completed in the template are marked with the string ”TODO”.

An example of a completed metadata file: metadata_example.xml

For a description of a metadata file compliant with the SAML 2.0 standard, visit http://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf

Data description

The metadata is composed of an md:EntityDescriptor element that contains the following elements:

  • md:SPSSODescriptor, service description
  • md:Organization, data of the organisation offering the e-service
  • md:ContactPerson, e-service contact details

E-service identifier

The e-service is identified by the <codeaEntityID attribute of the md:EntityDescriptor element. The content must be an URL based on the e-service’s domain name. The identifier does not need to be an address of a website. In the transition phase, an URN will also be accepted.

The e-service must include the identifier in its calls (identification and logout requests), otherwise Suomi.fi e-Identification cannot authenticate the sender’s signature.

Accepted tokens

The tokens accepted by the e-service are specified in the <code>mdattr:EntityAttributes</code> element. Possible values:

http://ftn.ficora.fi/2017/loa3 high, fLOA3
http://eidas.europa.eu/LoA/high high, eLOA3*
http://ftn.ficora.fi/2017/loa2 substantial, fLOA2
http://eidas.europa.eu/LoA/substantial eLOA3*
urn:oid:1.2.246.517.3002.110.5 KatsoOTP
urn:oid:1.2.246.517.3002.110.6 KatsoPWD
urn:oid:1.2.246.517.3002.110.998 EIDAS test token only used in customer testing environment
urn:oid:1.2.246.517.3002.110.999 test token only used in the customer testing environment

* The assurance levels high and substantial referred to in the elDAS regulation may be added to the metadata even though elDAS identification will only become possible in September 2018. Specifying these levels for metadata will become obligatory on 1 September 2018. The specifications of the elDAS assurance levels must always be in accordance with the corresponding FICORA assurance levels, as set out in the table above.

Examples

The examples below show how the approved assurance levels (those specified by FICORA and the ones set out in the elDAS regulation) should be specified in metadata.

High, fLOA3

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

Substantial, fLOA2

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

The high level of assurance (http://ftn.ficora.fi/2017/loa3) must always be defined with the substantial level. Thus, the following form is not permitted:
<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:Attribute>
 ...
</mdattr:EntityAttributes>

Substantial level of assurance in addition to Katso PWD and Katso OTP

<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>
<saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">urn:oid:1.2.246.517.3002.110.5</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">urn:oid:1.2.246.517.3002.110.6</saml:AttributeValue>
</saml:Attribute>
...

</mdattr:EntityAttributes>

Data and logo displayed in the user interface

The data to be displayed to the end user is described in the mdui:UIInfo element. A Finnish, Swedish and English version of the data displayed in the user interface should be submitted. If one of the language versions is not used in the e-service, the contents can be copied from the Finnish version, for example.

<mdui:UIInfo>
  <mdui:DisplayName xml:lang="en">Fishing license online</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:Logo height="38" width="93">https://mallikunta.fi/kalastuslupalogo.png</mdui:Logo>
  <mdui:PrivacyStatementURL xml:lang="fi">https://kalastus.mallikunta.fi/rekisteriseloste_fi.html</mdui:PrivacyStatementURL>
  <mdui:PrivacyStatementURL xml:lang="sv">https://kalastus.mallikunta.fi/rekisteriseloste_sv.html</mdui:PrivacyStatementURL>
  <mdui:PrivacyStatementURL xml:lang="en">https://kalastus.mallikunta.fi/rekisteriseloste_en.html</mdui:PrivacyStatementURL>
</mdui:UIInfo>
Data Element name Explanation
E-service display name mdui:DisplayName The e-service name displayed to the end user. Maximum length 50 characters.

If the element has not been specified, the value of the element md:ServiceName is used

E-service discription mdui:Discription  A short description of the e-service. Maximum length 255 characters.
 E-service logo position and size mdui:Logo HTTPS-protected web address (URL) from which the e-service logo can be retrieved. As additional attributes can be given the width and height of the logo. Maximum length 255 characters. Currently there may be only one logo for all languages (without attribute xml:lang).
E-service file description address mdui:PrivacyStatementURL  The link to the e-service file description displayed in Suomi.fi e-Identification. Maximum length 255 characters.

Certificate

The certificate contains a public key. The e-service uses the private key corresponding to this public key to sign the messages it sends to Suomi.fi e-Identification. The signature allows Suomi.fi e-Identification to verify the origin of a transmitted message. The certificate may be signed by the e-service itself when it is used against a TESTING environment. In production the certificate has to be issued by one of the following CA’s: VRK, VeriSign, Thawte, Symantec, Entrust or Terena.

The certificate resides in the ds:KeyInfo element of the md:KeyDescriptor element:

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

For the format of the certificate, see the document XML Signature Syntax and Processing.

Several certificates can be simultaneously specified for an e-service in the e-service metadata. For example, when a certificate is replaced, the e-service administrator can submit to Suomi.fi e-Identification a temporary metadata file that contains several certificates. The e-service can then independently select the certificate to be used and the time of its replacement. Several certificates are presented as parallel md:KeyDescriptor elements in the metadata files.

While only the public key of the e-service certificate is used, it is recommended that different certificates are used for SAML messaging and for encrypting e-service traffic.

Logout response return address

The element md:SingleLogoutService specifies the logout response return address in the Location attribute and the SAML connection type used in the Binding attribute. The supported values of the used connection type are:

urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect and

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

A https protocol must be used in the return address URL. Example:

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

Identification response return address

The element md:AssertionConsumerService specifies the logout response return address in the Location attribute and the used SAML connection type in the Binding attribute. The only supported connection type is urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST. Several return addresses may be given, and reference can be made to the desired return address in the identification call by using the index attribute attached to the address, which is mandatory.

A https protocol must be used in the return address URL. Example:

<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-service name and requested personal data

The md:AttributeConsumingService element contains the e-service name and a list of the user data that the e-service requests from Suomi.fi e-Identification. One md:AttributeConsumingService element must have the attributes index="1" and isDefault="true".

The e-service name is specified in the md:ServiceName element. The name should be given in Finnish, English and Swedish. It may be different from the name data displayed to the end user (mdui:DisplayName). This element is a mandatory sub-element of md:AttributeConsumingService.

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

 

The md:RequestedAttribute elements specify the personal data requested on an identified user. For a list of the data used in identification events involving Finnish tokens and their identifiers, see ‘”Personal data transmitted on an identified user“. For the data transmitted on identification events involving non-Finnish tokens, see article ‘Attributes transmitted on elDAS-identified user’. The personal data that is available in connection with the identification event is always transmitted, which means that data returned by Finnish tokens and elDAS tokens can be listed in metadata side by side. In the example below, the e-service is requesting the personal identity code and the person’s name.

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

A data access authorisation is needed to use Population Information System data. Suomi.fi e-Identification only transmits to the e-service the data specified in the data access authorisation. No data access authorisation is needed in the customer testing environment.

Identification in exceptional situations without checking the data in the Population Information System

Suomi.fi e-Identification checks the user’s data against Population Information System data in connection with each strong authentication. If preferred, the e-service can also enable identification without checking the data. This functionality is intended for exceptional situations where checking the data is not possible due to a disruption in the Population Information System. The e-service implementation must ensure that if the data has not been checked, only the personal identity code offered by the token and the name data (cn) of the user are communicated.

Identification without checking the data against Population Information System data in exceptional situations is enabled by setting the value of the attribute VtjVerificationRequired as ”false”. As a default, the value of this element in the metadata is ”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>

Specifying eIDAS capability

Specifying EidasSupport cabality

E-services can specify other than full eIDAS capability in their metadata using the EidasSupport attribute. With the attribute value ‘form’, a message form is provided to citizens using eIDAS identification, and the information in the form is submitted to an e-mail address specified with the EidasContactAddress attribute.

If the EidasSupport attribute not specified, the default value ‘full’ will be applied, referring to full eIDAS support. In this case, eIDAS-identified users are directed to the e-service as normal.

<saml:Attribute xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" FriendlyName="EidasSupport" Name="urn:oid:1.2.246.517.3003.111.14" 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">form</saml:AttributeValue>
</saml:Attribute>

Possible values for the EidasSupport attribute:

full Default value. Full eIDAS support though which eIDAS-identified users are directed straight to the e-service similarly as users who have identified themselves with Finnish tokens.
form No eIDAS support. After successful eIDAS identification, the citizen is presented a form whose information is submitted to an e-mail addressed specified by the e-service.

Specifying the contact address for the eIDAS form

When using the form alternative for the EidasSupport attribute, the eServices must also specify an e-mail address to which messages sent using the form are submitted. The address is specified using a new attribute ‘EidasContactAddress’. The attribute must be specified whenever the EidasSupport attribute is ‘form’.

<saml:Attribute xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" FriendlyName="EidasContactAddress" Name="urn:oid:1.2.246.517.3003.111.15" 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">eidas.yhteydenotot@palvelu.fi</saml:AttributeValue>
</saml:Attribute>

Data of the organisation requesting identification

The data of the e-service owner organisation is contained in the md:Organization element. A Finnish, Swedish and English version of this data should be submitted. If one of these language versions is not in use, the value of the element in question should be copied from the Finnish version, for example.

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>
Data Element name Explanation
Organisation name md:OrganizationName Valid characters in the organisation name are: alphanumeric characters, space, hyphen, dot, comma, colon, quotation mark, semicolon and brackets.

The maximum length of a name is 40 characters.

 Organisation display name md:OrganizationDisplayName Organisation name in the form in which it is displayed to the user.

If the element has not been specified, the value of the element md:OrganizationName is used.

 Organisation network address md:OrganizationURL  A URL that directs the user to the website of the organisation requesting identification in error situations. The user is redirected to this address if no SAML error message can be returned to the e-service. This address should, for example, be the e-service frontpage.

E-service contact persons and support service details

The details of the e-service contact persons are given in the md:ContactPerson attribute. The contact person types are: technical, support, administrative and other.

At minimum, a technical contact person must be specified, but it is desirable to also give the contact details of an administrative contact person and a support service contact person.

The following data are specified for a contact person: contact person type (technical, support, administrative or other), first name, last name, e-mail address and telephone number (optional). E-mail address is presented in URL-format (begins with mailto:).

<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>mailto:tiina.tuki@mallikunta.fi</md:EmailAddress>
 <md:TelephoneNumber>+358123456789</md:TelephoneNumber>
 </md:ContactPerson>

 


 Document history

Version Changes Date/Author
1.0 Document published on eSuomi 18.11.16 / NP
2.0 Document updated 21.02.17 / NP
 2.1  Document updated  20.3.18 / EJ
2.2 Document updated 10.7.18 / EJ
2.3 Document updated 17.8.18 / EJ

Document identifier: JTO21