Web eID

The Web eID solution enables the use of Estonian digital documents (ID-card, digital ID, e-Resident’s digital ID, residence permit card, etc.) for secure authentication and signing on the web. Web eID is compatible with most common operating systems and web browsers, using the PC/SC application interface to communicate directly with ID-cards. Additionally, Web eID supports Latvian, Lithuanian, Finnish, Croatian, Czech Republic and Belgium ID-cards. The technical capacity was also developed to rapidly implement the most common European eID smart cards online.

The Web eID solution consists of a JavaScript library, a web browser extension, and an application which jointly coordinate the communication between the web browser, the website, and the smart card to perform cryptographic operations.

In order to take Web eID into use, additional changes must also be made to online services. Currently, there is a library for online services and samples for the Java, .NET and PHP platforms. Support for other platforms is planned based on feedback. The transition to Web eID in online services requires that users have the Web eID extension and application installed. Users receive the necessary components with the ID-software. More information can be found in the schedule.

Code repository: https://github.com/web-eid/

Documentation of the architecture: https://github.com/web-eid/web-eid-system-architecture-doc

Portal and the sample environment: https://web-eid.eu/

What changes are taking place and why?

Due to the complexity of the current solution, there have been several problems with the reliability of the web browser and the operating system API, causing problems when using the ID-card in the web browser. The goal of Web eID is to make using the solution more reliable and user-friendly and solve numerous problems of the current solution.

Major changes in the Web eID solution compared to the current one:

