Skip to content

Commit

Permalink
Copied instructions for adding Web eID authentication token validatio…
Browse files Browse the repository at this point in the history 
…n library to the project from web-eid-authtoken-validation-dotnet repository.

WE2-572

Signed-off-by: Mihkel Kivisild mihkel.kivisild@cgi.com
  • Loading branch information
Mihkel Kivisild committed Nov 11, 2024
1 parent c787653 commit fcc35b7
Show file tree
Hide file tree
Showing 2 changed files with 59 additions and 36 deletions.
81 changes: 52 additions & 29 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,42 +13,71 @@ The ASP.NET web application makes use of the following technologies:
- 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).

Note that for including the Web eID authentication token validation library as a nuget package you need to have added a Package Source with the following address to the NuGet Package Manager:
https://gitlab.com/api/v4/projects/35362906/packages/nuget/index.json

## Quickstart

Complete the steps below to run the example application in order to test authentication and digital signing with Web eID.

### 1. Configure the origin URL
### 1. Add the Web eID authentication token validation library to your project

#### When using Visual Studio

1. Configure Web eID GitLab package repository as a NuGet package source.
In MS Visual Studio, go to the **Tools** > **NuGet Package Manager** > **Package Manager Settings** menu command. Select **Package Sources** and add a new source. Name it _Web eID GitLab_ and set the _Source_ URL to `https://gitlab.com/api/v4/projects/35362906/packages/nuget/index.json`.

2. Install the `WebEid.Security` NuGet package.
You can install the package either from the GUI or the Package Manager Console.

- From GUI:
Right-click the project in the Solution Explorer where you want to install the Web eID dependency. Select **Manage NuGet Packages**. Choose the _Web eID GitLab_ package source you added earlier from the _Package source_ dropdown. Then, install the `WebEid.Security` package.


- From Package Manager Console:
Run the following command:
```
Install-Package WebEid.Security
```

#### When using `dotnet` CLI

In case you prefer using command line tools, you can add the package using the `dotnet` CLI with the following command:

```
dotnet add package WebEid.Security --source https://gitlab.com/api/v4/projects/35362906/packages/nuget/index.json
```

**Note:** When you install a package, NuGet records the dependency in either your project file or a `packages.config` file, depending on the selected package management format (`Packages.config` or `PackageReference`).

