Skip to main content

Suomi.fi Authorisations

Authorisations generated in the Suomi.fi service by users can be imported to the ID Authorisations system.

When using Suomi.fi authorisations, selected namespaces MUST always have Suomi.fi user directory available for strong identification as required by DVV. Do not use other identification methods.

Also note that according to DVV terms and conditions, users MUST always visit suomi.fi authorisation service before being allowed to act on behalf of another person or organisation. Therefore it is strongly recommended to use short-lived authorisations, such as 60 minutes. Do not create long-lived "admin" accounts based on suomi.fi authorisations.

When registering your Trivore ID instance with DVV suomi.fi authorisations, you need to provide OAuth callback URL which is https://id.example.com/rp/suomi.fi-valtuudet/callback. Simply replace id.example.com with your ID hostname. If you are using multiple base URLs and plan to use them with Suomi.fi authorisations, you need to provide each of them to DVV.

Pre-requisites​

  • A person or organisation (the "Principal") has created an authorisation at Suomi.fi, granting the User (the "Delegate") ability to do something.

  • The User has signed in to your Service using OIDC. You have their access token.

At this time the Authorisation data is located only at the suomi.fi service. The User must transfer it to the ID service.

Redirect user to suomi.fi authorisation process​

Note that user needs to perform strong identification before using suomi.fi authorisations and will be redirected there automatically if current session is not strongly identified or it has expired (max age is 15 minutes).

On behalf of another person​

Create a form which makes a POST request to the URL https://id.example.com/api/suomi.fi/valtuudet/hpa with form parameters:

Form parameterValue
access_tokenUser's access token. Required.
successRedirectUriRequired. URI where user will be directed after successfully retrieving the Authorisations. Query parameter result can be used to verify the authorisation result. See details below.
failureRedirectUriRequired. URI where user will be directed if they cancel the operation or it fails for other reasons. Query parameters error and error_description describe the error.
nonceOptional parameter. This exact value is included in result JWT token when given. Can be used to correlate request with correct response.

The Success and Failure URIs must be pre-registered on the ID service. This can be done in the Management UI, System Preferences, Suomi.fi / Authorisations, Allowed redirect URLs.

You can add any custom query parameters (or fragment) to the success and failure redirect URIs and those will be included when user is redirected.

You may alternatively fetch redirect URL for user using /api/suomi.fi/valtuudet/hpa/user/{userId}/interactive endpoint which accepts the same parameters in JSON format.

On behalf of a organisation​

Use the URL https://id.example.com/api/suomi.fi/valtuudet/ypa, otherwise works the same as above.

You may alternatively fetch redirect URL for user using /api/suomi.fi/valtuudet/ypa/user/{userId}/interactive endpoint which accepts the same parameters in JSON format.

Simple example​

Have the User activate the buttons in their web browser​

Show the buttons to the User and instruct the User to activate on of them.

User experience after clicking the button​

The User's web browser will go through the ID service, then be redirected to suomi.fi pages where they will likely have to identify themselves using bank credentials or other means.

They will agree to pass the authorisation data to the ID service.

They will be redirected to the ID service where they will see another confirmation dialog.

Finally they will be redirected to the success URL. Query parameter result is added to the success URL. Value of this parameter is JWT token which describes the authorisation result. Details of the token payload below. Normal JWT validation rules apply.

In case error happens during the authorisation process, user will be redirected to the supplied failureRedirectUri with two query parameters:

  • error: Machine-readable error code
  • error_description: Human-readable error message

Example result JWT token:

{
  // 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/success"
  ],

  // JWT unique ID. Use this to prevent replay attacks.
  "jti": "425af4af-97b2-4e1c-b7ab-8015496262ae",
  
  // The "nonce" value provided in request redirect.
  "nonce": "406ebf05-a777-4df0-bb01-ce4d558b4cc8",
  
  // Describes the token type, different for acting on behalf of person or organisation
  "type": "urn:trivore:id:suomi.fi:valtuudet:person:result",
  "type": "urn:trivore:id:suomi.fi:valtuudet:organisation:result",
  
  // Value should always be true (excluding certain theoretical edge cases).
  "success": true,
  
  // User ID that is acting on behalf of another person or organisation.
  "userId": "6aa9239b1b5db46501f1e2bc",
  
  // List of authorisation objects that were created by the process.
  "authorisationIds": [
  	"6aabe4141b5db46501f1e2c1",
  	"6aabe4151b5db46501f1e2c2"
  ]
}

Retrieving Authorisation data​

After being redirected to the Success URL, a copy of the Authorisation data is retrievable from the ID service's Authorisations API.

Use the URL /api/rest/v1/user/{userId}/authorisation/subject to fetch authorisations using the user's own access token. You can use search paramer idAnyOf to fetch authorisations that were created by the process that was just completed.

Example:

POST /api/rest/v1/user/6aa9239b1b5db46501f1e2bc/authorisation/subject HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer <user-access-token>

{
	"idAnyOf": [
		"6aabe4141b5db46501f1e2c1",
		"6aabe4151b5db46501f1e2c2"
	]
}

If you have management API client credentials with enough permissions, you may also use /api/rest/v1/authorisation endpoint to fetch authorisations.

Figuring out who created the Authorisation​

See Listing Authorisations delegated to a User for an example of how to retrieve active Authorisations granted to a specific user.

For each Authorisation record, see the subject.type and subject.value properties. The type should be User and the value is the User ID of the person or organisation who granted the Authorisation.

Look up this Principal User account using the User API: GET /api/rest/v1/user/{userId}

The personalIdentityCodes property will hold an array of objects. Their identityCode value is the user's personal identity code ("henkilötunnus").

Last updated on