From 65d72a63d56ae2cb483532e72c6e6480e041d3e4 Mon Sep 17 00:00:00 2001 From: Mart Aarma Date: Mon, 14 Sep 2026 13:19:39 +0300 Subject: [PATCH 1/2] Add guide for adding Web eID for Mobile support to an existing integration Add a short section to the library and example READMEs that lists only what an application with a working regular Web eID integration has to change or add for the mobile authentication flow, with links to the existing sections and example classes that implement each step. Signed-off-by: Mart Aarma Co-authored-by: Sander Kondratjev --- README.md | 16 ++++++++++++++-- example/README.md | 9 +++++++++ 2 files changed, 23 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 208ea1d..b520d37 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Additional information regarding the Web eID project can be found on the officia # Quickstart -Complete the steps below to add support for secure authentication with eID cards to your ASP.NET Core web application backend. Instructions for the frontend are available [here](https://github.com/web-eid/web-eid.js). +Complete the steps below to add support for secure authentication with eID cards to your ASP.NET Core web application backend. Instructions for the frontend are available [here](https://github.com/web-eid/web-eid.js). If your application already uses Web eID and you only need to add the mobile flow, see [Adding Web eID for Mobile support to an existing integration](#adding-web-eid-for-mobile-support-to-an-existing-integration). See full example [here](https://github.com/web-eid/web-eid-authtoken-validation-dotnet/tree/main/example). @@ -382,7 +382,7 @@ When using standard [ASP.NET cookie authentication](https://docs.microsoft.com/e Note that successful token validation only establishes *who* the user is; it does not establish that the user is allowed to use the service. The authorization check is application-specific and must be implemented by the application itself, as outlined by the `IsUserAuthorized()` stub above. -- Similarly, the `MobileAuthInitController` generates a challenge nonce and returns the authentication request link (OS-verified App Link / Universal Link) for starting the Web eID mobile authentication flow, and the `AuthController` handles the mobile login request by validating the returned authentication token and creating the authentication cookie. +- Similarly, the `MobileAuthInitController` generates a challenge nonce and returns the authentication request link (OS-verified App Link / Universal Link) for starting the Web eID mobile authentication flow, and the `AuthController` handles the mobile login request by validating the returned authentication token and creating the authentication cookie. The authentication token returned by the mobile app uses format `web-eid:1.1` when a signing certificate is requested, or `web-eid:1.0` for authentication only. ```cs using System; using System.Text; @@ -457,9 +457,21 @@ When using standard [ASP.NET cookie authentication](https://docs.microsoft.com/e } ``` +## Adding Web eID for Mobile support to an existing integration + +Reuse your existing challenge nonce generator and store, trusted CA configuration, token validation and authorization logic. The mobile flow adds an App Link/Universal Link that opens the RIA DigiDoc app and a login page that receives the response in its URL fragment and posts the token to your back end. Authentication-only responses use `web-eid:1.0`; requesting a signing certificate with `getSigningCertificate=true` requires a validator that supports `web-eid:1.1`. The validator configuration stays the same. + +1. Add `POST /auth/mobile/init` to generate and store a challenge nonce and return `authUri`: `https://mopp.ria.ee/auth#`, where the payload is Base64-encoded JSON containing `challenge`, `loginUri` and optionally `getSigningCertificate` ([init controller](example/src/WebEid.AspNetCore.Example/Controllers/Api/MobileAuthInitController.cs)). Set `WebEidMobile:BaseRequestUri` to `https://mopp.ria.ee` for the RIA DigiDoc app; the example defaults to the development scheme `web-eid-mobile://`. Configure `WebEidMobile:RequestSigningCert` as needed. +2. Serve `GET /auth/mobile/login` at an HTTPS `loginUri` on the validator's configured `OriginUrl`. Its script must decode the response, handle errors and post `authToken` to the existing `POST /auth/login` endpoint ([login page](example/src/WebEid.AspNetCore.Example/Pages/WebEidLogin.cshtml), [payload parser](example/src/WebEid.AspNetCore.Example/wwwroot/js/payload.js)). Retrieve and consume the session's unexpired challenge nonce, validate the token, apply your authorization checks and establish the authenticated session as before. +3. Use `Secure`, `HttpOnly`, `SameSite=Lax` for the pre-authentication session cookie so it accompanies the return from the app. Keep CSRF protection on POST endpoints ([Startup.cs](example/src/WebEid.AspNetCore.Example/Startup.cs)) and protect the login page against XSS. Callback fragments are untrusted input; the CSRF token alone does not authenticate them. See the architecture document's [security assumptions](https://github.com/web-eid/web-eid-for-mobile-architecture-doc#security-assumptions). +4. Add a mobile login button that calls the init endpoint and opens the returned `authUri` ([front end](example/src/WebEid.AspNetCore.Example/Pages/Index.cshtml)). Keep the existing desktop login control. + +Optional mobile signing is demonstrated by [SignController](example/src/WebEid.AspNetCore.Example/Controllers/Api/SignController.cs) and [MobileSigningService](example/src/WebEid.AspNetCore.Example/Signing/MobileSigningService.cs). A validated signing certificate returned during authentication can be stored with its supported algorithms to skip the separate certificate request. Check that the signing certificate belongs to the authenticated user before preparing the data to sign. + # Table of contents * [Quickstart](#quickstart) + * [Adding Web eID for Mobile support to an existing integration](#adding-web-eid-for-mobile-support-to-an-existing-integration) * [Introduction](#introduction) * [Authentication token format](#authentication-token-format) * [Supported token format versions](#supported-token-format-versions) diff --git a/example/README.md b/example/README.md index 6ae12e8..bfb9df0 100644 --- a/example/README.md +++ b/example/README.md @@ -159,6 +159,7 @@ By default the address is https://localhost:44391. * [Setup for Development](#setup-for-development) * [Overview of the project](#overview-of-the-project) + [Overview of the source code](#overview-of-the-source-code) + + [Adding Web eID for Mobile support to an existing integration](#adding-web-eid-for-mobile-support-to-an-existing-integration) + [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) @@ -196,6 +197,14 @@ The `src\WebEid.AspNetCore.Example` directory contains the ASP.NET application s - `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). +### Adding Web eID for Mobile support to an existing integration + +To add mobile authentication to an existing integration, follow the [library migration guide](../README.md#adding-web-eid-for-mobile-support-to-an-existing-integration). This example adds `POST /auth/mobile/init` in `Controllers/Api/MobileAuthInitController.cs` and `GET /auth/mobile/login` in `Pages/WebEidLogin.cshtml`, using `wwwroot/js/payload.js`. Both login flows submit to `POST /auth/login` in `Controllers/Api/AuthController.cs`. + +Configure `OriginUrl`, `WebEidMobile:BaseRequestUri` and `WebEidMobile:RequestSigningCert` in `appsettings.json` and `appsettings.Development.json`. Set the base request URI to `https://mopp.ria.ee` for the RIA DigiDoc app; both files currently use `web-eid-mobile://` for development. The mobile button and device detection are in `Pages/Index.cshtml` and `wwwroot/js/device-utils.js`. `Startup.cs` configures `__Host-` prefixed, `Secure`, `SameSite=Lax` session and authentication cookies and enables antiforgery validation globally. + +For optional mobile signing, see `Controllers/Api/SignController.cs`, `Signing/MobileSigningService.cs` and `Pages/WebEidCallback.cshtml`. The login handler stores a validated token's signing certificate and algorithms in the `signingCertificate` and `supportedSignatureAlgorithms` claims for reuse when signing. + ### 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. From dabebbf5606095d9fabe58e12794aa9a15846091 Mon Sep 17 00:00:00 2001 From: Mart Aarma Date: Tue, 22 Sep 2026 12:06:03 +0300 Subject: [PATCH 2/2] Fix base URL Signed-off-by: Mart Aarma Co-authored-by: Sander Kondratjev --- README.md | 2 +- example/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b520d37..028a6f2 100644 --- a/README.md +++ b/README.md @@ -461,7 +461,7 @@ When using standard [ASP.NET cookie authentication](https://docs.microsoft.com/e Reuse your existing challenge nonce generator and store, trusted CA configuration, token validation and authorization logic. The mobile flow adds an App Link/Universal Link that opens the RIA DigiDoc app and a login page that receives the response in its URL fragment and posts the token to your back end. Authentication-only responses use `web-eid:1.0`; requesting a signing certificate with `getSigningCertificate=true` requires a validator that supports `web-eid:1.1`. The validator configuration stays the same. -1. Add `POST /auth/mobile/init` to generate and store a challenge nonce and return `authUri`: `https://mopp.ria.ee/auth#`, where the payload is Base64-encoded JSON containing `challenge`, `loginUri` and optionally `getSigningCertificate` ([init controller](example/src/WebEid.AspNetCore.Example/Controllers/Api/MobileAuthInitController.cs)). Set `WebEidMobile:BaseRequestUri` to `https://mopp.ria.ee` for the RIA DigiDoc app; the example defaults to the development scheme `web-eid-mobile://`. Configure `WebEidMobile:RequestSigningCert` as needed. +1. Add `POST /auth/mobile/init` to generate and store a challenge nonce and return `authUri`: `https://id.eesti.ee/auth#`, where the payload is Base64-encoded JSON containing `challenge`, `loginUri` and optionally `getSigningCertificate` ([init controller](example/src/WebEid.AspNetCore.Example/Controllers/Api/MobileAuthInitController.cs)). Set `WebEidMobile:BaseRequestUri` to `https://id.eesti.ee` for the RIA DigiDoc app; the example defaults to the development scheme `web-eid-mobile://`. Configure `WebEidMobile:RequestSigningCert` as needed. 2. Serve `GET /auth/mobile/login` at an HTTPS `loginUri` on the validator's configured `OriginUrl`. Its script must decode the response, handle errors and post `authToken` to the existing `POST /auth/login` endpoint ([login page](example/src/WebEid.AspNetCore.Example/Pages/WebEidLogin.cshtml), [payload parser](example/src/WebEid.AspNetCore.Example/wwwroot/js/payload.js)). Retrieve and consume the session's unexpired challenge nonce, validate the token, apply your authorization checks and establish the authenticated session as before. 3. Use `Secure`, `HttpOnly`, `SameSite=Lax` for the pre-authentication session cookie so it accompanies the return from the app. Keep CSRF protection on POST endpoints ([Startup.cs](example/src/WebEid.AspNetCore.Example/Startup.cs)) and protect the login page against XSS. Callback fragments are untrusted input; the CSRF token alone does not authenticate them. See the architecture document's [security assumptions](https://github.com/web-eid/web-eid-for-mobile-architecture-doc#security-assumptions). 4. Add a mobile login button that calls the init endpoint and opens the returned `authUri` ([front end](example/src/WebEid.AspNetCore.Example/Pages/Index.cshtml)). Keep the existing desktop login control. diff --git a/example/README.md b/example/README.md index bfb9df0..aac1b2b 100644 --- a/example/README.md +++ b/example/README.md @@ -201,7 +201,7 @@ The `src\WebEid.AspNetCore.Example` directory contains the ASP.NET application s To add mobile authentication to an existing integration, follow the [library migration guide](../README.md#adding-web-eid-for-mobile-support-to-an-existing-integration). This example adds `POST /auth/mobile/init` in `Controllers/Api/MobileAuthInitController.cs` and `GET /auth/mobile/login` in `Pages/WebEidLogin.cshtml`, using `wwwroot/js/payload.js`. Both login flows submit to `POST /auth/login` in `Controllers/Api/AuthController.cs`. -Configure `OriginUrl`, `WebEidMobile:BaseRequestUri` and `WebEidMobile:RequestSigningCert` in `appsettings.json` and `appsettings.Development.json`. Set the base request URI to `https://mopp.ria.ee` for the RIA DigiDoc app; both files currently use `web-eid-mobile://` for development. The mobile button and device detection are in `Pages/Index.cshtml` and `wwwroot/js/device-utils.js`. `Startup.cs` configures `__Host-` prefixed, `Secure`, `SameSite=Lax` session and authentication cookies and enables antiforgery validation globally. +Configure `OriginUrl`, `WebEidMobile:BaseRequestUri` and `WebEidMobile:RequestSigningCert` in `appsettings.json` and `appsettings.Development.json`. Set the base request URI to `https://id.eesti.ee` for the RIA DigiDoc app; both files currently use `web-eid-mobile://` for development. The mobile button and device detection are in `Pages/Index.cshtml` and `wwwroot/js/device-utils.js`. `Startup.cs` configures `__Host-` prefixed, `Secure`, `SameSite=Lax` session and authentication cookies and enables antiforgery validation globally. For optional mobile signing, see `Controllers/Api/SignController.cs`, `Signing/MobileSigningService.cs` and `Pages/WebEidCallback.cshtml`. The login handler stores a validated token's signing certificate and algorithms in the `signingCertificate` and `supportedSignatureAlgorithms` claims for reuse when signing.