Dynamic link flows

Overview

On a high level, the dynamic flow consists of the following steps:

  1. User interacts with an RP frontend (which is a webpage or an app).

  2. RP backend makes a request to RP-API to create a dynamic link based authentication or signature session, obtaining security parameters that are necessary for generating dynamic links. This request may either be anonymous (no personal identifier is provided) or non-anonymous.

  3. RP starts dynamically creating dynamic links that update each second. The dynamic links are generated in RP backend and forwarded to RP frontend.

  4. RP frontend displays the QR codes / Web2App links / App2App links. The user interacts with one of them by either:

    1. Opening Smart-ID app and scanning a QR code (preferred option for QR codes);

    2. Using a native camera app to scan a QR code (not supported by all camera apps);

    3. Clicking on a Web2App link in an RP webpage, thus opening the Smart-ID app;

    4. Clicking on an App2App link in an RP app, thus opening the Smart-ID app.

  5. Smart-ID app extracts the necessary parameters and makes a request to the Smart-ID backend to check the integrity, validity and freshness of the dynamic link. If the request was non-anonymous, it is verified that the provided personal identifier agrees with the actual user’s identity. Backend responds by creating a transaction and returning the transaction data.

  6. Signing protocol continues in the usual way (user enters the PIN code).

  7. After the signature has been given, the RP receives the success result via the session status endpoint. In the case of anonymous flow, RP learns the identity of the user only at this point (via the user’s certificate).

The following diagram describes the dynamic link based flow for the authentication session. The flow for the signature session follows the same principles and has been omitted.

flow

Dynamic link calculation

When RP backend makes a request to RP API to create a new dynamic link based session, Smart-ID server generates and returns the following parameters as a response:

  • sessionID - session ID (RP UUID);

  • sessionToken - unique random value that will be used to connect this login attempt between the relevant parties (RP, RP API, Smart-ID app);

  • sessionSecret - base64-encoded random key value that should be kept in secret and should be shared only between the RP backend and RP API server.

RP then starts calculating and showing the QR image, Web2App link, and/or App2App link dynamically (all those links must be updated regularly with the interval of 1 second).

The RP may offer multiple options (a QR image and a Web2App link) to the user at the same time. This is useful in the following situations:

  • The user is accessing RP website from a mobile device, for example a tablet device. RP wants to offer to the user the choice to authenticate either on the same device (via a Web2App link) or on a separate device (via a dynamic QR code).

  • RP is unable to detect from the user agent whether the user is using a mobile device or a PC.

The next table lists all the parameters and definitions used in the dynamic link generation. They are all explained in more detail below.

Parameters used for dynamic link generation
Parameter Formula

version

A pre-defined version value, currently 0.1.

sessionToken

Generated by RP API.

sessionSecret

Generated by RP API.

dynamicLinkType

'QR' (for QR codes) | 'Web2App' (for Web2App links) | 'App2App' (for App2App links)

sessionType

'auth' | 'sign'

elapsedSeconds

Seconds since receiving the response from the initial request to RP API.

payload

A concatenating of the following 3 values in string form, separated by periods: dynamicLinkType.sessionType.elapsedSeconds

authCode

Calculated using HMAC SHA 256 algorithm and represented in Base64URL encoding.

lang

An ISO 639-2 language code. It should match the language that the user was seeing in the RP UI previously. This only affects the language of the fallback page, not the Smart-ID app itself.

The parameter sessionType describes the session type:

  • 'auth' - authentication session

  • 'sign' - signature session

The lang parameter defines the interface language for the HTTPS fallback page that will be shown to the user when there are technical problems regarding opening dynamic links (for example, if user’s browser is blocking Web2App links and needs to be configured to allow them or if Smart-ID app is not installed on the phone). It is recommended that for consistent user experience, RP provides here the same language that the user was already using in the RP UI.

The elapsedSeconds parameters is seconds since receiving the response from the initial request to RP API. Notice that authCode must be re-calculated every 1s.

As the next step, RP calculates payload using string concatenation and then uses it in HMACSHA256 calculation (explained below):

  • payload := dynamicLinkType.sessionType.elapsedSeconds

  • authCode := HMACSHA256(sessionSecret, payload)

The calculation of payload must be done in the RP backend. dynamicLinkType, sessionType and elapsedSeconds must all be generated in the RP backend and RP frontend must not be able to change these parameters.

Details about formatting the payload and sessionSecret parameters as byte strings for HMACSHA256 calculation:

  • payload should be converted into a byte string from its ASCII string representation;

  • sessionSecret should be used in its binary representation (it is returned from RP API in Base64 encoding);

  • In the QR / Web2App link / App2App link, the result of hash calculation (parameter authCode) must be formatted in Base64URL encoding.

