# Suomi.fi e-Identification
Service providers in the Finnish public sector are obliged to use the Suomi.fi e-Identification (opens new window) service to authenticate users. This service is one of the infrastructure services offered under the Suomi.fi umbrella. There are two use cases:
- Authentication-based signing: Signicat's integration to the Suomi.fi e-Identification service makes signing available to service providers in the Finnish public sector.
- Authentication: Many service providers in the Finnish public sector use platforms provided by Signicat partners. Signicat's integration to the e-Identification service makes authentication available as an integral part of these platforms.
Signicat can only provide the Suomi.fi e-Identification service to customers that are approved by DVV (opens new window) (the Digital and Population Data Services Agency). Customers must apply for authorization to use Suomi.fi e-Identification (for more details, see the Integration section). The test and preproduction environments are however accessible without prior approval by DVV.
# Key features
The integration makes Signicat services available to the Finnish public sector. Also, Signicat partners that provide platforms for public sector services can offer authentication as an integral part of their platform offering. Using this ID method integrated with Signicat's authentication-based signing, actors in the Finnish public sector are enabled to use advanced electronic signatures. In short, the Suomi.fi e-Identification service offers:
- Authentication by all approved eIDs in Finland at a substantial or high level of assurance (LoA).
- Authentication of foreign users through the Finnish "eIDAS node".
- Common user experience for authentication across public services.
- A rich set of information attributes can be returned and based on the population register.
- User consent to release these information attributes towards the specific service.
- Single sign-on and single logout (SSO/SLO).
Only service providers in the Finnish public sector can use Suomi.fi e-Identification, and for these providers, it is mandatory to use it for authentication.
# Use case
In the following scenario, a public service provider wants to authenticate a citizen:
- Signicat redirects the citizen to Suomi.fi.
- Suomi.fi shows the eID selection menu (see photo slider below).
- The citizen selects the preferred eID-method and authenticates with this method.
- Signicat returns the result of the authentication to the public service provider.
Here is an example flow of how the authentication may look with a test user:
The flow may vary depending on the selected ID method and how the service provider has implemented it. For example, the user may be prompted to give consent to release certain personal attributes to the service provider. Signicat by default asks for all available information (see Information fields) in our integration with Suomi.fi, but the metadata configured for the specific service provider (Signicat's customer) specifies the information to release. Some of this information may require consent.
# Single sign-on (SSO) and single logout (SLO)
Suomi.fi e-Identification uses SSO between services. Each time a user logs into a service using Suomi.fi e-Identification, an SSO session is created between the user's browser and Suomi.fi. If the user logs into another service during the lifetime of this session, the user is logged in "silently". The eID selection menu is then not shown, and the user is merely redirected back to Signicat with no user dialogue, except possibly consent to release attributes.
For Signicat, it is invisible if an authentication in Suomi.fi is by SSO or by explicit use of an eID. Usually, Signicat, and thus a service provider, may signal "force new authentication" to disable SSO for a specific authentication but this is not supported for Suomi.fi. This means SSO is used whenever possible.
Following a local logout at the customer's service, the customer may initiate an SLO request towards Signicat to log the user out from all other services entered in the SSO session in Suomi.fi e-Identification.
When another service provider in the same SSO session initiates an SLO request for a user, Signicat will receive an SLO request redirect from Suomi.fi. This request should be propagated to the customer to perform a logout for the user.
Single logout (SLO) is not a mandatory feature.
# Electronic signing
The eIDs available in the Finnish market do not support native signing. However, Signicat's integration with Suomi.fi e-Identification allows you to use Signicat's authentication-based signing. This signing method provides Advanced Electronic Signature (AES) according to the EU eIDAS regulation. This means that Signicat's integration to Suomi.fi e-Identification enables AES for service providers in the Finnish public sector.
# Use case
In this scenario, the public service provider sends a signing request to a citizen. This assumes the service provider uses Signicat Sign:
- The service provider sends a signing request to Signicat.
- The citizen is either redirected from the service to Signicat Sign (synchronous signing) or alerted that a signing request is waiting (asynchronous signing) at a specific link.
- The citizen accesses the sign request, opens the document(s) to sign, consents to sign.
- Signicat redirects to Suomi.fi e-Identification for the authentication. The authentication follows the same flow as shown in the above image slider, starting with the ID method selection screen.
- Upon successful authentication, the signing process is completed and the signed document is returned to the service provider.
The authentication-based signing can be illustrated as follows:
# Information returned from the service
The Suomi.fi e-Identification service authenticates the user by one of the commonly available Finnish eIDs (Finnish bank eID, Mobiilivarmenne or FinEID) obtaining the information returned from the authentication. This information, in practice the HETU (Finnish national ID number), is then used for a lookup in the population register to fetch more information. The information that can be returned is listed in the Result example section.
Tip: You can use a flag in the metadata to indicate that if the population register is not available, the service will still return information, limited to the attributes available from the eID that is used.
The returned information for a specific service is defined in the SAML metadata for the service based on the agreement between the service provider and DVV (opens new window). This may, in turn, be based on what the service owner is legally entitled to receive.
# Information fields
- Unique identifier (usually HETU, may be SATU that is a more temporary variant, or an eIDAS identifier)
- First names
- Preferred name
- Municipality of residence
- Permanent address in Finland
- Temporary address in Finland
- Postal address in Finland
- Permanent address abroad
- Mother tongue (language code)
- Mother tongue, classification Finnish/Swedish/Sámi/other
- Communication language
- Details of death
- Information about non-disclosure orders (meaning address information is blocked and cannot be handed out; address fields will be empty)
- Indication of whether or not the person is a Finnish citizen
- Email address
For a code example with returned metadata and values, see Result example.
# Security level
Suomi.fi supports all FTN eIDs: Banks, Mobiilivarmenne, variants of the Finnish ID card (FINeID), and even notified foreign eIDs through the eIDAS infrastructure. A service must select the required LoA from the Finnish LoA framework, either substantial (which is "strong electronic identification" according to Finnish law) or high, meaning that only FINeID and foreign eIDs at high can be accepted. To Signicat, the following applies:
- Signicat has a broker license at substantial LoA and can for authentication only serve customers that require substantial. A customer with a "high only" requirement for authentication (not very likely in Finland) cannot be served by Signicat.
- For authentication-based signing, it is assumed that also customers that require "high only" can be served. However, requiring this level is very unlikely in Finland.
When substantial LoA is required, Suomi.fi also allows using eIDs at level high. If a foreign eID is used, the assurance level may be indicated as an "eIDAS level" and not a Finnish level but the levels are treated on par with each other. For more details, see the technical descriptions on the Suomi.fi website (opens new window).
# How to integrate with Suomi.fi through Signicat
Before you can integrate through Signicat, you must register and apply for an access license for Suomi.fi. For more information about this, see the Suomi.fi's web site > Commissioning stages (opens new window) and Applying for an access license (opens new window). This application process may take 8-12 weeks. After the approval, you must sign the terms and conditions document directly with Suomi.fi.
Signicat can only serve customers with this approval in place. However, you can start testing before the approval is concluded (see Test information).
The integration is done via the same API as Signicat's other ID methods. Through the single point of integration, you will get access to Signicat's wide portfolio of integrated ID methods.
Suomi.fi e-Identification is based on SAML2 as the authentication protocol. Specifications are available on the Suomi.fi website (opens new window).
# Subject notice
Since Suomi.fi returns a transient (non-persistent) subject, this cannot be used for recognizing the end-user across authentications, as it will change for each authentication. This is also the case for the sub claim returned when using OIDC.
# Result example
subject.name AAdzZWNyZXQxJ3ZxU34lSHZOdxHkmC7QUX8n3x2zwZKhC2hcqDBLAGQgEG2JncJvLr2lR85cHpSbI/a+1UFXQVnBFGJIh9upj41P/09oYc6jIrG33z3fKfXosnOxy8388LaCo9Qkct+0xJF+pR6zcGU+dsYvq3Ffy7tVu/SMJZwlBtRI subject.format urn:oasis:names:tc:SAML:2.0:nameid-format:transient subject.nameQualifier https://testi.apro.tunnistus.fi/idp1 authentication.method urn:signicat:names:SAML:2.0:ac:SUOMIFI authentication.instant Thu Jul 02 09:13:35 CEST 2020 signicat.friendly-name SUOMI.FI signicat.service-name nbidmobile signicat.method-name suomi-fi-4 signicat.unique-id AAdzZWNyZXQxJ3ZxU34lSHZOdxHkmC7QUX8n3x2zwZKhC2hcqDBLAGQgEG2JncJvLr2lR85cHpSbI/a+1UFXQVnBFGJIh9upj41P/09oYc6jIrG33z3fKfXosnOxy8388LaCo9Qkct+0xJF+pR6zcGU+dsYvq3Ffy7tVu/SMJZwlBtRI signicat.session-index _6200495c428947cb84dd8f931f86e4a6 signicat.security-level 3 signicat.plain-name Nordea Demo signicat.national-id 210281-9988 signicat.nationality FI signicat.date-of-birth 1981-02-21 suomi-fi.authnContext urn:oid:184.108.40.2067.3002.110.999 suomi-fi.hetu 210281-9988 suomi-fi.commonName Demo Nordea suomi-fi.displayName Nordea Demo suomi-fi.givenName Nordea suomi-fi.surname Demo suomi-fi.firstNames Nordea suomi-fi.municipality Turku suomi-fi.municipalityNumber 853 suomi-fi.address Mansikkatie 11 suomi-fi.postalCode 20006 suomi-fi.postalOffice TURKU suomi-fi.finnishCitizen 1 suomi-fi.eidasFirstName Nordea
# SAML2 metadata for customers using Suomi.fi e-Identification
Each Signicat customer using Suomi.fi e-Identification must have separate SAML2 metadata set up in Suomi.fi. Concerning the SAML2 metadata (description in Finnish and Swedish only), this includes:
- Identification (URI/URN) of the service
- Assurance levels allowed for the service. LoA2 is always set, meaning "Finnish strong authentication", corresponding to eIDAS LoA Substantial.
- One or more X.509 certificates for the service. Two certificates issued to Signicat are always used, one for signing requests, the other for encryption.
- Logo and texts (Finnish, Swedish, English) to show in Suomi.fi for the authentication dialogue.
- Return address (default) for the authentication response. This is always a URI in Signicat's platform.
- Return address for SLO response. This is also a URI in Signicat's platform.
- Name of service in Finnish, Swedish, and English.
- Contact persons categorized in technical, support, administrative, other. This should include both Signicat and customer personnel as needed.
- Basic information on the organization requesting authentication, i.e. the customer, in the three languages.
- Requested identity attributes.
- Flag to indicate if authentication without verification towards the population register is accepted.
- Flag to indicate that a dynamic return address can be specified per SAML request. This is not used when integration is through Signicat.
# Test information
On the Suomi.fi website, you can find information about test users (opens new window). The test environment is open, meaning no access license is needed.
# More information
Technical descriptions of the integration in SAML2 are available on the Suomi.fi website (opens new window).