Integration with OIDC

This guide details how to integrate with FTN using the OpenID Connect (OIDC) protocol.

Page contents

• Prerequisites
• Set up the OIDC client in the Dashboard
  • 1. Add an OIDC client
  • 2. Configure the scope
  • 3. Add a client secret
• Implement the OIDC authentication flow
  • 1. Build the authentication request
  • 2. Obtain the access token
  • 3. Obtain user information
• Next steps

Prerequisites

We assume you have done the initial preparations and received the needed access to the service, as described on the Initial preparations page.

Set up the OIDC client in the Dashboard

1. Add an OIDC client

When you register an OIDC client application, you receive a client ID. To do this:

1. In the Signicat Dashboard, go to eID Hub > OIDC clients (opens new window) and select Create/Add client.
2. Enter a name for the client.
3. In Primary grant type, select which grant type you want to use with this client. We strongly recommend AuthorizationCode. For further information about the different grant types, refer to the OIDC specification (opens new window) and the OAuth 2.0 specification (opens new window).
4. In the Redirect URI field, enter the URL that you want to redirect your end-user to when the authentication process is finished. Note that if you want to use more than one redirect URI, you can still add them after the client has been created.

2. Configure the scope

Available scopes for FTN are: openid profile idp-id nin ftn-extra

openid is mandatory for all ID methods.

To be able to add scopes in your request, you first need to define them in the Signicat Dashboard:

• In the Dashboard, go to the OIDC Client (opens new window) you intend to use for the ID method.
• Click Edit: to view your client configuration.
• Open the Access tab.
• Click Add scope in the "Allowed scopes" section and select the scopes from the list.

For more details about these scopes, see the Attributes reference.

3. Add a client secret

Depending on the type of your application, you may want to add a client secret. To do this:

1. In the menu for the OIDC Client (opens new window), go to the Secrets tab and click Add secret.
2. Enter a name for your client secret and click Create.
3. Copy your new client secret and store it safely.

Important

• Save the client secret in a safe place, since you will only be able to view your client secret once, right after you create it. If you ever forget it or lose it, you have to create a new one.
• If you intend to use the OIDC client in a frontend flow or any type of application that cannot store a client secret, you must use Proof Key for Code Exchange (PKCE). We strongly recommend using PKCE, even when you are using a client secret. Learn more about PKCE in the eID Hub documentation.

Implement the OIDC authentication flow

In OIDC, an application first needs to specify which permissions to request, then send the end-user to a browser to get their permission. After the end-user approves the authentication request and gets redirected to your website, your application receives back an authorization code that it can exchange for an access token and an ID token. You can find the end-user data attributes in the ID token or in the UserInfo endpoint.

1. Build the authentication request

This section describes how to generate the URI that opens the FTN selection page.

To begin the authentication flow, your application should build an authentication URI that the end-user can open in a browser to start an authentication flow with FTN. The authorize endpoint starts the authentication flow with the end-user. It directs the end-user to the authorisation server, where the end-user logs in with their FTN account.

Your application sends an HTTPS GET request with the appropriate URI parameters.

Here is an example of an OIDC authentication URI:

https://<YOUR_SIGNICAT_DOMAIN>/auth/open/connect/authorize?
client_id=sandbox-example-client-123
&response_type=code
&scope=openid profile idp-id nin ftn-extra
&prompt=login
&acr_values=idp:ftn
&redirect_uri=https://myservice.example/redirect

The URL consist of two parts:

• The first part is the base URL, https://<YOUR_SIGNICAT_DOMAIN>/auth/open/connect/authorize. This URL is available in the discovery document of your OIDC client which you can find under Well-Known URL for client in your OIDC client configuration in the Dashboard (opens new window).
• The remainder constitutes parameters to set things like Client ID, FTN flow and redirects.

Note the following query parameters:

