Skip to content

Version 2 notes

Jump to bottom
Mart Sõmermaa edited this page Jan 27, 2022 · 9 revisions

v2.0.0 is a major backwards incompatible release.

New authentication token format

The Web eID authentication token format changed in version 2. In version 1, the authentication token was in the OpenID X509 ID Token (JWT) format in order to be compatible with the standard OpenID Connect ID Token specification. The JWT format was found out to be undesirable, as it implies that the claims presented in the Web eID authentication token can be trusted and processed, while they actually cannot be trusted. Therefore a custom JSON-based format was adopted for the Web eID authentication token in version 2.

web-eid.js changes

In web-eid.js API version 1, the authenticate() and sign() functions took URLs as parameters and the network requests to the website back end were performed inside the extension. This had many benefits, including reduced surface for XSS attacks, additional internal security checks and control over the interaction flow with the user. However, the network requests indirectly caused a Cross-Origin Resource Sharing (CORS) vulnerability in Firefox.

To mitigate the CORS vulnerability in Firefox, the web-eid.js API version 2 no longer handles network requests internally; the website developer is expected to perform the requests instead.

Detailed overview of the changes and upgrade instructions are available here.

web-eid-authtoken-validation-java changes

In version 1, the generated challenge nonces were stored in a JSR107 compatible cache. However, in case the website had a CSRF vulnerability, this made the solution vulnerable to forged login attacks. In version 2, a session-backed challenge nonce store must be used instead to mitigate this attack.

Detailed overview of the changes and upgrade instructions are available here.

web-eid-app, web-eid-webextension and web-eid-spring-boot-example changes

web-eid-app outputs the authentication token in the new version 2 format.

web-eid-webextension has been updated to adapt to changes in web-eid.js and to the new version 2 format.

web-eid-spring-boot-example has been updated to adapt to changes in web-eid.js and in web-eid-authtoken-validation-java

Clone this wiki locally