Suomi.fi e-Identification

Suomi.fi e-Identification is a joint identification service for the Finnish public sector. Your organization can use the service to identify users in your own digital services.

1. Prerequisites

This process requires:

• Access license for the Suomi e-Identification service.

2. Configure Suomi.fi e-Identification in the Identity Broker

1. On the Identity providers page, select Add identity provider, and then select SAML.

   

   In a typical scenario, you provide these details:

   • Display name: Enter a name, such as Suomi.fi e-Identification
   • Active: Select the check box.
   • Identity provider metadata: Select Dynamic from URL

   • Metadata URL: Enter the relevant URL for your environment and click Load.

     Environment	URL
     test	https://static.apro.tunnistus.fi/static/metadata/idp-metadata.xml
     production	https://tunnistus.suomi.fi/static/metadata/idp-metadata.xml

   • Entity ID (service provider): Enter your tenant's domain in this format: https://<tenant-domain>/

   • Authentication request binding: Select HTTP POST.
   • Preferred authentication response binding: Select HTTP POST.
   • Signing key pair: Leave empty, so it is generated.
   • Encrypted Assertion: Select the check box.
   • Encryption key pair: Leave empty, so it is generated.
   • Enable Mutual TLS: Do not select the check box.
   • Single logout: Select the check box.

2. In the Variants section, enter a Variant name, such as Authentication. You always need at least one variant.

3. Save the configuration to generate the keys.

4. Reopen the configuration and manually change the key ID of the encryption key to match the key ID of the signing key.

   Both key IDs must be identical because Suomi.fi e-Identification permits only one certificate to be included in the service provider (SP) metadata that is generated for this IDP (Step 3).

3. Manually generate the metadata

After you save the configuration, the Identity Broker generates the SP metadata.

1. To access this file, on the Identity providers page, select the menu for the Suomi.fi e-Identification IDP, and then select View details.

   On this details page, you can see the key Metadata URL (service provider) with some URLs.

2. Open the URL that matches the Entity ID (service provider) from Step 2.

   The Suomi.fi e-Identification integration requires more specific fields, so you need to generate the metadata manually with a tool.

3. Open the Suomi.fi metadata generator.

   

4. Select the Environment Type that matches the Metadata URL from Step 2.

5. Select the required Data Permit Level.

6. In the ServiceProvider (SP) details section, in the Entity ID field, enter the same value as the Entity ID (service provider) from Step 2 (it must be an exact match).

7. Enter the required DisplayNames.

8. Enter the Public part of the x.509 certificate:

   • In the Metadata URL (service provider) for the IDP you just created, search for the <md:KeyDescriptor use="signing"> element that contains the <ds:KeyName>current</ds:KeyName>.

   • Nested in that element you can find the <ds:X509Certificate> element. Copy that value into the Public part of the x.509 certificate box.

9. For the Single Logout address, select POST and enter the URL in this format: https://<tenant-domain>/broker/slo.

10. For the SingleSignOn POST, enter the URL in this format: https://<tenant-domain>/broker/authentication/callback.

11. Click Generate XML and save the file, because you need it in the next step.

4. Add e-services at the Suomi.fi interface

In the administration interface of Suomi.fi, you can add e-services within your organization.

1. In the Suomi.fi administration interface, create an e-service for your Suomi.fi e-Identification service.

   The e-service's data contains the name of the e-service and a description of its operations.

2. Register one or more environments for the service you created, such as for testing or for production.

   Use the metadata file that you generated in Step 3.

You can find more detailed information on the Suomi.fi e-Identification site.

5. Test Suomi.fi in their test environment

In the Suomi.fi e-Identification test environment, you can use the test tokens provided by banks as well as the Suomi.fi e-Identification service's test token. Read more about the test tools.