• client_id: The client ID of your OIDC application. You can find this in the Dashboard > OIDC Clients (opens new window).
• response_type: Specifies the required grant type for the OIDC flow.
• scope: A space-separated list of permissions that the application requests, determining which claims are returned after a successful OIDC flow.
• prompt: Controls the behaviour of the authentication flow. For more details, see Forcing re-authentication.
• acr_values: (Optional) A space-separated list of key-value pairs to customise the authentication flow. For more details, see the Control the FTN flow (acr_values) below.
• redirect_uri: The URI where to redirect the user after they approve the request at the end of the OIDC flow. This must be an absolute URI using the HTTPS protocol.

You can find additional authorization request query parameters in the OIDC specification (opens new window).

Important

The values you specify in the query parameters must match the values in the configuration of your OIDC client (see Configure the scope).

Control the FTN flow (acr_values)

You can control the FTN flow by using the acr_values parameters, for example: acr_values=idp:ftn ftn_idp:fi-op

Available parameters and values are:

Name	Example value	Description
idp	ftn	Specify idp:ftn if you want the end-user to be sent directly to FTN. You can specify multiple ID methods to show the user a list of different identity providers. Specifying idp:ftn,sbid allows the user to choose between FTN and Swedish BankID. Don’t specify this field if you want to show a list of all the ID methods your account has connections for.
ftn_idp	fi-op	Sends the end-user directly to the specific identity provider login (here OP bank), instead of opening the FTN selection page with all the providers. The example value, fi-op, is the IdP code for OP bank. For a full list of FTN IdP codes, see the IdP discovery section.
ftn_sp_name	ExampleOrg	Allows you to specify your service provider name that will be shown to the end-user before and during the authentication. We recommend that you keep the name short to avoid a line break. You can also specify the service provider name on the FTN configuration page (opens new window) in the Dashboard. If neither of these are specified, your organisation name will be displayed as default. The service provider name is prioritised in this order: acr_values > configured in Dashboard > organisation name.

End-user authentication

The process flow that the end-user follows includes these steps:

1. On your website/application, the end-user clicks on a button to authenticate with FTN. Your application sends an authorization request to start an authentication with FTN, as described in the previous section.
2. 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 ftn_idp acr_value (see above table).
3. The end-user logs in using their FTN credentials (this step may involve two-factor authentication).

After the end-user approves the request, the authorization server redirects the browser back to the redirect_uri specified by the application, adding a code in the server response.

Server response

Here is an example of the server response URI after the end-user authentication:

https://<REDIRECT_URI>/?
code=DBB67B2E8E95933A1B8D283C04848DC6A878855B943671DED1310736A811D44E-1
&scope=openid%20profile%20idp-id%20nin%20ftn-extra
&session_state=MZvUqShFyumujsPPyby4cyUNhxrSKvmkBuDFvONHlcw.00C7928A96EBC64F87BEA33E37C3290B
&iss=https%3A%2F%2F<YOUR_SIGNICAT_DOMAIN>%2Fauth%2Fopen

The code is the authorization code generated by the authorization server. You use this code in the request to the token endpoint to obtain an access token and the ID token (see the next sections).

2. Obtain the access token

Your application should exchange the authorization code for an access token, an ID token and optionally a refresh token by making an HTTPS POST request to the authorization server token endpoint.

Message Level Encryption is required for FTN

Due to requirements from Traficom, you are required to 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:

1. Receiving encrypted responses from Signicat (required)
2. Sending encrypted requests to Signicat (optional)

Important

If you are sending personally identifiable information (PII) as part of your request, you will also need to send encrypted requests.

For more details on how to set this up for OIDC, see Advanced security considerations.

Example token request

curl -X POST https://<YOUR_SIGNICAT_DOMAIN>/auth/open/connect/token -H 'Authorization: Basic ZGV2LXRlbnNlL...pnTW9oajBpbW1SQQ==' -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=<GRANT_TYPE_CODE>&redirect_uri=<REDIRECT_URI>&code=7E3324AB3AC63C7C1D4BED818D01DDE8F7DDC15EBA9505E1B4D44A95A2B72DDF-1&code_verifier=oQDZ3uPQn...W7U'