For more detailed information on different methods of installing NuGet packages, refer to [Microsoft's official documentation](https://learn.microsoft.com/en-us/nuget/consume-packages/overview-and-workflow#ways-to-install-a-nuget-package).

### 2. Configure the origin URL

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, add `OriginUrl` field in the application settings file `appsettings.json` as follows:
To configure the origin URL, add `OriginUrl` field in the application settings file in either `appsettings.Development.json` for `Development` profile or `appsettings.json` for `Production` profile as follows:
```json
{
"OriginUrl": "https://example.org"
}
```
Note that the URL **must not end with a slash** `/`.
Note that the URL **must not end with a slash** `/` and the URL must be the same as the `applicationUrl` in `launchSettings.json`. When you change the `OriginUrl`, also change the `applicationUrl` in `launchSettings.json`.

### 2. Configure the trusted certificate authority certificates
### 3. Configure the trusted certificate authority certificates

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 from `.cer` files in the profile-specific subdirectory of the [`Certificates` resource directory](https://github.com/web-eid/web-eid-asp-dotnet-example/src/WebEid.AspNetCore.Example/Certificates). By default, Estonian eID test CA certificates are included in the `Development` profile and production CA certificates in the `Production` 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 from `.cer` files in the profile-specific subdirectory of the [`Certificates` resource directory](https://github.com/web-eid/web-eid-asp-dotnet-example/tree/main/src/WebEid.AspNetCore.Example/Certificates). By default, Estonian eID test CA certificates are included in the `Development` profile and production CA certificates in the `Production` profile.

In case you need to provide your own CA certificates, add the `.cer` files to the `src/WebEid.AspNetCore.Example/Certificates/{Dev,Prod}` profile-specific directory.

### 3. Setup the `libdigidocpp` library for signing
### 4. Setup the `libdigidocpp` library for signing

`libdigidocpp` is a library for creating, signing and verifying digitally signed documents according to XAdES and XML-DSIG standards. It is a C++ library that has [SWIG](http://swig.org/) bindings for C#.

Set up the `libdigidocpp` library as follows:

#### For MS Windows

1. Install the _libdigidocpp-3.17.1.msi_ package or higher. The installation packages are available from [https://github.com/open-eid/libdigidocpp/releases](https://github.com/open-eid/libdigidocpp/releases).
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 either the `x64` subfolder of the `libdigidocpp` installation folder to the example application build output folder `bin\...\net8.0` (after building, see next step). When building custom applications, choose `x64` if your application is 64-bit and `x86` if it is 32-bit.
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).
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
Expand All @@ -72,51 +101,49 @@ Set up the `libdigidocpp` library as follows:
4. Copy the necessary DigiDoc C# library files into your project:

```sh
cp /usr/include/digidocpp_csharp/* WebEid.AspNetCore.Example/DigiDoc/
cp /usr/include/digidocpp_csharp/* /usr/lib/x86_64-linux-gnu/libdigidoc_csharp.so WebEid.AspNetCore.Example/DigiDoc/
```

#### For macOS

1. Install the _libdigidocpp-3.17.1.pkg_ package or higher. The installation packages are available from [https://github.com/open-eid/libdigidocpp/releases](https://github.com/open-eid/libdigidocpp/releases).
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 `src/WebEid.AspNetCore.Example/bin/.../net8.0` directory and create symbolic link to `/Library/libdigidocpp/lib/libdigidoc_csharp.dylib` library:
3. Go to `bin/Debug/net8.0` directory and create symbolic link to `/Library/libdigidocpp/lib/libdigidoc_csharp.dylib` library:
```cmd
ln -s /Library/libdigidocpp/lib/libdigidoc_csharp.dylib
```

Further information is available in the [libdigidocpp example C# application source code](https://github.com/open-eid/libdigidocpp/tree/master/examples/DigiDocCSharp) and in the [`libdigidocpp` Wiki](https://github.com/open-eid/libdigidocpp/wiki).

### 4. Build the application
### 5. Build the application

You need to have the [.NET 6.0 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/6.0) installed for building the application package.
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.
Build the application by running the following command in a terminal window under the `src` directory:

```cmd
dotnet build
```

### 5. Choose either the `Development` or `Production` profile
### 6. Choose either the `Development` or `Production` profile

If you have a test eID card, use the `Development` profile. In this case access to paid services is not required, but you need to upload the authentication and signing certificates of the test card to the test OCSP responder database as described in section _[Using DigiDoc4j in test mode with the `dev` profile](https://github.com/web-eid/web-eid-spring-boot-example#using-digidoc4j-in-test-mode-with-the-dev-profile)_ of the Web eID Java example application documentation. The`Development` profile is activated by default.

If you only have a production eID card, i.e. an eID card issued to a real person or organization, use the `Production` profile. You can still test authentication without further configuration; however, for digital signing to work, you need access to a paid timestamping service as described in section [_Using DigiDoc4j in production mode with the `prod` profile_](https://github.com/web-eid/web-eid-spring-boot-example#using-digidoc4j-in-production-mode-with-the-prod-profile) of the Web eID Java example documentation.

You can specify the profile as an environment variable `ASPNETCORE_ENVIRONMENT` when running the application. To set the profile for the current session before starting the app using [`dotnet run`](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-run), use the following command:
```cmd
set ASPNETCORE_ENVIRONMENT=Production
```
You can specify the profile as an environment variable `ASPNETCORE_ENVIRONMENT` when running the application. To set the profile for the current session before starting the app using dotnet run, edit the appropriate profile in the `launchSettings.json` file located at `src/WebEid.AspNetCore.Example/Properties/`. Modify the `environmentVariables` section in the `launchSettings.json` file by setting the `ASPNETCORE_ENVIRONMENT` to `Production`.

### 6. Run the application
### 7. Run the application

Run the application with the following command in a terminal window under the `src` directory:

```cmd
dotnet run --project WebEid.AspNetCore.Example
```

This will activate the default `Development` profile and launch the built-in `kestrel` web server on HTTPS port 5001.
This will activate the `https` profile in the `launchSettings.json` and launch the built-in `kestrel` web server on the defined `applicationUrl`.

When the application has started, open https://localhost:5001 in your preferred web browser and follow instructions on the front page.
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

Expand All @@ -129,7 +156,7 @@ The `src\WebEid.AspNetCore.Example` directory contains the ASP.NET application s
- 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`,
- `Pages`: Razor pages,
- `Services`: Web eID signing service implementation that uses `libdigidocpp`.
- `Signing`: Web eID signing service implementation that uses `libdigidocpp`.

## More information

Expand All @@ -141,10 +168,6 @@ See the [Web eID Java example application documentation](https://github.com/web-

You are running in the `Development` profile, but you have not created an empty file named `EE_T.xml` for TSL cache. Creating the file is mandatory and is described in more detail in the [_Using test TSL lists_](https://github.com/open-eid/libdigidocpp/wiki/Using-test-TSL-lists#preconditions) section of the `libdigidocpp` wiki.

#### Why do I get the `System.BadImageFormatException: An attempt was made to load a program with an incorrect format` error during signing?

You are using `libdigidocpp` DLLs for the wrong architecture. Copy files from the `x64` subfolder of the `libdigidocpp` installation folder to right place as described in the section _3. Setup the `libdigidocpp` library for signing_ above. In case you get this error while developing a custom 32-bit application, copy files from the `x86` subfolder instead.

## Building and running with Docker on Ubuntu Linux

This section covers the steps required to build the application on an Ubuntu Linux environment and run it using Docker.
Expand Down
14 changes: 7 additions & 7 deletions src/WebEid.AspNetCore.Example/WebEid.AspNetCore.Example.csproj
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,14 @@
</PropertyGroup>

<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation" Version="8.0.7" />
<PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="8.0.7" NoWarn="NU1605" />
<PackageReference Include="Microsoft.AspNetCore.Authentication.OpenIdConnect" Version="8.0.7" NoWarn="NU1605" />
<PackageReference Include="Microsoft.Identity.Web" Version="2.20.0" />
<PackageReference Include="Microsoft.Identity.Web.UI" Version="2.20.0" />
<PackageReference Include="Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation" Version="8.0.10" />
<PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="8.0.10" NoWarn="NU1605" />
<PackageReference Include="Microsoft.AspNetCore.Authentication.OpenIdConnect" Version="8.0.10" NoWarn="NU1605" />
<PackageReference Include="Microsoft.Identity.Web" Version="3.3.1" />
<PackageReference Include="Microsoft.Identity.Web.UI" Version="3.3.1" />
<PackageReference Include="Microsoft.VisualStudio.Azure.Containers.Tools.Targets" Version="1.21.0" />
<PackageReference Include="System.Runtime.Caching" Version="8.0.0" />
<PackageReference Include="System.Text.Json" Version="8.0.4" />
<PackageReference Include="System.Runtime.Caching" Version="8.0.1" />
<PackageReference Include="System.Text.Json" Version="8.0.5" />
<PackageReference Include="WebEid.Security" Version="1.2.0" />
</ItemGroup>

Expand Down

0 comments on commit fcc35b7

Please sign in to comment.