June 12, 2018

Suomi.fi e-identification using Auth0

As it states on the Suomi.fi e-Identification service page, “Suomi.fi e-Identification 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.”

Do note that the e-identification service is not for private sector use, so it’s only for governmental authorities, agencies and institutions, courts of law and other judicial bodies.

How to configure suomi.fi e-identification for Auth0 and test it towards their test environment? Let’s see.

  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 to keep 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:
  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 metadata URL at https://testi.apro.tunnistus.fi/static/metadata/idp-metadata.xml. Paste X509Certificate string into suomifitest.txt file, rename it into suomifitest.cer, and upload to Auth0.

  6. Sign Out URL, add the Single Log Out URL of suomi.fi:
  7. 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:, which is the National Identification Number of the user. You can find the other fields at https://esuomi.fi/palveluntarjoajille/tunnistus/tekninen-aineisto/tunnistetusta-kayttajasta-valitettavat-attribuutit/.
  8. Enable Sign Request, and download the certificate, you will use that later.
  9. Sign Request Algorith, set to RSA-SHA256.
  10. Sign Request Digest Algorithm, set to SHA256.
  11. Protocol Binding, set to HTTP-POST.
  12. Request Template you can leave as-is.
  13. 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:",
       "family_name": "urn:oid:"

That was easy, right? Final step is to contact suomi.fi and let do some paperwork, most impotantly from a technical perspective is to send them description of your service, i.e., the SAML Metadata.

For that you will need to decide what authentication methods you want to support (bank, mobile, etc.), what 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.

EntityID, SingleLogoutService, AssertionConsumerService, and other details 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.


After that you’re all set and can test the authentication by pressing the PLAY button next to the Enterprise Connection, and you should find yourself from the authentication method selection screen, and eventually back in Auth0.

No comments:

Post a Comment