docs: update README with v2 information

mrts · mrts · commit f1f8fe43903a · 2025-05-26T10:48:10.000+03:00
WE2-610

Signed-off-by: Mart Somermaa &lt;mrts@users.noreply.github.com&gt;
diff --git a/example/README.md b/example/README.md
@@ -2,8 +2,8 @@
 
 ![European Regional Development Fund](https://github.com/open-eid/DigiDoc4-Client/blob/master/client/images/EL_Regionaalarengu_Fond.png)
 
-Example Spring Boot web application that uses Web eID for strong authentication
-and digital signing with electronic ID smart cards.
+This project is an example Spring Boot web application that shows how to implement strong authentication
+and digital signing with electronic ID smart cards using Web eID.
 
 More information about the Web eID project is available on the project [website](https://web-eid.eu/), which is served by this application.
 
@@ -23,19 +23,19 @@ You can use, for example, [_ngrok_](https://ngrok.com/) to get a reverse HTTPS p
 
 ### 2. Configure the origin URL
 
-One crucial step of Web eID authentication token validation algorithm is verifying that the _aud_ field of the token contains the site origin URL (the URL serving the web application) to protect against man-in-the-middle attacks. Hence the site origin URL must be configured in application settings.
+One crucial step of the Web eID authentication token validation algorithm is verifying the token signature. The value that is signed contains the site origin URL (the URL serving the web application) to protect against man-in-the-middle attacks. Hence the site origin URL must be configured in application settings.
 
-To configure the origin URL, copy and paste the HTTPS URL that _ngrok_ did output in step 1 into the `local-origin` field in the profile-specific settings file `src/main/resources/application-{dev,prod}.yaml` as follows:
+To configure the origin URL, copy and paste the HTTPS URL from _ngrok_ output in step 1 into the `local-origin` field in the profile-specific settings file `src/main/resources/application-{dev,prod}.yaml` as follows:
 
 ```yaml
 web-eid-auth-token:
     validation:
-        local-origin: "https://<<NGROK URL HERE>>"
+        local-origin: "https://<<NGROK HOSTNAME HERE>>"
 ```
 
 ### 3. Configure the trusted certificate authority certificates
 
-The Web eID authentication token validation algorithm needs to know which intermediate certificate authorities (CA) are trusted to issue the eID authentication certificates. CA certificates are loaded either from `.cer` files in the profile-specific subdirectory of the [`certs`resource directory](src/main/resources/certs) or the [truststore file](src/main/resources/certs/prod/trusted_certificates.jks). By default, Estonian eID test CA certificates are included in the `dev` profile and production CA certificates in the `prod` profile.
+The algorithm, which performs the validation of the Web eID authentication token, needs to know which intermediate certificate authorities (CA) are trusted to issue the eID authentication certificates. CA certificates are loaded either from `.cer` files in the profile-specific subdirectory of the [`certs`resource directory](src/main/resources/certs) or the [truststore file](src/main/resources/certs/prod/trusted_certificates.jks). By default, Estonian eID test CA certificates are included in the `dev` profile and production CA certificates in the `prod` profile.
 
 In case you need to provide your own CA certificates, either add the `.cer` files to the `src/main/resources/certs/{dev,prod}` profile-specific directory or add the certificates to the truststore file.
 
@@ -57,7 +57,7 @@ Build and run the application with the following command in a terminal window:
 ./mvnw spring-boot:run
 ```
 
-This will activate the default `dev` profile and launch the built-in Tomcat web server on port 8080 that was forwarded to _ngrok_ in step 1.
+This will activate the default `dev` profile and launch the built-in Tomcat web server on port 8080 that was forwarded using _ngrok_ in step 1.
 
 When the application has started, open the _ngrok_ HTTPS URL in your preferred web browser and follow instructions on the front page.
 
@@ -78,8 +78,10 @@ When the application has started, open the _ngrok_ HTTPS URL in your preferred w
   + [How to verify that HTTPS is configured properly](#how-to-verify-that-https-is-configured-properly)
 * [Deployment](#deployment)
 * [Frequently asked questions](#frequently-asked-questions)
-  + [Why do I sometimes get the `403 Forbidden` response during authentication?](#why-do-i-sometimes-get-the-403-forbidden-response-during-authentication)
-  + [Why do I get the `"Access denied to TSP service"` error?](#why-do-i-get-the-access-denied-to-tsp-service-error)
+  + [Why do I sometimes get the 403 Forbidden response during authentication?](#why-do-i-sometimes-get-the-403-forbidden-response-during-authentication)
+  + [Why do I get the "Access denied to TSP service" error?](#why-do-i-get-the-access-denied-to-tsp-service-error)
+  + [Why can I not use my test ID card?](#why-can-i-not-use-my-test-id-card)
+  + [Why do I get the 401 Unauthorized "Authentication failed: Web eID token validation failed" response during authentication?](#why-do-i-get-the-401-unauthorized-authentication-failed-web-eid-token-validation-failed-response-during-authentication)
 
 ## Overview of the project
 
@@ -88,7 +90,6 @@ This repository contains the code of a minimal Spring Boot web application that
 -   Spring Web MVC with REST support,
 -   the Thymeleaf template engine,
 -   Spring Security,
--   the Spring cache abstraction and the [_Caffeine_](https://github.com/ben-manes/caffeine) _JCache_-compatible caching implementation,
 -   the Web eID authentication token validation library [_web-eid-authtoken-validation-java_](https://github.com/web-eid/web-eid-authtoken-validation-java),
 -   the Web eID JavaScript library [_web-eid.js_](https://github.com/web-eid/web-eid.js),
 -   the digital signing library [_DigiDoc4j_](https://github.com/open-eid/digidoc4j).
@@ -101,9 +102,9 @@ There is also a Docker Compose configuration file `docker-compose.yml` in the ro
 
 The source code folder `src` contains the application source code and resources in the `main` subdirectory and tests in the `test` subdirectory.
 
-The `src/main/java/org/webeid/example` directory contains the Spring Boot application Java class and the following sub-folders:
+The `src/main/java/org/webeid/example` directory contains the Spring Boot application Java class and the following subdirectories:
 
--   `config`: Spring and HTTP security configuration, Web eID authentication token validation library configuration, cache configuration, trusted CA certificates loading etc,
+-   `config`: Spring and HTTP security configuration, Web eID authentication token validation library configuration, trusted CA certificates loading etc,
 -   `security`: Web eID authentication token validation library integration with Spring Security via an `AuthenticationProvider` and `AuthenticationProcessingFilter`,
 -   `service`: Web eID signing service implementation that uses DigiDoc4j, and DigiDoc4j runtime configuration,
 -   `web`: Spring Web MVC controller for the welcome page and Spring Web REST controllers that provide endpoints
@@ -131,37 +132,39 @@ The main configuration file `src/main/resources/application.yaml` is shared by a
 
 Besides configuration settings, the trusted certificate authority certificates may need to be configured as described in section [_3. Configure the trusted certificate authority certificates_](#3-configure-the-trusted-certificate-authority-certificates) above.
 
+Spring Security has CSRF protection enabled by default. Web eID requires CSRF protection.
+
 ### Integration with Web eID components
 
-Detailed overview of Java code changes required for integrating Web eID authentication token validation is available in the [_web-eid-authtoken-validation-java_ library README](https://github.com/web-eid/web-eid-authtoken-validation-java/blob/main/README.md). There are instructions for configuring the cache, nonce generator, trusted certificate authority certificates, authentication token validator, Spring Security authentication integration and REST endpoints. The corresponding Java code is in the `src/main/java/org/webeid/example/{config,security}` and `src/.../web/rest` directories.
+Detailed overview of Java code changes required for integrating Web eID authentication token validation is available in the [_web-eid-authtoken-validation-java_ library README](https://github.com/web-eid/web-eid-authtoken-validation-java/blob/main/README.md). There are instructions for configuring the nonce generator, trusted certificate authority certificates, authentication token validator, Spring Security authentication integration and REST endpoints. The corresponding Java code is in the `src/main/java/org/webeid/example/{config,security,web/rest}` directories.
 
 A similar overview of JavaScript and HTML code changes required for authentication and digital signing with Web eID is available in the [web-eid.js library README](https://github.com/web-eid/web-eid.js/blob/main/README.md). The corresponding JavaScript and HTML code is in the `src/resources/{static,templates}` directories.
 
 ### Integration with DigiDoc4j components
 
-Java code examples how to create and sign data containers that hold signed file objects and digital signatures is available in the [DigiDoc4j wiki](https://github.com/open-eid/digidoc4j/wiki/Examples-of-using-it). Further information and links to the API documentation is available in the project [README](https://github.com/open-eid/digidoc4j/blob/master/README.md). The corresponding Java code is in the `src/main/java/org/webeid/example/service` and `src/.../web/rest` directories.
+Java code examples that show how to create and sign data containers that hold signed file objects and digital signatures is available in the [DigiDoc4j wiki](https://github.com/open-eid/digidoc4j/wiki/Examples-of-using-it). Further information and links to the API documentation is available in the project [README](https://github.com/open-eid/digidoc4j/blob/master/README.md). The corresponding Java code is in the `src/main/java/org/webeid/example/{service,web/rest}` directories.
 
 #### Using the Certificates' _Authority Information Access_ (AIA) extension in DigiDoc4j
 
-In the `SigningService` constructor, we have configured DigiDoc4j to use the AIA extension that contains the certificates’ OCSP service location with `signingConfiguration.setPreferAiaOcsp(true)`. **Note that there may be legal limitations to using AIA URLs during signing** as the services behind these URLs provide different security and SLA guarantees than dedicated OCSP services, so you should consider using a dedicated OCSP service instead according to instructions in DigiDoc4j documentation. See also the [corresponding section in _web-eid-authtoken-validation-java_ README](https://github.com/web-eid/web-eid-authtoken-validation-java/blob/main/README.md#certificates-authority-information-access-aia-extension).
+In the `SigningService` constructor we have configured DigiDoc4j to use the AIA extension that contains the certificates’ OCSP service location with `signingConfiguration.setPreferAiaOcsp(true)`. Note that there may be limitations to using AIA URLs during signing as the services behind these URLs provide different security and SLA guarantees than dedicated OCSP services, so you should consider using a dedicated OCSP service instead. See the instructions in DigiDoc4j documentation and also the [corresponding section in _web-eid-authtoken-validation-java_ README](https://github.com/web-eid/web-eid-authtoken-validation-java/blob/main/README.md#certificates-authority-information-access-aia-extension).
 
 #### Using DigiDoc4j in test mode with the `dev` profile
 
-When using DigiDoc4j in test mode with a test eID card, you need to upload the corresponding authentication and signing certificates to the _demo.sk.ee_ OCSP responder database at https://demo.sk.ee/upload_cert/index.php, according to instructions on the webpage. You can choose the certificate status during upload, so you can test bad statuses as well as needed.
+When using DigiDoc4j in test mode with a test eID card, you need to upload the corresponding authentication and signing certificates to the _demo.sk.ee_ OCSP responder database at https://demo.sk.ee/upload_cert/index.php, according to instructions on the webpage. You can choose the certificate status during upload, so you can also test bad statuses.
 
 #### Using DigiDoc4j in production mode with the `prod` profile
 
 When using DigiDoc4j in production mode, you need access to a paid timestamping service by registering your server's IP address with the service provider. Besides that, you may want to use a paid OCSP service for legal and reliability reasons as described above.
 
 ### Stateful and stateless authentication
 
-In the current example, we use the classical stateful Spring Security session cookie-based authentication mechanism where a cookie that contains the user session ID is set during successful login and session data is stored at sever side. Cookie-based authentication must be protected against cross-site request forgery (CSRF) attacks and extra measures must be taken to secure the cookies by serving them only over HTTPS and setting the _HttpOnly_, _Secure_ and _SameSite_ attributes.
+In the current example we use the classical stateful Spring Security session cookie-based authentication mechanism, where a cookie that contains the user session ID is set during successful login and session data is stored at sever side. Cookie-based authentication must be protected against cross-site request forgery (CSRF) attacks and extra measures must be taken to secure the cookies by serving them only over HTTPS and setting the _HttpOnly_, _Secure_ and _SameSite_ attributes.
 
-A common alternative to stateful authentication is stateless authentication with JSON Web Tokens (JWT) where the session data resides inside the token at client side. The Web eID authentication token itself is a JWT token, but it should be considered a temporary authentication information carrier during login and should not be used afterwards. In case you want to use JWT authentication, you should issue a new JWT after successful Web eID authentication token validation.
+A common alternative to stateful authentication is stateless authentication with JSON Web Tokens (JWT) or secure cookie sessions where the session data resides at client side browser and is either signed or encrypted. Secure cookie sessions are described in [RFC 6896](https://datatracker.ietf.org/doc/html/rfc6896) and in the following [article about secure cookie-based Spring Security sessions](https://www.innoq.com/en/blog/cookie-based-spring-security-session/). Usage of both an anonymous session and a cache is required to store the challenge nonce and the time it was issued before the user is authenticated. The anonymous session must be used for protection against [forged login attacks](https://en.wikipedia.org/wiki/Cross-site_request_forgery#Forging_login_requests) by guaranteeing that the authentication token is received from the same browser to which the corresponding challenge nonce was issued. The cache must be used for protection against replay attacks by guaranteeing that each authentication token can be used exactly once.
 
 ### Assuring that the signing and authentication certificate subjects match
 
-It usually required to verify that the signing certificate subject matches the authentication certificate subject by assuring that both ID codes match. This check is implemented at the beginning of the `SigningService.prepareContainer()` method.
+It is usually required to verify that the signing certificate subject matches the authentication certificate subject by assuring that both ID codes match. This check is implemented at the beginning of the `SigningService.prepareContainer()` method.
 
 ## HTTPS support
 
@@ -176,7 +179,7 @@ There are two ways of adding HTTPS support to a Spring Boot application:
 The first approach is straightforward and documented in the [official documentation](https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#howto.webserver.configure-ssl).
 
 The second approach, running behind a reverse proxy, is common in enterprise
-deployments and the configuration is more involved. We assume this setup in the
+deployments and the configuration is more complex. We assume this setup in the
 current project and document it in this section to facilitate production deployment.
 
 Enabling HTTPS support when running behind a reverse proxy server requires
@@ -243,3 +246,12 @@ This is most likely caused by an expired CSRF token. Please refresh the page and
 ### Why do I get the `"Access denied to TSP service"` error?
 
 This error means that access was denied to the timestamping service. You are running in production mode with the `prod` profile and need to register for paid access to the timestamping service as described in section [_Using DigiDoc4j in production mode with the `prod` profile_](#using-digidoc4j-in-production-mode-with-the-prod-profile) above.
+
+### Why can I not use my test ID card?
+
+When running the application with the `dev` profile in test mode, you need to upload the corresponding authentication and signing certificates to the _demo.sk.ee_ OCSP responder database at <https://demo.sk.ee/upload_cert/index.php>, according to instructions on the webpage.
+
+### Why do I get the `401 Unauthorized "Authentication failed: Web eID token validation failed"` response during authentication?
+
+One possible reason is that you are using the test ID card on a site that is running in production mode or, vice-versa, a real ID card on a site that is running in test mode; or any other ID card whose certificate authority has not been added to the list of trusted certificate authorities.
+
diff --git a/example/src/main/resources/templates/index.html b/example/src/main/resources/templates/index.html
@@ -234,7 +234,7 @@ <h3><a id="for-developers"></a>For developers</h3>
             const challengeResponse = await fetch("/auth/challenge", {
                 method: "GET",
                 headers: {
-                    'Content-Type': 'application/json'
+                    "Content-Type": "application/json"
                 }
             });
             await checkHttpError(challengeResponse);
@@ -245,7 +245,7 @@ <h3><a id="for-developers"></a>For developers</h3>
             const authTokenResponse = await fetch("/auth/login", {
                 method: "POST",
                 headers: {
-                    'Content-Type': 'application/json',
+                    "Content-Type": "application/json",
                     [csrfHeaderName]: csrfToken
                 },
                 body: `{"auth-token": ${JSON.stringify(authToken)}}`
diff --git a/example/src/main/resources/templates/welcome.html b/example/src/main/resources/templates/welcome.html
@@ -86,7 +86,7 @@ <h2 class="adding-signature">Digital signing</h2>
             const prepareSigningResponse = await fetch("/sign/prepare", {
                 method: "POST",
                 headers: {
-                    'Content-Type': 'application/json',
+                    "Content-Type": "application/json",
                     [csrfHeaderName]: csrfToken
                 },
                 body: JSON.stringify({certificate, supportedSignatureAlgorithms}),
@@ -105,7 +105,7 @@ <h2 class="adding-signature">Digital signing</h2>
             const finalizeSigningResponse = await fetch("/sign/sign", {
                 method: "POST",
                 headers: {
-                    'Content-Type': 'application/json',
+                    "Content-Type": "application/json",
                     [csrfHeaderName]: csrfToken
                 },
                 body: JSON.stringify({signature, signatureAlgorithm}),
