For the complete documentation index, see llms.txt. You can also append .md to any page URL to get its markdown version.
Skip to main content
For the complete documentation index, see llms.txt.

For the complete documentation index, see llms.txt

Changes for Finnish Trust Network (FTN)

This page describes the changes specific to Finnish Trust Network (FTN) that are required when migrating an existing OIDC integration from Signicat Enterprise to the new Signicat Digital Trust Platform (DTP).

Overview​

  • FTN authentication works the same after migration.
  • The end-user authentication flow does not require any changes specific to FTN.
  • The main migration changes affect:
    • OIDC configuration, including your endpoints and client credentials.
    • Returned OIDC claims.
    • Mandatory Message-Level Encryption (MLE).
    • Authentication request signing.
    • Identity method selection (if used).
FTN security requirements

For FTN, you must sign or send your authentication requests using Pushed Authorization Requests (PAR). Also, OIDC responses must use full Message-Level Encryption (MLE), which requires an encryption key that needs to be configured on the OIDC client in our new platform before testing.

Without this configuration, authentication will fail and no result will be returned. To learn more, see the Message level encryption section.

Claims​

For an overview of the key claim changes, see the table below:

Note

The standard claims name, given_name, family_name, birthdate and gender remain unchanged.

For a complete list of Finnish Trust Network (FTN) claims, see the Attributes reference page.

Scopes​

When migrating FTN, we recommend using the same set of scopes as in your current integration, while applying the mapping of the scope codes. For example, if you currently use openid, profile and signicat.national_id, we recommend that you replace signicat.national_id with nin thus resulting in openid, profile and nin. This ensures that you receive the equivalent user information.

Example: Scopes
openid profile nin
Our recommendation

We recommend that you only use additional FTN scopes if your application already depends on them, such as the ftn-extra scope which returns ftn_idp, ftn_sub, ftn_issuer and ftn_hetu.

You should only use the idp-id scope if your application requires the separate idp_id claim.

The exact claims returned depend on the requested scopes and your OIDC client configuration.

You can find an example of how an OIDC authentication response and used scopes differ between Enterprise and our new platform below:

Example: Enterprise OIDC scopes
openid+ftn+profile+signicat.national_id
Example: Enterprise response
{
  "ftn.sub": "<ftn_subject_id>",
  "sub": "<enterprise_subject_id>",
  "birthdate": "2000-02-01",
  "gender": "male",
  "ftn.hetu": "<national_identity_number>",
  "name": "Onni Juhani Korhonen",
  "signicat.national_id": "<national_identity_number>",
  "locale": "FI",
  "given_name": "Onni Juhani",
  "ftn.idpId": "fi-nordea",
  "family_name": "Korhonen"
}

Required application changes​

Update your application to read the Finnish national identity number from the new platform claim nin, instead of the Enterprise signicat.national_id claim:

Enterprise claim
signicat.national_id

You also need to update your application to read FTN-specific claims using underscores (_) instead of full stops (.):

Example: Enterprise claims
ftn.sub
ftn.hetu
ftn.idpId

If your application uses the OIDC sub claim as an internal user identifier, then you must verify your identifier mapping before migration.

Note

The sub claim is still returned by our new platform, but the value may differ from the Enterprise value.

If you need to retrieve the identical subID value, then you can follow the Migrating from Enterprise documentation.

ACR values​

The acr_values parameter is optional. You should only use it if your application pre-selects FTN or a specific FTN provider.

Pre-select FTN​

To pre-select FTN in our new platform, set idp:ftn in the acr_values.

Starting FTN authentication
acr_values=idp:ftn

This routes the end-user directly to the FTN provider selection page.

Pre-select an FTN provider​

To pre-select a specific FTN provider, also specify ftn_idp in the acr_values.

Starting Nordea authentication
acr_values=idp:ftn ftn_idp:fi-nordea

For available FTN providers and additional request parameters, see the FTN OIDC integration guide.

Message-level encryption​

FTN requires message-level encryption (MLE). You must configure an encryption key on the OIDC client for our new platform before testing the FTN integration.

Without this configuration, FTN authentication will fail and no authentication result will be returned. Learn more about Encrypted/signed responses from Signicat.

What does this mean?

Our new platform encrypts the ID token and UserInfo response using a public encryption key configured on the OIDC client. Your application must use the corresponding private key to decrypt the responses.

1. Configure the encryption key​

