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, and Finnish 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 platform, and support for other platforms is planned. 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 architecturehttps://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 JWT 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 to prevent cross-site scripting (XSS) attacks.
  • 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 platform are currently available. Developments for the .NET platform are underway. Support for additional platforms is planned.

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

How to start using Web eID on the Java platform:

  1. 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;
  2. 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;
  3. 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 other platforms:

  1. 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;
  2. The authentication token validating library must be used in the back-end for authentication. Currently, there is a library only for the Java platform. Support for other platforms is planned, more information can be found in the schedule. Additionally, we would appreciate your feedback regarding platform preferences;
  3. 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

The beta version of Web eID can be downloaded https://web-eid.eu/ and for Safari App Store.
After installing the software, the Web eID extension must be manually activated in the web browser.

NB! The software offered on the web-eid.eu website is intended only for testing the Web eID solution and is not intended for daily operations.

In the future, the final version of Web eID will be added into the ID-software installation package, available for the users the website on www.id.ee.

Supported operating systems, web browsers, and ID-cards

All the most widespread operating systems and web browsers are supported.

Supported operating systems:

  • Windows 8.1, Windows 10, Windows Server 2012 R2, Windows Server 2016, Windows Server 2019
  • macOS Mojave (10.14), macOS Catalina (10.15), macOS Big Sur (11)
  • Ubuntu 18.04 (LTS) (64bit), 20.04 (LTS) (64bit), 20.10 (64bit)

Supported web browsers:

  • Google Chrome
  • Mozilla Firefox
  • Edge Chromium
  • Safari

The new Web eID will no longer support Internet Explorer and the older Microsoft Edge 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, and Croatian 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 signing extension supports online services that use the current solution (hwcrypto.js) or the newer Web eID solution (web-eid.js).

The backward compatibility functionality (hwcrypto.js support) added to the Web eID signing 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 extensions 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.

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 version – 21 October 2021.

  • Safari support

Web eID v1.0.3 version – date to be specified.

  • Stage IV of the new design
  • Amending the documentation
  • Additional improvements/fixes

ID-software release for the users planned to be published in autumn 2021.

  • 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.

The transition to the Web eID solution in online services is planned to begin in 2022 (date to be specified).

Sample for .NET platform planned to be published in autumn 2021.

Samples for other platforms (C++, PHP, 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 – 2022/2023 (date to be specified).

Changes to the RIA’s authentication service and software (TARA) – date to be specified.

Testing

In order to test the Web eID solution, proper software must firstly be installed on the operating system. The software can be downloaded at: https://web-eid.eu/. After installing the software, the Web eID extension must be manually activated in the web browser.

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

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

  1. go once more to https://web-eid.eu/;
  2. perform personal identification / authentication with a real ID-card;
  3. sign the sample text with a real ID-card;
  4. download the signed container;
  5. 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:

  1. a successful authentication;
  2. authentication with revoked or suspended certificates;
  3. authentication interruption;
  4. authentication disruption (the user removes the card from the reader);
  5. 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:

  1. a successful signing;
  2. signing with revoked or suspended certificates;
  3. validating the created containers;
  4. signing interruption;
  5. signing disruption (the user removes the card from the reader)
  6. locking the card (entering the incorrect PIN 3 times).
  7. 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:

  1. authentication attempt in the online service with an older version of the ID-software;
  2. authentication attempt in the online service without the ID-software;
  3. 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);
  4. 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.

Known issues and planned improvements:

The to-do list can be found at (the list is being regularly updated): https://github.com/orgs/web-eid/projects/2

Feedback and development suggestions can be submitted to help@ria.ee.

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.gitlab.io/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?

We plan to add the Web eID components into the ID-software installation package to be disclosed in the autumn of 2021. Users will acquire the new components via updating the ID-software or by downloading them separately from the 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 help@ria.ee.