June 12, 2018

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

    image
  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.

    image
  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.

image


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.
image

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.

6 comments:

  1. Thanks for the well written and interesting article!

    ReplyDelete
  2. Hi,

    Thanks for the Article. I am trying to connect Suomi.fi with Salesforce environment and was wondering what would be the IDP Issuer & IDP Login URL for Suomi.fi !

    Do you have any insight on this ?

    ReplyDelete
    Replies
    1. IDP issuer is just a unique URI identifyint the issuer in Salesforce, you can e.g., use the entityId from the metadata (https://testi.apro.tunnistus.fi/static/metadata/idp-metadata.xml): https://testi.apro.tunnistus.fi/idp1.

      IDP login URL you can also get from the metadata: https://testi.apro.tunnistus.fi/idp/profile/SAML2/POST/SSO or https://testi.apro.tunnistus.fi/idp/profile/SAML2/Redirect/SSO depending if you do the login via post or redirect.

      Delete
    2. Thanks for the quick response.

      Have you uploaded your org metadata in the exact same format as defined here - https://palveluhallinta.suomi.fi/en/tuki/artikkelit/5a814d109ea47311bfd599a3 ? or was it somewhat different, then how ?

      I am having some trouble understanding some tags & confusion on how to populated certain tags marked with "TODO" or whether to keep them in the metadata ?

      Thanks.

      Delete
    3. If you ask more specifically, I can provide you with answer, don't want to copy&paste whole XML here.

      Delete
  3. Out of curiosity, have you taken such thing to production? Asking because, well, testing environment seems to accept self-generated certificate. For production use there is limited information available. Document says that certificate needs to be signed by trusted CA, but there doesn't seem to be any list of them :)

    So if you have bought certificate and got it approved, could you point me to the CA you bought it from? Also which level of certificate is needed; EV, OV, DV, something else.

    Thanks for reading this far.

    ReplyDelete