Authentication REST API
This guide shows you how to integrate with FTN using Signicat Authentication REST API as an authentication protocol.
Prerequisites
- Follow the steps on the Initial preparations page to establish a connection with FTN.
-
Before you can start making requests to the Authentication REST API, you need to learn how to connect to it. To do this, see Connect to Signicat APIs Quick start guide.
Want to learn more?To learn more about the Signicat Authentication REST API, see:
- Authentication REST API for conceptual documentation.
- API Reference for endpoint descriptions.
Implement the authentication flow
1. Build the authentication request (Create a new session)
This section describes how to make an HTTP POST request to the /sessions endpoint, to create a new session and start an authentication.
To begin the authentication flow, your application must first start a session by utilising the /sessions endpoint. The endpoint automatically creates a session when you send a request. The flow and resulting information from the transaction depends on the parameters you pass in the body.
The response from this endpoint contains an authentication URL, to which you can embed in an iframe and present to the end-user to start their transaction.
To create a session, send a POST request to https://api.signicat.com/auth/rest/sessions?signicat-accountId={accountId}.
You can find your accountId in the Signicat Dashboard.
The following sub-sections show examples and descriptions of attributes that you can include in the request.
Message Level Encryption is required for FTN
Due to requirements from Traficom, you must use Full Message-Level Encryption (MLE) for authentication with FTN.
There are two different ways to achieve this. The first is required and the second is only required in certain circumstances:
- Receiving encrypted responses from Signicat (required)
- Sending encrypted requests to Signicat (optional)
If you are sending personally identifiable information (PII) as part of your request, you must also send encrypted requests.
To implement encrypted responses, you need to include the additional field encryptionPublicKey when making a request to the "Create a new session" endpoint (see below request example). Following this, all of your responses for both the "Create a new session" and "Get a new session" endpoints will be encrypted with this key. To decrypt these responses, you will need to use the private key that was created with the public key provided in the request.
For more details about how to set up encryption, see the general Encrypted responses from Signicat section.
Request example
Here is an example request body for an FTN authentication, including encryptionPublicKey:
{
"allowedProviders": ["ftn"],
"flow": "redirect",
"requestedAttributes": [
"name",
"firstName",
"lastName",
"dateOfBirth",
"nin",
"ftnIdp",
"ftnHetu",
"ftnSatu"
],
"additionalParameters": {
"ftn_sp_name": "ExampleOrg",
"ftn_idp": "fi-op"
},
"callbackUrls": {
"success": "http://example.com/success",
"abort": "http://example.com/abort",
"error": "http://example.com/error"
},
"encryptionPublicKey": {
"alg": "RSA-OAEP",
"e": "AQAB",
"kid": "encryption-key-04ceb013816d6244aca3310fa69b0bcf",
"kty": "RSA",
"n": "kwYbCCCQ4qUiwal16_paabTwp7GnKnjcKEH5btfGKC6ixg6mHAPTylP2_tjCpvL5OwtmdzRuLTQIxzqy4Kr2xASvlERVWNyGk_LFf4aKGv5gilBAqPOrx_...",
"use": "enc"
}
}
Upon sending this request, a session will be created with FTN.
If the authentication completes successfully, the final result will contain the attributes that were requested.
Attribute descriptions
To initialise an authentication with FTN, you can use the following attributes in the initial request:
For more detailed field descriptions, see the API reference.
Control the FTN flow (additionalParameters)
You can control the FTN flow using the additionalParameters shown in the table below.
For a full list of available attributes, see the Attributes reference page.
As an alternative to using the ftn_sp_name parameter to specify the service provider name, you can also specify this on the Finnish Trust Network configuration page in the Signicat Dashboard.
- If both are specified, then the name specified for the
ftn_sp_nameparameter takes priority. - If neither are specified, then your organisation name from the Signicat Dashboard is displayed by default.
Response example
The response from the "Create a new session" endpoint will contain an authenticationUrl, to which you can redirect the end-user to start their transaction.
Here is a response example after it has been decrypted using the private key that was generated along-side the public key provided in the request:
{
"encryptionPublicKey": {
"kty": "rsa",
"use": "enc",
"kid": "encryption-key-04ceb013816d6244aca3310fa69b0bcf",
"alg": "RSA-OAEP",
"e": "AQAB",
"n": "kwYbCCCQ4qUiwal16_paabTwp7GnKnjcKEH5btfGKC6ixg6mHAPTylP2_tjCpvL5OwtmdzRuLTQIxzqy4Kr2xASvlERVWNyGk_LFf4aKGv5gilBAqPOrx_...",
},
"id": "8775be75-bea4-...",
"accountId": "a-sdge-...",
"authenticationUrl": "https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=aeca9d15-5769-fc4d-b747-afb7f0e98c98&transactionId=e44e20af-b369-7d4b-9b88-b9d5baa1e0d7",
"status": "CREATED",
"callbackUrls": {
"success": "http://example.com/success?sessionId=8775be75-bea4-...",
"abort": "http://example.com/abort?sessionId=8775be75-bea4-...",
"error": "http://example.com/error?sessionId=8775be75-bea4-..."
},
"allowedProviders": [
"ftn"
],
"flow": "redirect",
"requestedAttributes": [
"dateOfBirth",
"firstName",
"ftnIdp",
"lastName",
"name",
"nin",
"idpId",
"ftnHetu",
"ftnSatu"
],
"sessionLifetime": 1200,
}
What you need to do with the response
You must redirect the end-user to the authenticationUrl found in the response. This is a unique URL which allows the user to perform the FTN authentication in context of the session you just created.
"authenticationUrl": "https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=aeca9d15-5769-fc4d-b747-afb7f0e98c98&transactionId=e44e20af-b369-7d4b-9b88-b9d5baa1e0d7"
End-user authentication
The end-user follows these steps:
- On your website/application, the end-user clicks on a button to authenticate with FTN. Your application sends a request to start an authentication with FTN, as described in the previous section.
- The end-user is redirected to the FTN selection page, where they can choose among all the FTN identity providers. Alternatively, they go directly to a specific identity provider, if you have specified the additionalParameters (see the above table).
- The end-user logs in using their FTN credentials (this step may involve two-factor authentication).
After the end-user approves the request, the browser is redirected back to the relevant callbackUrl specified in the "Create a new session" request.
For screen examples, see About Finnish eIDs.
2. Obtain user information (Get session status)
Make an HTTP GET request to the /sessions endpoint to poll for information regarding the session and ongoing authentication.
Upon successful authentication, a response is returned that contains the user information requested in the "Create a new session" call carried out earlier.
Request
No data specific for FTN needs to be provided in this request.
To get the status of a session, send a GET request to https://api.signicat.com/auth/rest/sessions/{id}.
You can find the id value in the response that was returned when you created the session.
Response
The response contains a status field, which indicates the current status of the session. Below you can see an example response for a successfully completed session:
{
"encryptionPublicKey": {
"kty": "rsa",
"use": "enc",
"kid": "encryption-key-04ceb013816d6244aca3310fa69b0bcf",
"alg": "RSA-OAEP",
"e": "AQAB",
"n": "kwYbCCCQ4qUiwal16_paabTwp7GnKnjcKEH5btfGKC6ixg6mHAPTylP2_tjCpvL5OwtmdzRuLTQIxzqy4Kr2xASvlERVWNyGk_LFf4aKGv5gilBAqPOrx_...",
},
"id": "8775be75-bea4-......",
"accountId": "a-sdge-...",
"authenticationUrl": "https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=aeca9d15-5769-fc4d-b747-afb7f0e98c98&transactionId=e44e20af-b369-7d4b-9b88-b9d5baa1e0d7",
"status": "SUCCESS",
"provider": "ftn",
"subject": {
"id": "qAk66xMjr-WBQgLeWvcYPNfay5bfO-cIjsVYRsxUlCs=",
"idpId": "070770-905D",
"name": "Väinö Tunnistus",
"firstName": "Väinö",
"lastName": "Tunnistus",
"dateOfBirth": "1970-07-07",
"nin": {
"value": "070770-905D",
"issuingCountry": "FI",
"type": "PERSON"
},
"ftnIdp": "fi-op",
"ftnHetu": "070770-905D"
},
"callbackUrls": {
"success": "http://example.com/success?sessionId=8775be75-bea4-...",
"abort": "http://example.com/abort?sessionId=8775be75-bea4-...",
"error": "http://example.com/error?sessionId=8775be75-bea4-..."
},
"allowedProviders": [
"ftn"
],
"flow": "redirect",
"requestedAttributes": [
"dateOfBirth",
"firstName",
"ftnIdp",
"lastName",
"name",
"nin",
"idpId",
"ftnHetu",
"ftnSatu"
],
"sessionLifetime": 1200,
}
Status overview
What you need to do with the response
If the returned status is SUCCESS, you will find information about the authenticated user in the subject object.
You will also see what identity provider was actually used by checking the provider field. This can be useful if you allowed more than one identity provider when you created the session.
You have now completed an authentication flow with FTN.
Next steps
Learn more about available request and response attributes for FTN:
Dive deeper into Authentication REST API and improve your application with advanced security features: