# eID - Finland
FTN (Finnish Trust Network) and MobileID (Mobiilivarmenne)
## Overview
FTN and MobileID are widely-adopted electronic identification (eID) solutions in Finland, offering secure and convenient authentication methods for citizens, businesses, and public institutions. Both solutions enable users to access a wide range of online services, including banking, e-commerce, government portals, and healthcare services.
FTN is provided by banks operating in Finland and relies on a combination of a unique user ID, a personal password, and one-time codes generated through a security device or online banking service. This eID solution is integrated into various online services, ensuring secure authentication and transactions.
MobileID is an eID solution that utilizes a mobile device and a SIM card with an integrated digital certificate. It requires users to enter a personal identification number (PIN) for authentication. MobileID provides a secure and user-friendly method for online identification without the need for additional hardware or software.
Both FTN and MobileID play vital roles in ensuring the privacy and safety of users' online transactions, offering secure and seamless authentication experiences across various sectors in Finland.
## API Overview
### Core Functionalities
**Environments**
We provide two environments for use:
Test: https://test.zignsec.com/v2/
Production: https://api.zignsec.com/v2/
#### Authentication
Each request to our API should be authenticated by sending your api key in the “Authorization” header. Our support creates api keys for you (a pair for each environment), and it’s highly recommended to regularly rotate the keys (currently it’s done by sending a support request, but please let us know if you’d like to automate it).
### REST API
##### Headers
| Header | Description | Required |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| Authorization | This header parameter is the api key you received from ZignSec during the registration process. Example: Authorization: 123456add0cff22873c428e987654321 | Yes |
| Content-Type | Specifies the media type of the request body data. Set to application/json if JSON object. | Yes |
#### API Endpoints
##### Authentication
**Endpoint:** POST /eid/fbid
**Description:** This API endpoint allows for identity verification using the FTN/MobileID in Finland. The API facilitates user authentication, providing secure verification based on Finnish national identity standards.
**Endpoint:** GET /eid/{sessionId}
**Description:** This API endpoint retrieves the status and details of a FTN/MobileID identity verification session in Finland. It allows you to check the outcome of a previously initiated verification request.
### Call Sequence
#### 1. Session Setup
After making the setup call, you'll receive a redirect_url. This is for initiating the browser-based login, identified by sessionid.
##### Request example
``` bash
curl --location 'https://test.zignsec.com/v2/eid/fbid' \
--header 'Content-Type: application/json' \
--header 'authorization: Api-Key' \
--data '{
"language": "en",
"relaystate": "my-internal-user-id",
"target": "https://google.com?q=success",
"targetError": "https://google.com?q=error",
"webhook": "https://webhook.site/zignsec",
"method": "saml.op.1"
}'
```
##### Request Parameters
| Parameter | Description | Required |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| language | The language preference. Supported values: `en` (English), `sv` (Swedish), `fi` (Finnish). | No |
| relaystate | Internal user identifier used for session tracking. | No |
| target | The URL to redirect upon success (`https://google.com?q=success`). | No |
| targetError | The URL to redirect upon failure (`https://google.com?q=error`). | No |
| webhook | The webhook endpoint to receive event notifications (`https://webhook.site/zignsec`). | No |
| method | Chose one or more authentication methods: `mpki.telia.1 oidc.aktia.1` If only one authentication method is included then identification broker service initiates that authentication method automatically, if available. If no authentication method is indicated default method is used. | No |
#### Finnish Trust Network (FTN) authentication methods
| Method | Name |
| ---------------------- | ---------------- |
| `mpki.telia.1` | Mobiilivarmenne |
| `oidc.aktia.1` | Aktia |
| `oidc.alandsbanken.1` | Ålandsbanken |
| `oidc.danskebank.1` | Danske Bank |
| `oidc.handelsbanken.1` | Handelsbanken |
| `oidc.nordea.1` | Nordea |
| `oidc.omasp.1` | Oma Säästöpankki |
| `saml.op.1` | Osuuspankki |
| `oidc.pop.1` | Pop Pankki |
| `oidc.sp.1` | Säästöpankki |
| `oidc.spankki.1` | S-Pankki |
| `oidc.hightrust.id.1` | Hightrust.id |
#### 2. Login Workflow Execution
To start, navigate to the provided redirect_url in your web browser. The exact user interactions differ by country and bank and might even necessitate an external device. If you prefer, embed the URL in an HTML IFrame for a more integrated web experience. Concurrently, an eID session will be initiated client-side with JavaScript.
##### Response
``` json
{
"id": "08d0382b-d429-4563-a704-776493bf57f7",
"errors": [],
"redirect_url": "https://tunnistus-pp.telia.fi/uas/oauth2/authorization?response_type=code&scope=openid&client_id=7fb547fc-48d2-40d7-93e4-ae9a3c90aecc&redirect_uri=https:%2f%2ftest.zignsec.com%2fv2%2fcallback%2foidcfi&state=08d0382b-d429-4563-a704-776493bf57f7&ui_locales=en"
}
```
#### 3. Retrieve Status/Results
To gather details about the logged-in individual, use the unique sessionid from the workflow. Fetch the data during or post-workflow completion. The process may notify you of the status, like pending, completed, or error through a browser redirect to a specified URL, a set webhook, or via JavaScript through the Window.postMessage() event.
##### Request example
``` bash
curl --location 'https://test.zignsec.com/v2/eid/08d0382b-d429-4563-a704-776493bf57f7' \
--header 'Content-Type: application/json' \
--header 'authorization: Api-Key' \
--data ''
```
Notifications on Workflow Completion
You can be alerted both actively and passively once the workflow concludes:
- Callback: Specify the Target URL during the first step. Once this URL is accessed, follow the collect-GET mentioned above.
- Webhook: To designate a webhook URL for callbacks, liaise with ZignSec. Results will then be sent to the given URL.
- Polling: Consistently call the collect-GET until the end result appears.
##### Result Response
``` json
{
"id": "87fef88b-236b-49ce-b243-affd04ca6985",
"errors": [],
"relaystate": "my-internal-user-id",
"identity": {
"CountryCode": "FI",
"FirstName": "Tero Testi",
"LastName": "Äyrämö",
"FullName": "Tero Testi Äyrämö",
"PersonalNumber": "010170-999R",
"DateOfBirth": "1970-01-01",
"Age": 54,
"Gender": null,
"IdProviderName": "BankIDFI",
"IdentificationDate": "2024-09-24T11:42:42.5005886Z",
"IdProviderRequestId": "",
"IdProviderPersonId": "",
"CustomerPersonId": ""
},
"FBID": "{\"sub\":\"PFPIK7C5GJQT7XNX5SZISVTVOLJWAOF2\",\"iss\":\"https://tunnistus-pp.telia.fi/uas\",\"aud\":[\"7fb547fc-48d2-40d7-93e4-ae9a3c90aecc\"],\"exp\":1727181758,\"iat\":1727178161,\"auth_time\":1727178157,\"acr\":\"oidc.aktia.1\",\"amr\":[\"https://tunnistus-pp.telia.fi/uas/saml2/names/ac/oidc.aktia.1\"],\"azp\":\"7fb547fc-48d2-40d7-93e4-ae9a3c90aecc\",\"session_index\":\"_f8f47475dacab8f58ab0dde62e0379c8eab5e6bd\",\"urn:oid:1.3.6.1.5.5.7.9.1\":[\"1970-01-01\"],\"urn:oid:1.2.246.21\":[\"010170-999R\"],\"urn:oid:2.5.4.4\":[\"Äyrämö\"],\"urn:oid:1.2.246.575.1.14\":[\"Tero Testi\"],\"urn:oid:2.16.840.1.113730.3.1.241\":[\"Tero Testi Äyrämö\"],\"PersonIDHash\":[\"47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=\"],\"bank-tupasid\":[\"400\"]}",
"method": "fbid",
"result": {
"identity": {
"state": "FINISHED"
}
}
}
```
##### Response Parameters
| Parameter | Description |
| ------------------- | ----------------------------------------------------------------------------------------- |
| id | A unique session identifier generated for each workflow instance. |
| errors | A JSON array of error conditions, see error handling. |
| relaystate | Internal user identifier used for session tracking. |
| Identity | A verified identity of the customer, containing the following details. |
| state | Indicates the verification status. Values: PENDING, FINISHED, ERROR. |
| CountryCode | ID provider’s country/nationality. |
| FirstName | Extracted first name from ID provider. |
| LastName | Extracted last name from ID provider. |
| PersonalNumber | Finnish social security number |
| DateOfBirth | Date of birth of person format yyyy-mm-dd (year-month-day) |
| Age | Computed from DateOfBirth. |
| IdProviderName | ZignSec’s name for the Identity provider. |
| IdentificationDate | Time the identification was performed. |
| IdProviderRequestID | Unique ID from the identity provider for the request. Not present for this product |
| IdProviderPersonID | Technical key uniquely identifying the authenticated person. Not present for this product |
| CustomerPersonID | Customer specific reference for the person. Not present for this product |
| method | Name of the initiated method, e.g. “fbid”. |
| result | An object that describes the main result of the service call. |
### Error Handling
ZignSec´s REST APIs have a general return object format that includes an `errors` field. This field contains an array of error objects, each of which has two fields, `code` and `description`.
| Property | Type | Description |
| ----------- | ------ | -------------------------------------------------------------------------------- |
| code | string | A code indicating what type of error occurred. |
| description | string | A descriptive error message (in English) indicating what type of error occurred. |
##### Example of a returned error:
``` json
{
"errors": [
{
"code": "INVALID_APPID",
"description": "Authorization header is missing"
}
]
}
```
##### Error Codes
The following is a list of error codes that may be generated by the ZignSec API
| Error code | Description |
| ------------------- | -------------------------------- |
| INVALID_APPID | Invalid AppID |
| INVALID_ADDRESS | Invalid address |
| INVALID_REQUEST | Request is invalid |
| INVALID_METHOD | Method is invalid or not allowed |
| INVALID_TARGET | Target URL is invalid |
| INVALID_TARGETERROR | TargetError URL is invalid |
| INVALID_WEBHOOK | Webhook URL is invalid |
| SESSION_NOT_FOUND | Session not found |
## Testing
##### In web browser
Use either of the following test user:
| Bank | User name | Password | OTP | Name | SSN |
| ---------------- | --------- | --------- | --------- | --------------------- | ----------- |
| Osuuspankki | 12345678 | Prefilled | Prefilled | Väinö Tunnistus | 070770-905D |
| Nordea | DEMOUSER1 | None | None | Onni Juhani Korhonen | 010200A9618 |
| Nordea | DEMOUSER2 | None | None | Aino Olivia Virtanen | 291292-918R |
| Nordea | DEMOUSER3 | None | None | Eino Ilmari Mäkinen | 030883-925M |
| Nordea | DEMOUSER4 | None | None | Helmi Aurora Nieminen | 170677-924F |
| Danske Bank | 78985110 | 4545 | None | Teemu Antero Testaaja | 280453-111A |
| Handelsbanken | 11111111 | 123456 | 123456 | Testaaja Teemu | 010100A001N |
| Ålandsbanken | 12345678 | 123456 | 1234 | - | - |
| S-Pankki | 12345678 | 123456 | 1234 | - | - |
| Aktia | 12345678 | 123456 | 1234 | Tero Testi Äyrämö | 010170-999R |
| POP Pankki | 11111111 | 123456 | - | Testaaja Teemu | 010100A001N |
| Säästöpankki | 11111111 | 123456 | - | Testaaja Teemu | 010100A001N |
| Oma Säästöpankki | 11111111 | 123456 | - | Testaaja Teemu | 010100A001N |
##### Testing from mobile
To test your solution, you can use real user data or the **Mobiilivarmenne (test)** setup. This requires custom provisioning to a Telia SIM card or installing the Mobiilivarmenne test mobile app provided by **Elisa** or **DNA**.
##### Production testing
There are no test users available for the production environment. Merchants who wish to conduct tests in staging areas using the production environment will need to use real users.