Initiating Interactive Strong Identification (suomi.fi-tunnistus)

Produce a URL leading to the interactive strong identification web page

The URL for interactive strong identification is generated by requesting it via the Management API. The request can use Management API Client credentials or any valid access token (no specific scope is required); you need to provide the user ID, a success redirect URI, and a failure redirect URI. You may optionally provide nonce value that will be included in success redirect result JWT token.

See the API documentation for POST https://{your-id-server}/api/rest/v1/user/{userId}/strongidentification/interactive for the full request/response reference.

The produced URL is only valid for a short time, so generate it immediately before forwarding the user to it — don't generate it ahead of time.

Deprecated method

In older server versions, the interactive identification URL was constructed by hand and required an access token. This method still exists but isn't recommended — use the API endpoint above instead.

Redirect the user to the produced URL

Have the user open the URL in their web browser.

Wait for the result

The identification process ends in either success or failure. On success, the user is redirected to the provided success redirect URL. On failure (including cancellation), the user is redirected to the failure redirect URL.

Success redirect URI parameters

If the identification process was completed successfully, following parameter is added to the success redirect URI. Note that section applies only to Trivore ID version 6.x and later.

Parameter	Value
result	Signed JWT token which describes the strong identification result. Normal signed JWT validation rules apply.

Result JWT token payload is described below.

{
  // Token issuer, value is Trivore ID base URL
  "iss": "https://id.example.com",
  
  // Issued at timestamp when token was issued. Value is epoch seconds.
  "iat": 1789018469,
  
  // Token expiration timestamp. Value is epoch seconds.
  "exp": 1789623269,
  
  // Audience, value always contains the success redirect URI without any query parameters.
  "aud": [
  	"https://example.com/succes"
  ],

  // JWT unique ID. Use this to prevent replay attacks.
  "jti": "425af4af-97b2-4e1c-b7ab-8015496262ae",
  
  // Nonce value provided in original API request
  "nonce": "406ebf05-a777-4df0-bb01-ce4d558b4cc8",
  
  // Describes the token type, value is always the same
  "type": "urn:trivore:id:strong-identification:result",
  
  // Value should always be true (excluding certain theoretical edge cases).
  "success": true,
  
  // User directory ID that was used to perform strong identification.
  "directoryId": "6aa923791b5db46501f1e2bb",
  
  // User ID that was identified.
  "userId": "6aa9239b1b5db46501f1e2bc",
  
  // Strong identification history entry ID that was created.
  "strongIdentificationId": "6aa923b41b5db46501f1e2bd",
  
  // These fields are present only if success is false.
  "error": "machine-readable-error",
  "errorDescription": "Human-readable error message"
}

Failure redirect URI parameters

If the identification process doesn't finish successfully, these parameters may be added to the failure URI:

Parameter	Value
error	Error code.
error_description	Short, human-readable explanation of the error, in English.

Sequence diagram

suomi.fi strong identification + sign-in

Test credentials

The Digital and Population Data Services Agency (DVV) provides test credentials for suomi.fi identification and sign-in.

See also Strong Identification Explained for the broader concepts.