Example token response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "eyJ ... Klmmm.emo ... NzBKFf.gaW8g ... Mzn5"
    "token_type": "Bearer",
    "refresh_token": "eyJ ... zcuUk.mow ... 7HmKmn.ggW8h ... Gz4g",
    "expires_in": 3600,
    "id_token": "eyJ ... zcifQ.ewo ... NzAKfQ.ggW8h ... Mzqg"
}

ID token

An ID token is a JWT that encoded looks like eyJ ... zcifQ.ewo ... NzAKfQ.ggW8h ... Mzqg.

The decoded payload (data) part of the ID token for FTN would then look like:

{
  "iss": "https://<YOUR_SIGNICAT_DOMAIN>/auth/open",
  "nbf": 1713946792,
  "iat": 1713946792,
  "exp": 1713947392,
  "aud": "<OIDC_CLIENT_ID>",
  "amr": "[\"external\"]",
  "at_hash": "uvaVtF2kvHTl2kPCqpi3VQ",
  "sid": "4BA883D8E1D67053C2E78F9D87811A7A",
  "sub": "2uwfL96EEeJCQSqGbrWwTr5S3sCK9SibSlv2-EAf7A8=",
  "auth_time": 1713946773,
  "idp": "ftn",
  "idp_id": "070770-905D",
  "name": "Väinö Tunnistus",
  "family_name": "Tunnistus",
  "given_name": "Väinö",
  "birthdate": "1970-07-07",
  "nin": "070770-905D",
  "nin_type": "PERSON",
  "nin_issuing_country": "FI",
  "ftn_idp": "fi-op",
  "ftn_hetu": "070770-905D",
  "idp_issuer": "https://saml-idp.test.op.fi/FIM/sps/LVASOPIDP/saml20",
  "sandbox": true
}

In this example we have used all the available scopes for FTN: openid profile idp-id nin ftn-extra

Control the returned data in ID Token

ID Token is configured by default to return only the claims defined in the OIDC standard (standard scopes). To control the data returned in the ID Token:

1. Open the Dashboard OIDC clients (opens new window) and select your OIDC client.
2. Go to the Advanced > Security tab and edit the Id Token User data. You can choose between:

- **Standard Scopes** (default): Returns the standard OIDC scopes.
- **All**: Returns all claims.
- **Minimal**: Returns only `sub`.

In the above example, we have set the Id Token User data to All, which means it returns all the claims.

3. Obtain user information

You use the UserInfo request to obtain the user information as defined in the scopes.

This response example shows user information retrieved from the UserInfo endpoint:

{
    "idp_id": "4heW7-yPOePAVfT-TTER-IKzTCJBad7yyFkdB4T1Bn4=",
    "name": "Väinö Tunnistus",
    "family_name": "Tunnistus",
    "given_name": "Väinö",
    "birthdate": "1970-07-07",
    "nin": "070770-905D",
    "nin_type": "PERSON",
    "nin_issuing_country": "FI",
    "idp_issuer": "https://saml-idp.test.op.fi/FIM/sps/LVASOPIDP/saml20",
    "sub": "4heW7-yPOePAVfT-TTER-IKzTCJBad7yyFkdB4T1Bn4="
}

See also the Attributes reference page for a list of available scopes and claims.

Success

You have now completed an authentication flow with FTN.

Next steps

Learn more about available scopes and claims for FTN:

Attributes reference

Scopes and claims for FTN with OIDC

Dive deeper into OIDC and improve your application with advanced security features:

Advanced OIDC implementation

Learn about available flows, endpoints, claims, key rotation, security, error codes etc.

Advanced security considerations

Learn about advanced security measures like PKCE and encryption