The Web eID solution changes the process of authentication: instead of the certificate authentication built into the browser (TLS client certificate authentication), the authentication token is sent to the online service for validation via the REST API with an AJAX request. This reduces errors due to the use of different technologies for authentication and signing. Signing processes and workflows remain the same in the Web eID solution, but the API changes minimally due to updates.
In the Web eID solution, the PIN1 is not cached during ID-card authentication, and the PIN1 is requested for each authentication. Therefore, there is no need to close or restart the web browser when logging out.
In the Web eID solution, authentication certificates are not buffered, but are always loaded directly from the card, therefore showing the user only the certificate of the card currently in the card reader. As a result, selecting the correct certificate from the list of previously used certificates is no longer needed and communication with the card becomes faster.
With the current solution, web browsers use different cryptographic APIs (CNG, CDSA/Tokend, PKCS#11) across operating systems, resulting in different visuals (dialogs) in web browsers. The visuals may also differ in the same browser for authentication and signing. With the new solution, the visuals for authenticating or signing are the same regardless of the web browser or operating system.
The Web eID solution uses the common HTTPS connection that requires no special TLS settings from the web server. This simplifies the use of an ID-card in cloud services and clustered systems.

What do I need to do to integrate the Web eID solution into my online service?

Taking Web eID into use implies changes to the online service. The library and samples for the Java, .NET and PHP platforms are currently available. Support for additional platforms is planned based on feedback.

To get started, we recommend reading the Web eID materials:

Portal and the sample environment: https://web-eid.eu/
Authentication: https://github.com/web-eid/web-eid-system-architecture-doc#authentication-1
Signing: https://github.com/web-eid/web-eid-system-architecture-doc#digital-signing
Sample application that uses Web eID for authentication and signing: https://github.com/web-eid/web-eid-spring-boot-example

How to start using Web eID on the Java platform:

Integrate the JavaScript library web-eid.js into your service’s front-end. The JavaScript library is necessary for the website of the online service to communicate with the browser extension. Instructions for taking into use: https://github.com/web-eid/web-eid.js#quickstart;
The Java authentication token validation library web-eid-authtoken-validation-java must be used in the back-end for authentication. Instructions for taking into use: https://github.com/web-eid/web-eid-authtoken-validation-java#quickstart;
A XAdES library must be used in the back-end for signing. On the Java platform, we recommend using the digidoc4j library. Instructions for taking into use: https://github.com/open-eid/digidoc4j/wiki/Examples-of-using-it

How to start using Web eID on the .NET platform:

Integrate the JavaScript library web-eid.js into your service’s front-end. The JavaScript library is necessary for the website of the online service to communicate with the browser extension. Instructions for taking into use: https://github.com/web-eid/web-eid.js#quickstart;
The .NET authentication token validation library web-eid-authtoken-validation-dotnet must be used in the back-end for authentication. Instructions for taking into use: https://github.com/web-eid/web-eid-authtoken-validation-dotnet#quickstart;
A XAdES library must be used in the back-end for signing. On the .NET platform, we recommend using the libdigidocpp library. Instructions for taking into use: https://github.com/open-eid/libdigidocpp/wiki#how-to-use-it

How to start using Web eID on the PHP platform:

Integrate the JavaScript library web-eid.js into your service’s front-end. The JavaScript library is necessary for the website of the online service to communicate with the browser extension. Instructions for taking into use: https://github.com/web-eid/web-eid.js#quickstart;
The PHP authentication token validation library web-eid-authtoken-validation-php must be used in the back-end for authentication. Instructions for taking into use: https://github.com/web-eid/web-eid-authtoken-validation-php#quickstart

How to start using Web eID on other platforms:

Integrate web-eid.js JavaScript library into your service’s front-end. The JavaScript library is necessary for the website of the online service to communicate with the browser extension. Instructions for taking into use: https://github.com/web-eid/web-eid.js#quickstart;
The authentication token validating library must be used in the back-end for authentication. Currently, there is a library for the Java, .NET and PHP platforms. Support for other platforms is planned, more information can be found in the schedule. Additionally, we would appreciate your feedback regarding platform preferences;
A XAdES library must be used in the back-end for signing. If possible, we recommend using the existing libraries:
1. Libdigidocpp: https://github.com/open-eid/libdigidocpp
2. DigiDoc4j: https://github.com/open-eid/digidoc4j

Installing Web eID

Web eID can be downloaded from here: https://web-eid.eu/. For Safari the extension must be installed from App Store.
After installing the software, the Web eID extension must be manually activated in the web browser.

Web eID components are included in the ID-software installation package, which is available to users on www.id.ee website.

Supported web browsers and ID-cards

All the most widespread web browsers are supported.

Supported web browsers:

Google Chrome
Mozilla Firefox
Edge Chromium
Safari

The new Web eID will no longer support Internet Explorer web browser.

Supported ID-cards:

Web eID supports all Estonian digital documents, for example the ID-card, digital ID, e-resident’s digital ID, residence permit card, etc. as well as Latvian, Lithuanian, Finnish, Croatian, Czech Republic and Belgium ID-cards.

Backward compatibility

The Web eID authentication functionality can be used in online services that have implemented the web-eid.js library. If hwcrypto.js is used for signing in the online service, then there is a high probability that the TLS-CCA solution is still being used for authentication.

During the transitional period, the Web eID extension supports online services that use the current solution (hwcrypto.js) or the newer Web eID solution (web-eid.js) for signing.

The backward compatibility signing functionality (hwcrypto.js support) added to the Web eID extension is available only during the transitional period and will be removed in the future. More information can be found in the schedule.

Online services that took the newer Web eID solution (web-eid.js) into use cannot be used with the current extension (Token Signing) for signing. In such a case, the service provider should direct the user to install new ID-software, which includes the components of Web eID.

Software installed on a user's computer	Solution used in a web application	What happens
ID-software version (2021.06 or earlier) that includes Token Signing components.	- TLS-CCA solution is used for authentication. - The hwcrypto.js library is used for signing.	- The user is authenticated in the service through components supported by the operating system or the PKCS#11 driver. - The Token Signing component is used for signing.
ID-software version (2021.06 or earlier) that includes Token Signing components.	The Web eID solution is used for authentication and signing.	- Authentication fails. - Signing fails.
ID-software version 2022.01 and newer, that includes Web eID components.	- TLS-CCA solution is used for authentication. - The hwcrypto.js library is used for signing.	- The user is authenticated in the service through components supported by the operating system or the PKCS#11 driver. - Web eID browser extension and native app are used for signing.
ID-software version 2022.01 and newer, that includes Web eID components.	The Web eID solution is used for authentication and signing.	The Web eID browser extension and native app are used for ID-card authentication and signing.

Schedule

Web eID v0.9.4 published on 26 February 2021.

Web eID v1.0.0-rc1 published on 30 April 2021.

Support for multiple cards
Support for PinPad readers
Error management
Stage I of PKCS#11
Stage I of the new design

Web eID v1.0.0-rc2 published on 11 June 2021.

Stage II of the new design
Amending information upon changing the card
PinPad reader improvements
Additional improvements/fixes

Web eID v1.0.0 published on 27 July 2021.

Stage III of the new design
Translations
Screen reader improvements
Amending the documentation
Additional improvements/fixes

Web eID v1.0.2 published on 21 October 2021.

Safari support

Web eID v2.0 published on 21 January 2022.

Format changes
Stage IV of the new design
Additional improvements and changes in translations
Pinpad special cases
Improvements for Latvia, Lithuania and Finnish ID cards
Additional improvements/fixes

ID-software release for the users published on 15 March 2022.

Web eID components will be added into the ID-software composition (includes the backward compatibility functionality of the current solution).
Components of the current solution for signing online will be removed.

Sample for .NET platform published on 19 May 2022.

Web eID v2.0.2 published on 20 July 2022.

More information about the changes can be found here.

Web eID v2.2.0 published on 14 December 2022.

More information about the changes can be found here.

Web eID authentication token validation library for PHP published on 20 January 2023.

Start of transition to the Web eID solution in online services - 1st quarter 2023.

Web eID v2.3.1 published on 04 May 2023.

More information about the changes can be found here.

Changes to the RIA's authentication service and software (TARA) - 13 June 2023.

Web eID v2.4.0 published on 09 August 2023.

More information about the changes can be found here.

Web eID v2.5.0 published on 15 April 2024.

More information about the changes can be found here.

Web eID v2.6.0 published on 07 October 2024.

More information about the changes can be found here.

Samples for other platforms (C++, Node.js, Python, Go) – planned according to feedback.

End of the transition to the Web eID solution, i.e. the backward compatibility of the current solution will be removed from the Web eID components – 2025 I semester (date to be specified).

Testing

In order to test the Web eID solution, proper software must firstly be installed on the operating system. More information about software installation can be found here.

To test authentication and signing in your online service, we recommend ordering a test card issued by SK ID Solutions AS.

Ordering test ID-cards

Show Hide
Ordering test cards
- Ordering form of test cards and Prices :
  https://portal.skidsolutions.eu/order/certificates?tab=test-card
Test cards issued by SK:
- test ID-card (2021);
- test e-residency Digi-ID;
e-Seal on crypto-stick issued by SK
- test e-Seal on crypto stick
NB! Keep in mind that:
- test ID-cards can only be used in a test environment;
- test ID-card certificates cannot be updated.
Hide

Please note that to authenticate and sign in the test environment, the ID-card identification and signing certificates must be uploaded to the SK demo environment. https://demo.sk.ee/upload_cert/

Testing whether web-eid installation was successful

go once more to https://web-eid.eu/;
perform personal identification / authentication with a real ID-card;
sign the sample text with a real ID-card;
download the signed container;
check the signed container with the DigiDoc4 Client.

What kind of tests should be done?

Once you have integrated the Web eID solution into your online service, the solution should also be tested.

To test a positive user experience, the Web eID software must be installed on the user’s computer.

Authenticating in the online service

In order to test authentication in the online service, the following procedures should be completed:

a successful authentication;
authentication with revoked or suspended certificates;
authentication interruption;
authentication disruption (the user removes the card from the reader);
locking the PIN (entering the incorrect PIN 3 times).

Signing in the online service

In order to test signing in the online service, the following procedures should be completed:

a successful signing;
signing with revoked or suspended certificates;
validating the created containers;
signing interruption;
signing disruption (the user removes the card from the reader)
locking the card (entering the incorrect PIN 3 times).
the signer differs from the authenticated person (the user switches cards in the reader between authentication and signing).

The web service is also likely to be used by users who have an older version of the ID-software on their computer or no software at all. It would be sensible to also solve such a scenario by the web service and direct the user to install ID-software that supports Web eID:

authentication attempt in the online service with an older version of the ID-software;
authentication attempt in the online service without the ID-software;
signing attempt in the online service with an older version of the ID-software (only possible if the user is not authenticated prior to signing);
signing attempt in the online service without the ID-software (only possible if the user is not authenticated prior to signing).

It is recommended to complete the successful authentication and signing tests on all of the web browsers supported by the ID-software on at least one Windows, macOS, and Ubuntu-operated computer.

Depending on the functionality provided by the specific online service, completing additional tests could be necessary.

FAQ

Where can I find information about the safety of Web eID?

The security analysis of the Web eID solution was prepared by Cybernetica AS. The security analysis can be found at: https://web-eid.github.io/web-eid-cybernetica-analysis/webextensions-main.pdf

You can read more about the risk of session hijacking and man-in-the-middle attacks in Web eID here.

What is the difference between Open eID and Web eID?

All electronic identification projects and solutions are grouped under Open eID and will continue to be used in the future.

Web eID is a new architecture solution for web authentication and signing, the components of which are published in a standalone repository in Github.

How will the users acquire the Web eID components?

Web eID components are included in the ID-software installation package published in March 2022, which is available to users on www.id.ee website.

Does the Web eID solution also affect logging in to Windows domains with ID-cards?

Web eID solution does not affect logging in to Windows domains with ID-cards. The change only affects authentication and signing in the online service.

In my online service, users can authenticate with an ID-card, do I have to make changes?

Yes, the change affects authentication in the online service and in order to take Web eID into use, additional changes must also be made to online services. Read more here.

In my online service, users are redirected to the RIA's authentication service (TARA) to authenticate with an ID-card, do I have to make changes?

No changes is required on the online service side, as the necessary changes are made by the RIA's authentication service (TARA). More information can be found in the schedule.

In my online service, users can sign documents with an ID-card, do I have to make changes?

Yes, the change affects signing in the online service and in order to take Web eID into use, additional changes must also be made to online services. Read more here.

My online service validates signed documents in the Digital Signature Validation Service (SiVa), do I have to make changes?

Web eID solution does not affect document validation in the Digital Signature Validation Service (SiVa). The change only affects authentication and signing in the online service.

We use DigiDoc4 Client and/or RIA DigiDoc mobile application to sign and validate the documents, do i have to make changes?

Web eID solution does not affect document signing and validation in DigiDoc4 Client and/or RIA DigiDoc mobile application. The change only affects authentication and signing in the online service.

Does Web eID support Chromium web browser?

Web eID will not support Chromium web browser. Read more here.

Where do I submit my feedback?

Feedback and development suggestions can be sent to [email protected].