Skip to main content

How-to: Suomi.fi

This document describes how to setup Suomi.fi authentication for Trivore ID. Suomi.fi user directory can be used to login to Trivore ID or it can be used only for strong identification.

Configure Trivore ID​

Basic configuration​

Login in to your Trivore ID instance and select the namespace where you want to create user directory. Only users in the selected namesapce can use Entra ID user directory for login purposes. Also, users are automatically created in the selected namespace, if creating new users is allowed.

Navigate to "User directories" in main menu and click "Add directory"

Image

This will open a new dialog where you can select the type of user directory to add. Click "Suomi.fi".

Image

SP entity ID is one the most important fields. Its value should be Trivore ID instance URL and it MUST be unique. If you have multiple Suomi.fi user directories in your Trivore ID, you can append some path component to the URL. For example:

The URL does not need to give any response when queried, it simply MUST be unique because Suomi.fi uses this SP entity ID to uniquely identify the service provider.

Default values for following fields are usually fine:

  • Require response signature (you can select this if you want, Suomi.fi always signs the response message)
  • Require assertion signature (selected by default, Suomi.fi signs the assertion)
  • Require assertion encryption (you can select this if you want, Suomi.fi always encrypts assertion)

Image

Next, you need to generate private key and certificate that are used for authentication request signatures and response encryption. Suomi.fi basically accepts any certificate (even validity dates are ignored) so you can use, for example, openssl to generate self-signed cerfificates.

IDHOST=id.example.com
openssl genrsa -out mykey.pem 4096
openssl req -x509 -new -key mykey.pem -out mycert.pem -days 36500 -subj "/CN=$IDHOST/"

Change IDHOST value as appropriate for your environment. These commands will generate two files: mykey.pem and mycert.pem. Copy-paste the content of these files to the user-interface fields "SP private key" and "SP certificate". Generated certificate is valid for 100 years.

Suomi.fi officially recommends using proper certificates and changing them periodically but this is not enforced. Beware that this policy may change in future.

Click the link "Download automatically generated SP metadata" and save it to a file. You will need this metadata later on.

Next, you need to download Suomi.fi IdP metadata and copy-paste it to the field "IdP metadata XML". You can download Suomi.fi IdP metadata from following URLs:

Image

Save the changes. If you only need Suomi.fi for strong identification (as opposed to signing in), you can continue to section Configure Suomi.fi. Otherwise see section User information.

User information​

If your users need to be able to login to Trivore ID using Suomi.fi (as opposed to strong identification only), you need to enable user directory linking.

  • Select "Link user with directory"
  • Unselect "Use NameID based linking". Suomi.fi uses transient NameID values that are not suitable for linking.
  • Most probably you want to use personal identity code for linking. Therefore, insert value urn:oid:1.2.246.21,http://eidas.europa.eu/attributes/naturalperson/PersonIdentifier to the "Link ID" field.
  • Select "Encrypt link ID using salted hash algorithm" because personal identity codes should not be saved to database without encryption.
  • You may want to select "Allow creating new users" also if you want to enable Suomi.fi login for any user and automatically create user account for them.
  • Select "Allow users to change password" if you want to enable login to Trivore ID with password. If not selected, users will always need to use Suomi.fi for signing in because they are not able to set their password.
  • Recommendation is to use "Automatic namespace username policy" for usernames. If your namespace policy does not supported automatic usernames, random SHA-1 hash is generated for username.
  • You can use attribute urn:oid:2.16.840.1.113730.3.1.241 for "Friendly name".

Image

Dynamic linking​

If you have existing users in Trivore ID namespace and your users already have personal identity code and you want to enable Suomi.fi authentication for all them, you can use dynamic linking to achieve that. Dynamic linking can link Suomi.fi accounts with Trivore ID accounts by comparing personal identity codes.

If you do not configure dynamic linking, your existing users need to manually link their accounts with Suomi.fi by using "Link my account with another account" button in Trivore ID dashboard ("Verify your identity" button also works). Otherwise, Suomi.fi login creates new user account (if allowed by settings).

Image

Select "Allow dynamic linking to existing users" to enable dynamic linking.

In rare cases, dynamic linking may find several Trivore ID accounts that match Suomi.fi credentials. If you want to enable dynamic linking in this scenario, you also need to select "Allow dynamic linking to multiple users". When selected, users are able to select which account they want to use when signing in to Trivore ID.

"Dynamic linking attribute" defines which Suomi.fi attribute is used for dynamic linking. Value of this attribute is compared to Trivore ID account. Usually, this attribute is personal identity code urn:oid:1.2.246.21,http://eidas.europa.eu/attributes/naturalperson/PersonIdentifier.

"Dynamic linking user field" defines which Trivore ID account field is used for comparison with Suomi.fi account attribute (dynamic linking attribute). Common use-case is to use "Personal identity code (any)" but you can also limit comparison to legal or strong identification personal identity code if needed.

Configure Suomi.fi​

First step in configuring Suomi.fi is to enrich the previously downloaded SP metadata XML file according to instructions available at https://kehittajille.suomi.fi/services/e-identification/how-to-implement-the-technical-setup-of-the-identification-service/metadata/creating-metadata-for-the-e-service. Open the XML file in your favorite text editor and add all required information to it. Future versions of Trivore ID may provide better support for automatically generating SP metadata XML that is suitable for Suomi.fi and this manual editing is no longer needed.

Full metadata example is available at https://kehittajille.suomi.fi/services/e-identification/how-to-implement-the-technical-setup-of-the-identification-service/metadata/template-for-the-e-service-metadata-file

Next step is to login to Suomi.fi service management at https://palveluhallinta.suomi.fi (assuming that you have credentials to this service. If not, ask your administrator for access rights). After login, click "Go to the identification administrative interface".

Image

If you have already created e-service, continue to Register environment. If not, add new e-service first.

Image

Add e-service​

Add new e-service by filling in the required fields: name and description of your service in Finnish, Swedish and English.

Image

Image

After filling in all required information, click "Add e-service" button and then click "Register or update the environment" button and continue to next section.

Image

Register environment​

Select appropriate Suomi.fi environment (testing or production) and your e-service environment which can be development, testing, acceptance test or production.

Image

Note that in order to use production environment, you need approved application first. Registering approved application is outside the scope of this document. Suomi.fi testing environment does not need approved application.

Image

Next step is to either upload SP metadata file or copy-paste it to field show below.

Image

Click "Save environment" and your Suomi.fi integration is ready. Note that initially your environment is waiting for review. This may take a day or two and you cannot use the integration before it is accepted and published.

Image