Introduction

This document describes the relying party interface protocol of Smart-ID service and provides information for integration. The interface offers the entry point to Smart-ID main use cases, i.e. authentication and signing.

The main Smart-ID use case is of a relying party (RP) starting a session by calling the Smart-ID service RP API with a challenge when the user wishes to authenticate with the relying party’s service or a hash to create a digital signature.

Depending on the chosen RP API endpoint, either the user scans a dynamic QR code or (in the same-device use case) the user clicks a link that launches the Smart-ID application, or the Smart-ID server sends a push notification to the application.

The user then verifies the details of the transaction displayed by the Smart-ID application and confirms it.

The Smart-ID application communicates with the Smart-ID server to generate the digital signature which makes it available for the relying party to be fetched.

Meanwhile, the relying party has been waiting for a reply from the Smart-ID server using a long poll connection. In the case of success, it receives the signature and the user’s certificate to validate the result.

The service creates digital signatures as proof of authentication and signing. However, to create electronic signatures (ASiC-E with XAdES/CAdES signatures or PDF with PAdES signatures) the relying party must create the required document structure themselves, calculate the hash and have that signed using this API.

About RP API v3

The latest version of the API introduces new flows collectively referred to as "device link flows".

  • for cross-device use cases — dynamic QR codes that the user must scan;

  • for same-device use cases where the user is visiting an RP webpage using a mobile browser — device links which the user must click;

  • for same-device use cases where the user is using an RP app — device links which the user must click.

The guiding principle in designing the API has been to unify the three aforementioned flows as much as possible to minimize the integration efforts for RPs. Because of this, they mostly share the same security mechanisms and principles, even though the methods used to launch the Smart-ID application are completely different.

This also means it is possible for an RP to offer multiple alternative methods of authentication at the same time without making multiple requests to the RP API.

In the latest RP API version 3, the notification based flows will still be available, but for maximum security, it is recommended they are only used if the particular user has been authenticated at least once before on the device by one of the more secure device link flows. This can be accomplished by utilizing the client device’s local storage (e.g. browser cookies, local app storage).

Device link based flows must always be used in the same-device use case for both usability and security reasons.

Brokers of the Smart-ID service are treated similarly to relying parties and there is no extra configuration compared to previous RP API versions.

About this document

Throughout this document, there will be some blocks of text as shown below.

IMPORTANT

Important blocks like these must be followed by every RP without exceptions. These blocks show important points of the API which might lead to security issues or failures if implemented wrongly.
NOTE

Note blocks present additional information and optional features. They also link to other related sections in the guide.