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: authentication and digital signing.
What is Smart-ID?
Smart-ID is a secure digital identity service that enables users to authenticate and create digital signatures using their mobile device. The service works through a collaboration between:
-
Relying Parties (RPs) - organizations that need to verify user identity or obtain digital signatures
-
Smart-ID service - the backend infrastructure that manages authentication and signing processes
-
Smart-ID mobile app - the user’s interface for confirming transactions
How Smart-ID works
The typical Smart-ID workflow follows these steps:
-
A user wants to authenticate or sign a document with a Relying Party
-
The RP creates a session by calling the Smart-ID RP API with either:
-
A challenge (for authentication)
-
A document hash (for digital signing)
-
-
The user interacts with Smart-ID through one of these methods:
-
Scanning a dynamic QR code (cross-device)
-
Clicking a link (same-device)
-
Receiving a push notification
-
-
The user verifies transaction details and confirms the transaction in the Smart-ID app
-
The Smart-ID service generates the digital signature
-
The RP receives the result and validates the user’s certificate
About RP API v3
The latest version introduces device link flows--a unified approach for cross-device and same-device scenarios. Device link flows provide a modern and more secure alternative to push notification flows.
Cross-device Use Cases
Users scan dynamic QR codes when the RP session is on a different device than their Smart-ID app (e.g., using a PC browser to access an RP website).
Same-device Use Cases
Users click device links when the RP frontend (website or app) is on the same mobile device as their Smart-ID app:
-
Web2App - to navigate from RP website to Smart-ID app;
-
App2App - to navigate from RP app to Smart-ID app.
Key Benefits of Device Link Flows
-
Unified Flow: All flows share the same API endpoints and security mechanisms despite different launch methods
-
Flexible Integration: RPs can offer multiple authentication methods simultaneously
-
Enhanced Security: Device link flows provide better protection than notification-based flows
Notification based Flows
RP API v3 still has notification based flows that are very similar to previous versions of the RP API. Users enter their identity code. They then receive a notification on their device(s).
Which flows to prefer for cross-device use cases?
When integrating RP API v3, every RP has to make a choice between using device links, notification-based flows, or a combination of them. Essentially, there are three possible options:
-
Always use device links
-
Use device links once on a new device, and use push notifications on known devices
-
Always use push notifications
This choice should be done after careful consideration to ensure that RP and its users obtain maximum possible security and user experience benefits. The following table gives an overview of the possible options and their implications.
| Flow on a new device | Flow on a known device | Protection against phishing attacks | Recommendation |
|---|---|---|---|
|
|
|
Recommended |
|
|
|
Recommended |
|
|
|
Not recommended |
Table 1. Available options for implementing the cross-device flow.
Which flows to prefer for same-device use cases?
For same-device use cases, the same security considerations apply as for the cross-device use cases. However, there are even more benefits for always using device link flows in the same-device use case:
-
they provide a seamless user experience, where user has to only make one click to open up the Smart-ID app;
-
user does not have to verify verification codes (which can be problematic for users to verify in same-device flows);
-
they provide highest phishing resistance possible, relying on the fact that RP frontend and Smart-ID app reside in the same device.
| Flow on a new device | Flow on a known device | Protection against phishing attacks | Recommendation |
|---|---|---|---|
|
|
|
Recommended |
|
|
|
Not recommended |
|
|
|
Not recommended |
Table 2. Available options for implementing the same-device flow.
Security considerations
Although Smart-ID service is a technology designed with security in mind, Relying Parties (RPs) need to consider potential risks which are associated with digital authentication and signing solutions. It is important that RPs implement additional security mechanisms to help users understand the context of their actions and protect them from possible attacks.
Throughout this integration guide, we describe effective security measures for mitigating attacks, however not all security measures are considered mandatory for all RPs. Nevertheless, there’s nobody else who can implement those defences and security measures on their behalf. It is the RP’s opportunity and responsibility to carefully assess these risks and select appropriate countermeasures to prevent cybercriminals from being successful in their actions.
Throughout this guide, the following types of information blocks are used:
|
IMPORTANT
Important blocks contain critical information that must be followed without exception. Ignoring them may lead to security issues or implementation failures. |
|
NOTE
Note blocks provide additional information and clarify implementation details. |
|
TIP
Tip blocks describe optional features and provide additional information that can be used to enhance your implementation. |
What’s Next?
-
To understand the technical details of the solution, start by reading the Overview of API endpoints.
-
For additional information about device link flows, continue to read the Device Link flows page.
Feedback
All feedback to this document is appreciated and can be sent to the e-mail address support@smart-id.com.