You can configure the encryption key in the Signicat Dashboard. To do this:

  1. Go to Signicat Dashboard > Products > eID and Wallet Hub > OIDC clients.
  2. From the OIDC client management page, locate your OIDC client, then click the Edit button.
    Tip

    This is the OIDC client that you created when following the Enterprise to new platform migration Quick start guide, in the Create a connection section.

  3. Click the Advanced tab, then click Public keys.
  4. Choose either the Import public key or + Add public key button, depending on what option you want to proceed with. Follow the corresponding steps under either Option 1 or Option 2 below.

Option 1: Reuse the existing Enterprise encryption key​

You can use this option if you want your application to continue using its existing private key. Only the public key is uploaded to our new platform. To do this:

  1. Copy or export the public part of your Enterprise encryption key pair.
  2. From the Public keys page in the Signicat Dashboard, click the Import public key button.
  3. Enter a name, set the validation dates, then set Encryption for the Usage field.
  4. Either paste the key in the Data field, or upload it using the Upload file button.
  5. To finish, click the Upload button

Option 2: Generate a new encryption key​

You can use this option if you want to rotate the encryption key during migration. To do this:

  1. From the Public keys page in the Signicat Dashboard, click the + Add public key button.
  2. Enter a name, set the validation dates, then set Encryption for the Usage field.
  3. To generate the key pair, click the Create button.
  4. Copy the private key using the copy button, then securely store it.
  5. Configure your application to use the new private key.
Want to learn more?

For supported key formats and technical requirements, see the Encrypted and signed responses from Signicat page.

2. Enable encrypted responses​

After adding the encryption key, you need to enable encrypted responses in the Signicat Dashboard. To do this:

  1. Go to Signicat Dashboard > Products > eID and Wallet Hub > OIDC clients.
  2. From the OIDC client management page, locate your OIDC client, then click the Edit button.
    Tip

    This is the OIDC client that you created when following the Enterprise to new platform migration Quick start guide, in the Create a connection section.

  3. Click the Advanced tab, then click Security.
  4. Under the User Info response type section, use the dropdown menu to select SignedAndEncrypted.
  5. Tick the Require encrypted ID tokens box.
  6. To save the client, click the Update button.

Your application must then:

  1. Decrypt the ID token or UserInfo response using its private key.
  2. Read the signed JWT contained inside the encrypted response.
  3. Validate the signed JWT as normal.
Note

The encrypted response is a nested JWT. It must be decrypted before the claims can be read.

Authentication request signing​

FTN requires signed authentication requests. You must use one of the following:

  • A signed OIDC request object.
  • Pushed Authorization Requests (PAR).

Option 1: Signed request objects​

If you use signed request objects, then you must configure the corresponding signing public key on the OIDC client for our new platform. To do this:

  1. Go to Signicat Dashboard > Products > eID and Wallet Hub > OIDC clients.
  2. From the OIDC client management page, locate your OIDC client, then click the Edit button.
    Tip

    This is the OIDC client that you created when following the Enterprise to new platform migration Quick start guide, in the Create a connection section.

  3. Click the Advanced tab, then click Public keys.
  4. If you have an existing key, you can configure this with the Edit button. If not, then you can upload or create a new one with the Import public key or + Add public key buttons.
  5. If applicable, complete the name and validation date fields. Then, ensure that you set Signing for the Usage field.
  6. Finalise editing, uploading or generating the new keys.
  7. Your application must then keep the matching private key, and use it to sign each request object.
Want to learn more?

To learn how to implement, see the Encryption/signing of the request object page.

Option 2: Pushed Authorization Requests (PAR)​

To learn how to implement Pushed Authorization Requests (PAR), see the Pushed Authorization Requests page.

Test before cutover​

Migrating FTN authentication to our new platform has a low impact on the end-user authentication experience. However, FTN requires additional security requirements, including mandatory message-level encryption (MLE) and signed authentication requests. Note that you need to configure and implement these additional security requirements in our new platform.

Before production cutover, verify that your application can:

  • Complete an FTN OIDC authentication flow in our new platform.
  • Read the Finnish national identity number from nin instead of signicat.national_id.
  • Read FTN-specific claims using underscore-based names (for example, ftn_sub and ftn_idp).
  • Successfully decrypt encrypted OIDC responses using the configured private key.
  • Send signed authentication requests or use Pushed Authorization Requests (PAR), as required.
  • Handle any changes to the sub value if it is used as an internal identifier.
  • Pre-select FTN using acr_values=idp:ftn, if your application uses method pre-selection.
  • Pre-select the correct FTN provider, if your application uses provider pre-selection.
On this page