Skip to content

giosg Suomi.fi

suomi.fi logo

Info

This functionality is only available as separately sold product. Please contact us at sales@giosg.com in order to get more information.

Overview

giosg Suomi.fi is a separately sold product, which allows our Customers to use Suomi.fi identification and acting on behalf of a person functionality. This means that you can reach a wider audience and provide your services more efficiently and conveniently.

Suomi.fi introduction

Suomi.fi identification is the secure and convenient way to verify your identity online in Finland. With Suomi.fi identification, you can easily and securely access giosg provided services that require identity verification.

With Suomi.fi and giosg, you can:

  • Offer your services online through a secure and convenient platform
  • Reach a wider audience and increase your customer base
  • Save time and effort by providing your services online, without the need for in-person visits

As a Visitor you can:

  • Verify your identity online using a secure and convenient e-ID
  • Access giosg services with just one set of login credentials
  • Save time and effort by avoiding the need to go call government offices or health care in person

Prerequisites

Customer account must have Interaction Builder and Workflow Builder enabled and giosg script added to the website giosg - How does the v2 giosg script work.

Customer needs to request e-Identification and e-Authorizations services from Palvelunhallinta - Suomi.fi.

e-Authorizations

Suomi.fi configuration must have following redirect urls defined (this configuration change is requested from valtuudet-kayttoonotot@dvv.fi): 

1
2
3
https://suomifi.giosg.app/behalf/callback/hpa
https://suomifi.giosg.app/behalf/callback/ypa
https://suomifi.giosg.app/behalf/callback/hpalist

e-Identification

Metadata.xml should have following giosg-specific additions:

entityID, which point to giosg owned url and contains ${config_id_from_giosg_suomifi_setup} which is automatically generated during suomifi App setup. 

1
        entityID="https://suomifi.giosg.app/${config_id_from_giosg_suomifi_setup}"

callback urls: 

1
2
3
<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://suomifi.giosg.app/auth/logout/callback" />
<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://suomifi.giosg.app/auth/logout/callback" />
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://suomifi.giosg.app/auth/login/callback" index="1" isDefault="true" />

X509 sertificate which is provided by giosg: 

1
<ds:X509Certificate>

Info

Please contact us at support@giosg.com in order to get help for creating metadata specific to your usecases.

Reference/demo suomi.fi implementation

Suomi.fi demo can be used for demoing and as an reference for Customer implementation. We are also using this as an example when explaining setup on next chapter.

Setting up Suomi.fi

Install Suomi.fi App

At first Suomi.fi app must be shared from Giosg Integrations and Apps account to Customer account. This is done by giosg. After this, you can find app as part of the Settings -> Apps.

suomifi_giosg_app

After the installation, you should be able to configure your first suomi.fi setup:

Field Description
Id Automatically generated Config id
EntityId suffix Uuid. Used as unique suffix for metadata's entityID
Env Type This defines which suomi.fi environment is used (TEST or PROD)
Name Name of this configuration. Should be something which clearly defines the usecase.
Default Locale Default locale used in suomi.fi, if not provided as part of identification start request. Options are ('fi', 'en' or 'sv')
Authentication Workflow Uuid Uuid of the workflow which is called after successfull identification
Authentication Fail Workflow Uuid Uuid of the workflow which is called after failed identification
Logout Workflow Uuid Uuid of the workflow which is called after successfull logout from Suomi.fi
Logout Fail Workflow Uuid Uuid of the workflow which is called after failed logout from Suomi.fi
Acting Behalf client ID Cliend Id used for acting behalf (e-Authorizations)
Acting Behalf client Secret Cliend Secret used for acting behalf (e-Authorizations)
Acting Behalf Api key Api key used for acting behalf (e-Authorizations) API calls
Acting Behalf authorization roles List of things (matters) that the main authenticated person has the right to act behalf of. More information can be found in Finnish from this article

Configure interaction

Suomi.fi identification is activated from interaction. This interaction can be opened to the page or it can be sent by the chat agent during chat conversation. giosg Suomi.fi supports both usescases.

As an example we are using following interaction (account id: 7944):

suomifi_interaction

Interaction has following custom js action configure to the button, which starts the identification:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
(function suomiFiOpener(winParams) {
  window.open(
    "https://suomifi.giosg.app/auth/login?identifier=" +
      encodeURIComponent(document.location.search.match(
        /(chat_id=[\da-fA-F]{8}(\-[\da-fA-F]{4}){3}\-[\da-fA-F]{12}){1}/
      )[0] +
      "&" +
      document.location.search.match(/(visitor_id=[\da-fA-F]*)/)[0]) +
      "&" +
      Object.keys(winParams)
        .map(function (key) {
          return key + "=" + winParams[key];
        })
        .join("&"),
    "_top"
  );
})({
  config_id: "167e1364-a70c-421a-bd58-98641382c013",
  referrer_url: $i.dataFields.referrer_url,
  act_behalf: false,
  locale: 'en'
});
Parameter Description
locale Defines locale used in suomi.fi ('fi', 'en' or sv). If not provided, then default locale used from configuration.
config_id This defines which suomi.fi environment is used
act_behalf If set to true, the act_behalf is also exacuted as part of the flow.
referrer_url Return url after identification. Recommended to use the same page url from where the visitor started the identification
identifier Unique identifier for the user/session, which is passed to the workflows without changing the content. This could be for example chat_uuid & visitor_uuid.

Configure workflows

Following workflows can be used as reference for the Customer specific workflows (account id: 7944):

Succesfull authentication workflow will receive following trigger payload. Person1 is the person who has done the authentication and the person2 contains kids or someone elses information if the person1 is acting behalf of person2. Identifier is passed without changes from interaction. act_behalf is true if person2 information exists.:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
"person1": {
    "social_sec_number": $social_sec_number,
    "email": $email,
    "first_name": $first_name,
    "last_name": $last_name,
    "given_name": $given_name,
    "home_town": $home_town,
    "home_address": $home_address,
    "post_office": $post_office,
    "zip_code": $zip_code,
},
"person2": {
    "social_sec_number": $social_sec_number,
    "name": $name,
},
"act_behalf": $act_behalf,
"identifier": $url_decoded_identifier_value,
"locale": $locale

Failed authentication workflow is used when authentication callback or acting behalf callback fails and it will receive following parameters as payload: 

1
2
3
"identifier": $url_decoded_identifier_value,
"locale": $locale,
"login_callback_failed": False,  # False or True depending if authentication or acting behalf callback failed

Logout (success & fail) workflows will only receive indentifier and locale parameters as payload: 

1
2
"identifier": $url_decoded_identifier_value,
"locale": $locale

Info

Workflows can populate 'referrer_url_hash' variable. This variable is added to original 'referrer_url' provided by interaction.

Used domain(s)

giosg Suomi.fi uses suomifi.giosg.app. See Giosg's Domains and IP addresses document for extra information.

Additional info

Please contact us at support@giosg.com in order to get more information.