Suomi.fi e-identification using Auth0

Suomi.fi e-Identification is a "joint identification service for public administration in Finland. Customer organisations can use the service to identify end-users in their own digital services." It enables the citizens of Finland and the European Union to be recognized in a safe way by using various identification media such as bank-id and mobile certificates.

As suomi.fi authentication offers user authentication service across SAML 2.0 compliant interface, and Auth0.com supports SAMLP Identity Providers, configuring the two shouldn’t be too much of a problem.

Configuring Auth0

These steps will assist you in configuring Auth0 towards suomi.fi test environment. Steps for production environment are mostly the same, but there are few additional steps related to certificates.

1. Register for Auth0 tenant (https://auth0.com), Trial will work just fine for this test scenario
2. Add suomi.fi as SAMLP Identity Provider at Connections –> Enterprise –> SAMLP Identity Provider
   
   
3. Type in Connection name. It can be anything, but I suggest keeping it short and without special characters. I call it suomi-fi-test
4. For Sign In URL, type in the POST signin URL endpoint of suomi.fi test environment:
   https://testi.apro.tunnistus.fi/idp/profile/SAML2/POST/SSO
5. For X509 Signing Certificate upload the suomi.fi (which is IdP in this case) public key, so basically suomi.fi will sign the outgoing messages with their private key, and here you define the corresponding public key to verify the message signature.
   
   You can get the certificate from suomi.fi IdP metadata URL at https://testi.apro.tunnistus.fi/static/metadata/idp-metadata.xml from the ds:X509Certificate element.
   
   
6. Paste X509Certificate string into *.txt file, add certificate markers -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- (required by Auth0), rename file to *.cer, and upload to Auth0.
7. Sign Out URL, add the Single Log Out URL of suomi.fi, which you will also find from the IdP metadata in step 5:
   https://testi.apro.tunnistus.fi/idp/profile/SAML2/POST/SLO
8. User Id Attribute you can decide what user data returned by suomi.fi is considered as the user identificator in Auth0, I’m using urn:oid:1.2.246.21, which is the National Identification Number of the user. You can find the other fields here.
9. Enable Sign Request, and download the certificate, you will use that later.
10. Sign Request Algorithm, set to RSA-SHA256.
11. Sign Request Digest Algorithm, set to SHA256.
12. Protocol Binding, set to HTTP-POST.
13. Request Template you can leave as-is.
14. On the Mappings tab (at the top), I map user name details so user list in Auth0 is more convenient to manage:
    {
       "name": "urn:oid:2.16.840.1.113730.3.1.241",
       "given_name": "urn:oid:2.5.4.42",
       "family_name": "urn:oid:2.5.4.4"
    }

Creating SAML Metadata

Final step is to contact suomi.fi and do some paperwork, most importantly from a technical perspective is to send them description of your service, i.e., the SAML Metadata.

In SAML Metadata you define things like

• authentication methods you want to support (bank, mobile, etc.)
• user details you would like to get back from suomi.fi after authentication (e.g., National Id of the user, name, address)

You will also need to include the public Auth0 signing certificate you downloaded earlier in step 8.

It is recommended to start from this sample SAML Metadata, and modify it accordingly.
EntityID, SingleLogoutService, and AssertionConsumerService you can get from Auth0 Setup Instructions page by clicking on the Pen button after creating the Enterprise Connection.



NOTE! Before sending the metadata to suomi.fi, you should validate it at https://www.samltool.com/validate_xml.php by pasting the metadata into the XML field, selecting Metadata for XSD. This will save you some time and effort as the metadata won’t bounce back at least due to trivial syntax errors.


After metadata has been configured in suomi.fi environment, you’re all set and can test the authentication by pressing the PLAY button next to the Enterprise Connection in Auth0.

Browser should redirect you to the authentication method selection screen in suomi.fi, and eventually after successful authentication back in Auth0 together with the user details (claims) you defined in SAML Metadata.