The following table aims to clarify which of the parameters should be accessible by which parties.

RP-API server RP backend RP frontend/app

version

check emoji 2714

check emoji 2714

check emoji 2714

sessionId

star emoji 2B50

check emoji 2714

no entry emoji 26D4

sessionToken

star emoji 2B50

check emoji 2714

check emoji 2714

sessionSecret

star emoji 2B50

check emoji 2714

no entry emoji 26D4

elapsedSeconds

check emoji 2714

star emoji 2B50

check emoji 2714

dynamicLinkType

check emoji 2714

star emoji 2B50

check emoji 2714

sessionType

check emoji 2714

star emoji 2B50

check emoji 2714

authCode

check emoji 2714

star emoji 2B50

check emoji 2714

lang

check emoji 2714

star emoji 2B50

check emoji 2714

Legend:

  • star emoji 2B50 - source of parameter (the party that generates/calculates it)

  • check emoji 2714 - knows parameter

  • no entry emoji 26D4 - MUST NOT know parameter

Link

The dynamic link for App2App and Web2App is a URL string:

https://https://smart-id.com/dynamic-link/?version=…​&sessionToken=…​&dynamicLinkType=…​&sessionType=…​&elapsedSeconds=…​&lang=…​&authCode=…​

Example of a Web2App link:

https://https://smart-id.com/dynamic-link/?version=0.1&sessionToken=kj4mIOLOa75zeNKabFA5f251&dynamicLinkType=Web2App&sessionType=auth&elapsedSeconds=2&lang=eng&authCode=R5oiivdJIhfjJLBCA3AzijU2p8oH45fBKpcN59oSXboo

For all flows, the dynamic generation (every 1s) of the authCode parameter must be done in the RP backend, NOT in the RP frontend or RP app so as not to not leak the sessionSecret parameter. Also, it is forbidden to generate values of authCode parameter ahead of time and forward them to the RP frontend/app.

In the App2App and Web2App flow it will be possible for the RP to also attach a callback URI that the Smart-ID App can call at the end of the transaction. This will allow for seamless navigation between RP apps and RP websites in the single-device use case.

Details for this functionality are being worked on.

The callback URL will also be part of the payload and as such protected by the authCode parameter.

The allowed callback domains might be whitelisted by the Smart-ID Service.

QR

QR message itself is defined as a URL string, just like App2App and Web2App links. The only difference is the dynamicLinkType parameter value.

https://https://smart-id.com/dynamic-link/?version=…​&sessionToken=…​&dynamicLinkType=…​&sessionType=…​&elapsedSeconds=…​&lang=…​&authCode=…​

Example:

https://https://smart-id.com/dynamic-link/?version=0.1&sessionToken=kj4mIOLOa75zeNKabFA5f251&dynamicLinkType=QR&sessionType=auth&elapsedSeconds=2&lang=eng&authCode=R5oiivdJIhfjJLBCA3AzijU2p8oH45fBKpcN59oSXboo

Here parameter authCode is represented in Base64URL encoding. Parameter sessionToken is inserted into the QR message exactly as it was obtained from RP API.

Example of a QR code:

qr

Dynamic link and QR presentation

For generation of QR codes, error correction level LOW should be used. The QR code should have sufficient margins to enable quick scanning by the Smart-ID app. The optimal size for QR code is ~10 pixels per block when displayed on a PC, since:

  • Block sizes 5 pixels and less are too small for easy scanning (devices might have focus issues).

  • Block sizes 20 pixels and above are too big for convenient scanning.

When QR code is displayed on a mobile device, it is recommended to show the QR code as big as possible, up to 10 pixels per block.

The actual generation of the QR image can be done both in the backend or the frontend, as the underlying message in the QR code is essentially public information.

In the App2App flow, it is not necessary to generate the link every second. Instead, the RP app can request a fresh link on-the-fly from the RP backend when the user clicks on a button in the RP app and navigate to it.

Fallback page

For cases when the app is not installed or some other problem occurs with opening a dynamic link, a fallback HTTPS webpage is opened with instructions on how to resolve the issue. The lang parameter in the link is used to by default show the same language as on the RP UI. The instructions cover the following scenarios:

  • User is not on a mobile device where Smart-ID is installed and has been allowed by the RP to use a wrong type of dynamic link.

  • Smart-ID App is not installed on the current device.

  • Mobile browser does not support universal links / Android App links.

  • Mobile OS settings disallow the link and user intervention is required.