Configure Suomi.fi authentication
This configuration example has been tested by using Ubisecure SSO 8.8.1 and Suomi.fi in February 2022.
Ubisecure Identity Platform can be configured to use external Identity Providers for user authentication. The prerequisite is that the Identity Provider implements one of the protocols supported by Ubisecure Identity Platform, typically SAML2 or OpenID Connect. For the list of all supported protocols, please refer to Authentication methods - SSO.
Suomi.fi e-identification service is used by Finnish public sector organizations for strong user authentication. This article describes how Suomi.fi can be configured as an Identity Provider for Ubisecure Identity Platform by using SAML2 protocol. For the description of the Suomi.fi SAML2 interface, please refer to the Technical interface description.
Prerequisites
A user account for Suomi.fi Service Management is required for uploading your application information to the service. Note that it may take a few working days before your information is updated to the service and you can start using Suomi.fi authentication.
Before integrating to the Suomi.fi Identification production environment, your organization needs an Authentication License (Käyttölupa). Please refer to the instructions at https://palveluhallinta.suomi.fi/en/sivut/tunnistus/kayttoonotto/kayttoonoton-vaiheet. Technical integration to the test environment can be done without a license.
For integrating to the Suomi.fi Identification production environment, you need a public key certified by a known Certificate Authority (CA). Please follow the instructions at Management API - SSO for creating a Certificate Signing Request (CSR), send it to your CA and install the CA-provided certificate as instructed at Management API - SSO. The Suomi.fi test environment can be used with a self-signed certificate generated automatically by Ubisecure Identity Server.
The server compatibility flag MetadataCertificate must be set for your Ubisecure SSO, please see Add certificate to the SAML metadata for details.
Create Ubisecure SSO authentication method
Identity Providers are configured as authentication methods for Ubisecure Identity Platform. You can create authentication methods in Management user interface - SSO or by using Management API - SSO. In this article, we configure the authentication method in the Management UI. For examples on Management API usage, please refer to Use the Ubisecure SSO Management API with curl.
1. Create an authentication method for example with name suomi_fi.saml.1 and title Suomi.fi as follows:
Go to the tab Global Method Settings and click on New Method. Enter the title and name, and select SAML for the method type. If you are planning to link the Suomi.fi identity to your local user store, choose CustomerID Directory or other user directory based on your environment. The directory can also be left unspecified now and set later if needed.
2. Enable the method and add the following SAML Compatibility Flags, and click on Update:
Suomi.fi SAML compatibility flags
MessageDigestSHA256 IdpProxyDelegate SendAssertionConsumerServiceURL3. On the SAML tab, upload Suomi.fi Identity Provider metadata. Please check the Suomi.fi documentation for the correct metadata. At the time of writing, the metadata is available at the following addresses:
Production: https://tunnistus.suomi.fi/static/metadata/idp-metadata-tunnistautuminen.xml
Test: https://testi.apro.tunnistus.fi/static/metadata/idp-metadata.xml
You can either save the metadata to a file and upload it to Ubisecure SSO with the Choose file button, or choose view source from your browser tools and directly copy-paste the metadata to the Ubisecure SSO dialogue.
Create and upload Service Provider metadata
Download example metadata and edit fields marked as TODO based on information on your service and your contact details.
Define desired assurance levels, eIDAS authentication and user attributes based on your business needs, please refer to Suomi.fi metadata description.
Download SAML Service Provider metadata from your Ubisecure SSO authentication method and copy the following fields (marked as red in the example metadata below) to your Suomi.fi Service Provider metadata:
entityID
X509Certificate
AssertionConsumerService for HTTP-POST binding
SingleLogoutService for HTTP-POST and HTTP-Redirect bindings
<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="_6d42ef5960a27a20323f3785da4465bbc6f6480b" entityID="https://login.ubidemo.com:8443/uas/saml2/names/ac/suomi_fi.saml.1">
<md:SPSSODescriptor AuthnRequestsSigned="true" WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<md:KeyDescriptor use="signing"><ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:X509Data>
<ds:X509Certificate>
MIIHnTCCBoWgAwIBAgIMBmNjg/2tuTbD+KDAMA0GCSqGSIb3DQEBCwUAMFAxCzAJBgNVBAYTAkJF
...
e554d2tuOTuf54T3H/BXsHg24zGAtWqYALCwXQrb1r9zoH2mp0iO+N3uFM6F/2bRTJf2FHeQR2OH
WKv+OiNF+qfnq5R1g20w
</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo></md:KeyDescriptor>
<md:ArtifactResolutionService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="https://login.ubidemo.com:8443/uas/saml2/names/ac/suomi_fi.saml.1/soap/ArtifactResolutionService" index="0" isDefault="true"></md:ArtifactResolutionService>
<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://login.ubidemo.com:8443/uas/logout/suomi_fi.saml.1" ResponseLocation="https://test.ubidemo.com:8443/uas/logout/suomi_fi.saml.1"></md:SingleLogoutService>
<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://login.ubidemo.com:8443/uas/logout/suomi_fi.saml.1" ResponseLocation="https://test.ubidemo.com:8443/uas/logout/suomi_fi.saml.1"></md:SingleLogoutService>
<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact" Location="https://login.ubidemo.com:8443/uas/logout/suomi_fi.saml.1" ResponseLocation="https://test.ubidemo.com:8443/uas/logout/suomi_fi.saml.1"></md:SingleLogoutService>
<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="https://test.ubidemo.com:8443/uas/saml2/names/ac/suomi_fi.saml.1/soap/SingleLogoutService"></md:SingleLogoutService>
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://test.ubidemo.com:8443/uas/return/suomi_fi.saml.1/AssertionConsumerService" index="0" isDefault="true"></md:AssertionConsumerService>
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact" Location="https://test.ubidemo.com:8443/uas/return/suomi_fi.saml.1/AssertionConsumerService" index="1"></md:AssertionConsumerService>
</md:SPSSODescriptor></md:EntityDescriptor>
As a result, you should have your Suomi.fi Service Provider metadata file like the example below. In Suomi.fi Service Management, create a new e-service and upload your metadata. Monitor the state of your e-service until it is in the state "Published". This may take several days.
Create a group for Suomi.fi-authenticated users
In order to configure Suomi.fi authentication for your applications and services, a group is typically used. Create a group, for example Suomi.fi users as follows:
Now all users authenticating via Suomi.fi get Suomi.fi users group membership and it can be used in Authorization Policies for access configurations.
Using Suomi.fi authentication with your applications
There are 2 typical use cases for Suomi.fi authentication:
Identity verification for creating user accounts
Strong authentication when signing in to services
For identity verification, please refer to Protected CustomerID workflows for an example configuration.
For configuring Suomi.fi authentication for your applications, you have the following options:
Allow access to any user successfully authenticated via Suomi.fi
Locate a local user account by using the Social Security Number received from Suomi.fi and allow access based on your Authorization Policy settings
For allowing access to all Suomi.fi authenticated users, simply allow access for the Suomi.fi users group:
For mapping a Suomi.fi identity to a local user account, use Directory User Mapping with the following LDAP filter:
Directory User Mapping filter
(&(objectclass=ubiloginUser)(description={method:urn:oid:1.2.246.21}))Then allow access to the mapped identities, typically CustomerID users: