Introduction
This document describes the relying party service interface protocol of Smart-ID server 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 to start a session by calling the Smart-ID server RP API with a challenge when the user wishes to authenticate with the relying party’s service or create a signature.
Either the user must scan a QR code for multi-device use case to launch the Smart-ID application or click a link for single-device use case to launch the Smart-ID application, or the Smart-ID server must send a push message notification to the user’s device where the user opens the Smart-ID application.
The user checks the details of the transaction and enters a PIN code to confirm it.
The application communicates with the Smart-ID server and once the final signature is created 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 case of success it receives the signature and the user’s certificate to be able to validate the result.
The service creates digital signatures as proof of authentication and signing. However, to create electronic signatures the relying party must create the required document structure, calculate the hash and have that signed using this API.
|
The latest version of the API introduces new flows collectively referred to as "dynamic flows".
The guiding principle in designing the API has been to unify those three aforementioned flows as much as possible to minimize the integration efforts for the RPs. Because of this, they share the same security mechanisms and principles, even though the medium of transmitting information is completely different. This also means that it is possible for an RP to offer alternative methods of authentication at the same time without doing multiple requests to RP-API. In RP API version 3, the notification based flows will still be available, but for maximum security, it is recommended that they are used only if the user has been authenticated at least once before in that device by one of the more secure dynamic flows. The recommended way for ensuring this is for the RP to utilize the client’s local storage (e.g. browser cookies) to keep track which clients have previously authenticated using the more secure flows. For both usability and security reasons, in the single-device use case the new dynamic links based flows should always be used. Brokers of the Smart-ID service are treated similarly to relying parties and there is no extra configuration compared to previous RP API versions. |
Dynamic link based authentication flow
The following sequence diagram gives an overview of the new (more secure) dynamic link based authentication flow.
