Web eID enables usage of European Union electronic identity (eID) smart cards for secure authentication and digital signing of documents on the web using public-key cryptography.
@@ -196,8 +196,9 @@ A REST endpoint that issues challenge nonces is required for authentication. The
In the following example, we are using the [ASP.NET Web APIs RESTful Web Services framework](https://dotnet.microsoft.com/apps/aspnet/apis) to implement the endpoint, see also full implementation [here](https://github.com/web-eid/web-eid-authtoken-validation-dotnet/blob/main/example/src/WebEid.AspNetCore.Example/Controllers/Api/AuthController.cs).
```cs
+using System;
using Microsoft.AspNetCore.Mvc;
-using WebEid.Security.Nonce;
+using WebEid.Security.Challenge;
[ApiController]
[Route("auth")]
@@ -253,66 +254,186 @@ When using standard [ASP.NET cookie authentication](https://docs.microsoft.com/e
using System;
using System.Collections.Generic;
using System.Security.Claims;
- using System.Text.Json.Serialization;
+ using System.Text.Json;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.Cookies;
using Microsoft.AspNetCore.Mvc;
+ using WebEid.AspNetCore.Example.Dto;
+ using WebEid.Security.AuthToken;
+ using WebEid.Security.Challenge;
+ using WebEid.Security.Exceptions;
using WebEid.Security.Util;
using WebEid.Security.Validator;
[Route("[controller]")]
[ApiController]
- public class AuthController : ControllerBase
+ public class AuthController(IAuthTokenValidator authTokenValidator, IChallengeNonceStore challengeNonceStore) : BaseController
{
- private readonly IAuthTokenValidator authTokenValidator;
+ private readonly IAuthTokenValidator authTokenValidator = authTokenValidator;
+ private readonly IChallengeNonceStore challengeNonceStore = challengeNonceStore;
- public AuthController(IAuthTokenValidator authTokenValidator, IChallengeNonceStore challengeNonceStore)
+ [HttpPost("login")]
+ public async Task
This project is an example ASP.NET 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/).
-The ASP.NET web application makes use of the following technologies:
-
-- ASP.NET MVC,
-- the Web eID authentication token validation library [_web-eid-authtoken-validation-dotnet_](https://github.com/web-eid/web-eid-authtoken-validation-dotnet),
-- the Web eID JavaScript library [_web-eid.js_](https://github.com/web-eid/web-eid.js),
-- the digital signing library [_libdigidocpp_](https://github.com/open-eid/libdigidocpp/tree/master/examples/DigiDocCSharp).
-
## Quickstart
Complete the steps below to run the example application in order to test authentication and digital signing with Web eID.
@@ -91,8 +84,8 @@ Set up the `libdigidocpp` library as follows:
1. Install the _libdigidocpp-4.0.0.8301.x64.msi_ package or higher. The installation packages are available from [https://github.com/open-eid/libdigidocpp/releases](https://github.com/open-eid/libdigidocpp/releases).
2. Copy the C# source files from the `libdigidocpp` installation folder `include\digidocpp_csharp` to the `src\WebEid.AspNetCore.Example\DigiDoc` folder.
-3. Copy all files from the `libdigidocpp` installation folder to the example application build output folder `bin\Debug\net8.0` (after building, see next step).
- * Windows: Also copy folder `schema` from `libdigidocpp` installation folder to the example application build output folder `bin\Debug\net8.0`
+3. Copy all files from the `libdigidocpp` installation folder to the example application build output folder `bin\Debug\net10.0` (after building, see next step).
+ * Windows: Also copy folder `schema` from `libdigidocpp` installation folder to the example application build output folder `bin\Debug\net10.0`
4. When running in the `Development` profile, create an empty file named `EE_T.xml` for TSL cache as described in the [_Using test TSL lists_](https://github.com/open-eid/libdigidocpp/wiki/Using-test-TSL-lists#preconditions) section of the `libdigidocpp` wiki.
#### For Ubuntu Linux
@@ -123,7 +116,7 @@ Set up the `libdigidocpp` library as follows:
1. Install the *libdigidocpp_4.0.0.1460.pkg* package or higher. The installation packages are available from [https://github.com/open-eid/libdigidocpp/releases](https://github.com/open-eid/libdigidocpp/releases).
2. Copy the C# source files from `/Library/libdigidocpp/include/digidocpp_csharp` directory to `src/WebEid.AspNetCore.Example/DigiDoc` directory.
-3. Go to `bin/Debug/net8.0` directory and create symbolic link to `/Library/libdigidocpp/lib/libdigidoc_csharp.dylib` library:
+3. Go to `bin/Debug/net10.0` directory and create symbolic link to `/Library/libdigidocpp/lib/libdigidoc_csharp.dylib` library:
```cmd
ln -s /Library/libdigidocpp/lib/libdigidoc_csharp.dylib
```
@@ -132,7 +125,7 @@ Further information is available in the [libdigidocpp example C# application sou
### 5. Build the application
-You need to have the [.NET 8.0 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) installed for building the application package.
+You need to have the [.NET 10.0 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) installed for building the application package.
Build the application by running the following command in a terminal window under the `src` directory:
```cmd
@@ -160,7 +153,32 @@ This will activate the `https` profile in the `launchSettings.json` and launch t
When the application has started, open your preferred web browser on the address defined in `launchSettings.json` on the `applicationUrl` field at `https` profile and follow instructions on the front page.
By default the address is https://localhost:44391.
-## Overview of the source code
+## Table of contents
+
+* [Quickstart](#quickstart)
+* [Setup for Development](#setup-for-development)
+* [Overview of the project](#overview-of-the-project)
+ + [Overview of the source code](#overview-of-the-source-code)
+ + [Requesting the signing certificate in a separate step](#requesting-the-signing-certificate-in-a-separate-step)
+* [More information](#more-information)
+ + [Frequently asked questions](#frequently-asked-questions)
+ - [Why do I get the `System.ApplicationException: Failed to verify OCSP Responder certificate` error during signing?](#why-do-i-get-the-systemapplicationexception-failed-to-verify-ocsp-responder-certificate-error-during-signing)
+* [Building and running example web application with Docker on Ubuntu Linux](#building-and-running-example-web-application-with-docker-on-ubuntu-linux)
+ + [Prerequisites](#prerequisites)
+ + [Building the application](#building-the-application)
+ + [Building the Docker image](#building-the-docker-image)
+* [Running the Docker container with HTTPS support](#running-the-docker-container-with-https-support)
+
+## Overview of the project
+
+The ASP.NET web application makes use of the following technologies:
+
+- ASP.NET MVC,
+- the Web eID authentication token validation library [_web-eid-authtoken-validation-dotnet_](https://github.com/web-eid/web-eid-authtoken-validation-dotnet),
+- the Web eID JavaScript library [_web-eid.js_](https://github.com/web-eid/web-eid.js),
+- the digital signing library [_libdigidocpp_](https://github.com/open-eid/libdigidocpp/tree/master/examples/DigiDocCSharp).
+
+### Overview of the source code
The `src\WebEid.AspNetCore.Example` directory contains the ASP.NET application source code and resources. The subdirectories therein have the following purpose:
- `wwwroot`: web server static content, including CSS and JavaScript files,
@@ -170,8 +188,23 @@ The `src\WebEid.AspNetCore.Example` directory contains the ASP.NET application s
- logging in,
- digital signing,
- `DigiDoc`: contains the C# binding files of the `libdigidocpp` library; these files must be copied from the `libdigidocpp` installation directory `\include\digidocpp_csharp`,
+- `Dto`: data transfer objects used by the Web API endpoints,
- `Pages`: Razor pages,
-- `Signing`: Web eID signing service implementation that uses `libdigidocpp`.
+- `Services`: helper services for cleaning up signing containers and for building the mobile authentication and signing request URIs,
+- `Signing`: Web eID signing service implementation that uses `libdigidocpp`,
+ - `SigningService`: prepares signing containers and finalizes signatures,
+ - `MobileSigningService`: orchestrates the mobile signing flow (builds mobile signing requests/responses) and supports requesting the signing certificate in a separate step when enabled by configuration,
+- `Options`: strongly-typed configuration classes for mobile Web eID settings such as `BaseRequestUri` and `RequestSigningCert` (when set to false, initiates a separate signing-certificate flow to demo requesting the certificate without prior authentication, as the signing certificate normally comes from the authentication flow).
+
+### Requesting the signing certificate in a separate step
+
+In some deployments, the signing certificate is not reused from the authentication flow. Instead, it is retrieved directly from the user’s ID-card during the signing process itself.
+
+This approach is useful when the signing process is performed without a prior authentication step. For example, in a mobile flow, the user may start signing directly without authenticating beforehand. In such cases, the signing certificate must be requested separately from the user’s ID-card before the signature can be created.
+
+When this mode is enabled in the configuration, the backend issues a separate request for the signing certificate using the `MobileSigningService`. The service communicates with the client to obtain the certificate before the signing container is prepared, ensuring that the correct certificate chain is available for the signature.
+
+This behavior is controlled by the `RequestSigningCert` flag in the `appsettings.json` configuration files (`appsettings.json`, `appsettings.Development.json`). When the flag is set to **false**, the application explicitly requests the signing certificate during the signing process, demonstrating the separate signing certificate retrieval flow. When set to **true**, the signing uses the signing certificate that was already obtained during authentication, and no additional request is made.
## More information
@@ -192,7 +225,7 @@ then please follow these steps in this chapter to build a Docker image in Ubuntu
Before you begin, ensure you have the following installed on your system:
-- .NET SDK 8.0
+- .NET SDK 10.0
- libdigidocpp-csharp
You can install them using the following commands:
@@ -205,7 +238,7 @@ sudo apt update
```
then install the packages
```sh
-sudo apt install dotnet-sdk-8.0 libdigidocpp-csharp
+sudo apt install dotnet-sdk-10.0 libdigidocpp-csharp
```
Add a NuGet package source for web-eid-authtoken-validation-dotnet library:
@@ -238,7 +271,7 @@ To build the application, follow these steps:
4. Update the `OriginUrl` in the `appsettings.json` to match your production environment. Please replace https://localhost:8443 with your actual domain name where you intend to run the application:
```sh
- sed -i 's#"OriginUrl": "https://localhost:44391"#"OriginUrl": "https://localhost:8443"#' WebEid.AspNetCore.Example/bin/Release/net8.0/publish/appsettings.json
+ sed -i 's#"OriginUrl": "https://localhost:44391"#"OriginUrl": "https://example.com"#' WebEid.AspNetCore.Example/bin/Release/net10.0/publish/appsettings.json
```
### Building the Docker image
@@ -299,3 +332,13 @@ app.UseForwardedHeaders(new ForwardedHeadersOptions
By default, this middleware is already enabled in the application.
A Docker Compose configuration file `docker-compose.yml` is available in the `src` directory for running the Docker image `web-eid-asp-dotnet-example` on port 8480 behind a reverse proxy.
+
+# Code formatting
+
+The project uses `.editorconfig` for .NET code formatting rules.
+
+To format the library code, run:
+
+```bash
+dotnet format example/src/WebEid.AspNetCore.Example.sln --no-restore
+```
diff --git a/example/src/.dockerignore b/example/src/.dockerignore
index 50e2413e..cc331793 100644
--- a/example/src/.dockerignore
+++ b/example/src/.dockerignore
@@ -24,4 +24,4 @@
LICENSE
README.md
-!WebEid.AspNetCore.Example/bin/Release/net8.0/publish/
+!WebEid.AspNetCore.Example/bin/Release/net10.0/publish/
diff --git a/example/src/.editorconfig b/example/src/.editorconfig
new file mode 100644
index 00000000..eadfeba8
--- /dev/null
+++ b/example/src/.editorconfig
@@ -0,0 +1,453 @@
+# Version: 4.1.1 (Using https://semver.org/)
+# Updated: 2022-05-23
+# See https://github.com/RehanSaeed/EditorConfig/releases for release notes.
+# See https://github.com/RehanSaeed/EditorConfig for updates to this file.
+# See http://EditorConfig.org for more information about .editorconfig files.
+#
+# Modified by Erkki Arus (erkki@raulwalter.com) on 2023-07-17 - disabled IDE0009 warning.
+
+##########################################
+# Common Settings
+##########################################
+
+# This file is the top-most EditorConfig file
+root = true
+
+# All Files
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 4
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+##########################################
+# File Extension Settings
+##########################################
+
+# Visual Studio Solution Files
+[*.sln]
+indent_style = tab
+
+# Visual Studio XML Project Files
+[*.{csproj,vbproj,vcxproj.filters,proj,projitems,shproj}]
+indent_size = 2
+
+# XML Configuration Files
+[*.{xml,config,props,targets,nuspec,resx,ruleset,vsixmanifest,vsct}]
+indent_size = 2
+
+# JSON Files
+[*.{json,json5,webmanifest}]
+indent_size = 2
+
+# YAML Files
+[*.{yml,yaml}]
+indent_size = 2
+
+# Markdown Files
+[*.{md,mdx}]
+trim_trailing_whitespace = false
+
+# Web Files
+[*.{htm,html,js,jsm,ts,tsx,cjs,cts,ctsx,mjs,mts,mtsx,css,sass,scss,less,pcss,svg,vue}]
+indent_size = 2
+
+# Batch Files
+[*.{cmd,bat}]
+end_of_line = crlf
+
+# Bash Files
+[*.sh]
+end_of_line = lf
+
+# Makefiles
+[Makefile]
+indent_style = tab
+
+##########################################
+# Default .NET Code Style Severities
+# https://docs.microsoft.com/dotnet/fundamentals/code-analysis/configuration-options#scope
+##########################################
+
+[*.{cs,csx,cake,vb,vbx}]
+# Default Severity for all .NET Code Style rules below
+dotnet_analyzer_diagnostic.severity = warning
+dotnet_diagnostic.CA1848.severity = suggestion
+
+##########################################
+# Language Rules
+# https://docs.microsoft.com/dotnet/fundamentals/code-analysis/style-rules/language-rules
+##########################################
+
+# .NET Style Rules
+# https://docs.microsoft.com/dotnet/fundamentals/code-analysis/style-rules/language-rules#net-style-rules
+[*.{cs,csx,cake,vb,vbx}]
+# "this." and "Me." qualifiers
+dotnet_style_qualification_for_field = false:warning
+dotnet_style_qualification_for_property = false:warning
+dotnet_style_qualification_for_method = false:warning
+dotnet_style_qualification_for_event = false:warning
+# Language keywords instead of framework type names for type references
+dotnet_style_predefined_type_for_locals_parameters_members = true:warning
+dotnet_style_predefined_type_for_member_access = true:warning
+# Modifier preferences
+dotnet_style_require_accessibility_modifiers = always:warning
+csharp_preferred_modifier_order = public,private,protected,internal,static,extern,new,virtual,abstract,sealed,override,readonly,unsafe,volatile,async:warning
+visual_basic_preferred_modifier_order = Partial,Default,Private,Protected,Public,Friend,NotOverridable,Overridable,MustOverride,Overloads,Overrides,MustInherit,NotInheritable,Static,Shared,Shadows,ReadOnly,WriteOnly,Dim,Const,WithEvents,Widening,Narrowing,Custom,Async:warning
+dotnet_style_readonly_field = true:warning
+# Parentheses preferences
+dotnet_style_parentheses_in_arithmetic_binary_operators = always_for_clarity:warning
+dotnet_style_parentheses_in_relational_binary_operators = always_for_clarity:warning
+dotnet_style_parentheses_in_other_binary_operators = always_for_clarity:warning
+dotnet_style_parentheses_in_other_operators = never_if_unnecessary:warning
+# Expression-level preferences
+dotnet_style_object_initializer = true:warning
+dotnet_style_collection_initializer = true:warning
+dotnet_style_explicit_tuple_names = true:warning
+dotnet_style_prefer_inferred_tuple_names = true:warning
+dotnet_style_prefer_inferred_anonymous_type_member_names = true:warning
+dotnet_style_prefer_auto_properties = true:warning
+dotnet_style_prefer_conditional_expression_over_assignment = false:suggestion
+dotnet_diagnostic.IDE0045.severity = suggestion
+dotnet_style_prefer_conditional_expression_over_return = false:suggestion
+dotnet_diagnostic.IDE0046.severity = suggestion
+dotnet_style_prefer_compound_assignment = true:warning
+dotnet_style_prefer_simplified_interpolation = true:warning
+dotnet_style_prefer_simplified_boolean_expressions = true:warning
+# Null-checking preferences
+dotnet_style_coalesce_expression = true:warning
+dotnet_style_null_propagation = true:warning
+dotnet_style_prefer_is_null_check_over_reference_equality_method = true:warning
+# File header preferences
+# file_header_template = - Estonian, Finnish, Latvian, Lithuanian and Croatian eID cards are supported in the first phase, but only - Estonian eID card support is currently enabled in the test application below. + Estonian, Finnish, Latvian, Lithuanian, Belgian and Croatian eID cards are supported in the first + phase, + but only Estonian eID card support is currently enabled in the test application below.
- Please get in touch by email at help@ria.ee in case you need support with adding Web eID to your project + Please get in touch by email at help@ria.ee in case you need support with adding Web eID to your + project or want to add support for a new eID card to Web eID.
+The privacy policy of the test service is available here. +
- More information about the Web eID project, including installation and usage instructions - is available on the project [website](https://web-eid.eu/). -
-Click Authenticate below to test authentication and digital signing.
+- -
+The recommended way of installing Web eID is by installing + the latest Open-EID ID-software + package. + In case you do not need or want to install the Open-EID package, install the latest Web eID packages + in + Firefox, Chrome, Edge or Safari according to the following instructions: +
+install-web-eid.sh
+ script from the console withwget -O - https:///scripts/install-web-eid.sh
+ | bashTesting:
+- The privacy policy of the test service is available here. -
-+ +
+ +The uninstaller will remove the browser extension from all supported browsers + automatically.
+ +Uninstall the Web eID software either using the Ubuntu Software Center or from the
+ console with
+ sudo apt purge web-eid
+
To uninstall the Web eID software, do the following:
+uninstall.sh from the downloaded file to the
+ Terminal window,
+ Uninstall the Web eID software using Add or remove programs.
+echo 'logging=true' > ~/.config/RIA/web-eid.conf
+ defaults write \ "$HOME/Library/Containers/eu.web-eid.web-eid/Data/Library/Preferences/eu.web-eid.web-eid.plist"
+ \ logging truedefaults write
+ "$HOME/Library/Containers/eu.web-eid.web-eid-safari/Data/Library/Preferences/eu.web-eid.web-eid-safari.plist"
+ \ logging true[HKEY_CURRENT_USER\SOFTWARE\RIA\web-eid]"logging"="true"
+ ~/.local/share/RIA/web-eid/web-eid.log in Linux~/Library/Containers/eu.web-eid.web-eid/Data/Library/Application\
+ Support/RIA/web-eid/web-eid.log in macOS
+ ~/Library/Containers/eu.web-eid.web-eid-safari/Data/Library/Application\
+ Support/RIA/web-eid-safari/web-eid-safari.log
+ of Safari in macOS
+ C:/Users/<USER>/AppData/Local/RIA/web-eid/web-eid.log
+ in
+ Windows.
+ web-eid
+ manually,
+ there will be an informative message in the logs.
+ + Technical overview of the solution is available in the project + system + architecture + document. + Overview of authentication token validation implementation in the back end is + available + in the + web-eid-authtoken-validation-java Java library + README. +
++ Security analysis of the solution is available + in + this + document. +
++ Currently the Web eID back-end libraries are available for Java, .NET and PHP web + applications. +
++ To implement authentication and digital signing with Web eID in a Java, .NET or PHP + web + application, + you need to +
++ The full source code of an example Spring Boot web application that uses Web eID for + authentication + and digital signing is available + here. + The .NET/C# version of the example is available + here. + The PHP version of the example is available + here. +
+The Web eID solution can also be used without installing the Web eID native app and browser + extension. + This includes devices like mobile phones, tablets, and some Chromebooks, where the Web eID plugin + cannot + currently be installed. +
++ +
+ ++ Technical overview of the solution is available in the project + system + architecture document. + Overview of authentication token validation implementation in the back end is + available + in the + web-eid-authtoken-validation-java Java library + README. +
+ +
+