Creating metadata for the e-Service

Create the metadata with the help of this article.

Description of the information

Metadata consists ot the element 

md:Entity

Descriptor that contains these elements:

md:SPSSODescriptor 

the description of the service

md:Organization 

the organization that provides the e-Service

md:ContactPerson 

the contact person(s) for the technical / organizational / support for the metadata provided

The unique identification code of the e-service

md:EntityDescriptor-element's entityID-attribute identifies the e-Service. The content should be a URL and based on the e-service's domain name. The identification code does not have to lead to any web page. During the transition phase, URN is also approved.

The e-service must include the identification code in its messages (identification request and logout request).

Approved identification methods

The methods & levels that the e-Service approves are defined in the mdattr:EntityAttributes with the values of FinnishAuthMethod. Possible values:

Examples

The examples below show how the approved levels of trust (both those established by the FICORA and those following the eIDAS regulation) are to be defined in the metadata.

High Level of Assurance

<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 Level of Assurance

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

Note that high confidence levels (http://ftn.ficora.fi/2017/loa3 and http://eidas.europa.eu/LoA/high) should always be defined in the metadata in addition to the substantial level. The following formats are therefore not allowed:

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

eIDAS support is configured with EidasSupport attribute values.

The default value is 'full'.

You can read more about eIDAS in the article.

If the e-service is not obliged to use eIDAS, please contact support for the Identification service.

Algorithm used to encrypt the return response

To encrypt the authentication response, it is possible to use two different algorithms during the transition period (2021-2022): AES-GCM and AES-CBC. AES-GCM being the DEFAULT algorithm:

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

Key transport algorithm for authentication response

The key transport algorithm for authencation response can be selected in metadata. By default the value is rsa-oaep-mgf1p, however we recommened changing it to stronger sha256-variant. You can specify it inside the KeyDescriptor element.

The recommended value for key transport is:

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

If using recommended algorithm is not possible, the value below can be also used, or it can be omitted to fall back to the default value:

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

The information displayed in the user interface

The information displayed to the end user is described inside the element mdui: UIInfo. The information displayed in the user interface must be delivered in Finnish, Swedish and English versions.

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

Table 1. The information in the user interface.

Certificate

The certificate includes the public key, which is used with the corresponding private key to sign messages sent to Suomi.fiOpens in a new window. e-Identification. This signature allows Suomi.fiOpens in a new window. e-Identification to verify the origin of the message. Suomi.fiOpens in a new window. e-Identification also uses the certificate to encrypt the response message. The only supported key type is RSA. ECC keys are not supported.

In the production environment, the certificate must be signed by a known CA (such as the Digital and Population Data Services Agency, Telia, DigiCert...). There will be significant changes to the validity of TLS certificate in the coming years, reducing in stages to as few as 47 days by 15 March 2029. For this reason, we recommend that you use the Digital and Population Data Services Agency's system signature certificates, which are valid for two years. For additional information on ordering Digital and Population Data Services Agency certificates, please visit https://dvv.fi/en/how-to-order-a-service-certificate. We also recommend against using the same certificate in both the test and production environments. Self-signed certificates are allowed in the test environment.

The certificate type is system signature certificate. For production certificates to be granted, the orders must be placed in a way that their CN names are in the valid format (Fully Qualified Domain Name).

Certificate orders must be made for the ‘service certificate’ subcategory ‘system signature certificate’.

Certificate is placed in  md:KeyDescriptor-elements ds:KeyInfo element:

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

The certificate describes the public key that is corresponding the private key e-service is using in signing the message sent to the identification service.

The identification service assumes that the e-service's metadata always contains the KeyDescriptor element for signing. In this element, the ds: KeyInfo element must be present to contain the certificate used according to the following structure:
<ds:X509Data>

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

Read more about the format of the certificateOpens in a new window..

The e-service can present multiple certificates in the e-service's metadata. For example, when the certificate is changed, the administrator of the e-service can supply the Suomi.fi identification metadata containing several certificates. Then the e-service can choose independently at which time the used certificate is exchanged. If the certificates are multiple in number, they are specified in parallel as md: KeyDescriptor elements in the metadata file.

We recommend that you use a different certificate in the exchange of SAML messages than the one used to encrypt the e-service's traffic.

Learn more about changing the certificate.

The return address for the logout response

The md: SingleLogoutService element defines the return address of the logout response in the Location attribute and the SAML connection type used in the Binding attribute. Values ​​supported for the connection type used are:

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

Please note, that the first one is used, so please supply only the desired binding.

The return URL must use the HTTPS protocol. 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" />

Return address for the identification response

The md: AssertionConsumerService element defines the return address of the login response in the Location attribute and the SAML connection type used in the Binding attribute. The only connection type supported is urn: oasis: names: tc: SAML: 2.0: bindings: HTTP-POST. Multiple return addresses can be specified. You can reference the desired return address in the identification call using the mandatory index attribute associated with the address.

The return URL must use the HTTPS protocol. 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" />

The name of the e-service and the personal information requested

md: The AttributeConsumingService element contains the name of the e-service as well as a list of the information that the e-service requests for the user of Suomi.fi identification. Only one  AttributeConsumingService element is supported and it must contain the attributes index = "1" and isDefault = "true".

The name of the e-service is defined in the element md: ServiceName. The name should be in Finnish, Swedish and English. The name can be different from the name information displayed to the end user (mdui: DisplayName). The element is a mandatory sub element for 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>

The element md: RequestedAttribute defines the personal information requested by an identified user. The personal data available at the identification is always communicated. Both the data returned with Finnish identification tools and those returned with eIDAS identification tools can be listed side by side in the metadata.

Read more about the information communicated about identified users.

In the example below, the e-service requests personal identification 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>

To utilize the data in the population data system, a data permit is required. The Suomi.fi identification only transmits data according to the data permit level to the e-service. In the test environment, no data permit is needed. Read more about how to apply for the Identification data permit.

Identification without retrieving data from the population data system (allowing partal data in case the query to the population data system fails)

Suomi.fi identification queries the user's data from the population data system when an identification tool is used that returns the user's personal identification number.

The identification can be carried out without the information being checked if desired. This function is intended for emergency states where the data cannot be queried from the population data system due to a disturbance. In the implementation of the e-service, it must be taken into account that if the query fails, only the personal identification number and name information (cn) offered by the identification tool is communicated to the e-Service.

The functionality can be tested by entering 151070-9138 to the test identifier (... 110,999) in the test environment.

Identification in an disturbance without reviewing the data in the population data system is defined by giving the value VtjVerificationRequired the value "false". By default, the element is added to the metadata with the value "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>

Defining a dynamic return address

A dynamic return address for SAML2 communication can be used by specifying the skipEndpointValidationWhenSigned attribute value "true". Then the e-service can determine the return address to which SAML2 AuthenticationResponse is sent per request for identification.

Note that the definition in question applies only to the response to the AuthnRequest. LogoutResponse and LogoutRequest are always sent to the address defined in the metadata.

The use of the dynamic return address requires that different keys are used in SAML2 communication and in TSL data traffic.

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

Details of the organization requesting identification

The information for the organization that owns the e-service is specified in the element md: Organization. The information must be delivered in Finnish, Swedish and English versions. If any of the language versions are not used, the element can be given the same value as for example in the Finnish language 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>

Table 2. Details of the organization requesting identification.

E-service contact persons and information about the support service

The details of the e-service contacts are specified in the attribute md:ContactPerson. The types of contacts are

technicalsupportadministrativeother.

As a contact person, at least the technical contact person must be specified, but we hope that the contact information of the administrative contact person and the support services are also provided.

The following information is established for the contact person:

type of contactperson (technical, support, administrative or other)first name (special characters must be HTML-coded)surname (special characters must be HTML-coded)e-mail adresstelephone number (optional).

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