Skip to main content

OpenID Connect

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

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, navigate to Products > eID Hub > OIDC clients.
  2. Select Create/Add client.
  3. Enter a name for the client.
  4. In Primary grant type, select the grant type (authentication flow) to use for this client.
    Choosing a grant type

    The Authorization Code flow is recommended for most cases. Learn more about supported flows in the generic OIDC implementation guide and the OAuth 2.0 specification.

  5. In the Redirect URI field, enter the URL where to redirect the end-user after authentication. You can always edit and add more URIs later.

2. Configure the scope​

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

openid is mandatory for all eIDs.

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

  1. In the Signicat Dashboard, navigate to Products > eID Hub > OIDC Clients.
  2. Select Edit to view your client configuration.
  3. Open the Access tab.
  4. Select 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 Signicat Dashboard, navigate to Products > eID Hub > OIDC Clients.
  2. Choose your client, go to the Secrets tab and select Add secret.
  3. Enter a name for your client secret and select Create.
  4. 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.

PKCE

Note that if you intend to use the OIDC client in a frontend flow, then you must always 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.

You can pre-select an eID in your authorization request by including the name of the identity provider (idp) in the acr_values parameter. To pre-select FTN, include acr_values=idp:ftn in your authorization request.

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 consists 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 the configuration of your OIDC client in the Dashboard.
  • The remainder constitutes parameters to set things like Client ID, flow and redirects.

Note the following query parameters:

  • client_id: The client ID of your OIDC application. To view the client ID, navigate to Products > eID Hub > OIDC Clients and select your client.
  • 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.
  • 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.
Important

The values you specify in the query parameters must match the values in the configuration of your OIDC client in the Dashboard.

You can find additional authorization request query parameters in the OIDC specification.

The acr_values parameters are described in more detail below.

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

In this example, the end-user will go directly to the OP-bank (fi-op) login screen.

Available parameters and values are:

End-user authentication​

The end-user follows 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 ftn_idp in acr_values (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.

For screen examples, see About Finnish eIDs.

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=authorization_code&redirect_uri=<REDIRECT_URI>&code=7E3324AB3AC63C7C1D4BED818D01DDE8F7DDC15EBA9505E1B4D44A95A2B72DDF-1&code_verifier=oQDZ3uPQn...W7U'

Example token response​

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

{
    "id_token": "eyJhbGciOiJSU0EtT0FFUC...",
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InNhbmRib3gtc2lnbmluZy1rZXktZjJlNGE3YTg4NDgxYTc0ZWJlMzIxNDFiYj...",
    "expires_in": 600,
    "token_type": "Bearer",
    "scope": "openid profile idp-id nin ftn-extra"
}

ID token​

An ID token is a JWT that encoded looks like "eyJhbGciOiJSU0EtT0FFUC...".

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 the following 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. In the Signicat Dashboard, navigate to Products > eID Hub > OIDC Clients.
  2. Choose your OIDC client and select Edit to view the client configuration.
  3. Navigate 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.

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​

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
Last updated:
On this page