commit a2464e3646b2335fcd66431cdb9f9ebab3dd4866
parent 2e402bb7519b61d4c5d8ea49f1978e6e5f2fae4a
Author: Henrique Chan Carvalho Machado <henriqueccmachado@tecnico.ulisboa.pt>
Date: Tue, 4 Nov 2025 19:49:14 +0100
news: Swiyu guide: remove useless sections, add testing, add Taler context
Diffstat:
1 file changed, 189 insertions(+), 27 deletions(-)
diff --git a/template/news/2025-11.html.j2 b/template/news/2025-11.html.j2
@@ -3,21 +3,61 @@
<h1>2025-10: Onboarding the Swiyu Trust Infrastructure as a Verifier</h1>
<p>
-We are pleased to announce the availability of comprehensive documentation for integrating GNU Taler with the Swiyu trust infrastructure for digital identity verification. This guide enables developers to onboard as credential verifiers in the Swiss digital identity ecosystem.
+We are pleased to announce the availability of comprehensive documentation for integrating GNU Taler with the Swiyu trust infrastructure for digital identity verification. This integration will enable GNU Taler exchanges to perform Know Your Customer (KYC) processes using Switzerland's digital identity infrastructure, particularly relevant for regulatory compliance in Swiss financial services.
+</p>
+
+<p>
+This guide enables developers to onboard as credential verifiers in the Swiss digital identity ecosystem, enabling the verification of user identity attributes from Swiyu eID credentials.
</p>
<h2 id="about-swiyu">About Swiyu</h2>
<p>
-Swiyu is Switzerland's decentralized trust infrastructure for digital identity management, currently in public beta. The public beta allows organizations to act as credential issuers or verifiers, with the Generic Verifier component enabling registered third-party entities to request and verify identity attributes from Swiyu eID credentials.
+<a href="https://swiyu-admin-ch.github.io/">Swiyu</a> is Switzerland's decentralized trust infrastructure for digital identity management. Swiyu is currently in public beta, allowing organizations to act as credential issuers or verifiers. The <a href="https://github.com/swiyu-admin-ch/swiyu-verifier">Generic Verifier</a> component enables registered third-party entities to request and verify identity attributes from Swiyu eID credentials.
+</p>
+
+<p>
+<strong>Important:</strong> Swiyu is in Public Beta and is provided on a best-effort basis. The system will continue to evolve over time.
+</p>
+
+<h2 id="architecture">System Architecture and Components</h2>
+
+<p>
+The Swiyu ecosystem consists of several key components that work together to enable secure digital identity verification:
+</p>
+
+<h3>Core Components</h3>
+
+<ul>
+<li><strong>Swiyu Base Registry:</strong> The foundational decentralized identifier (DID) registry that stores and manages DIDs for all participants in the ecosystem. This is where organizations register their identity and cryptographic keys.</li>
+<li><strong>Swiyu Wallet:</strong> Mobile application held by end users that stores their verifiable credentials (eID). The Swiyu wallet communicates with verifiers to present identity attributes upon request.</li>
+<li><strong>Issuers:</strong> Trusted entities (such as government agencies) that issue verifiable credentials to users' Swiyu wallets after identity verification.</li>
+<li><strong>Verifiers:</strong> Services operated by organizations that request and verify identity attributes from user Swiyu wallets.</li>
+<li><strong>DID Toolbox:</strong> A command-line tool for generating cryptographic keys and DID documents required for onboarding to the Base Registry.</li>
+</ul>
+
+<h3>How Components Interact</h3>
+
+<p>
+The verification flow works as follows:
+</p>
+
+<ol>
+<li>A <strong>Verifier Service</strong> creates a verification request specifying which identity attributes are needed (e.g., date of birth, name)</li>
+<li>The request is presented to the user's <strong>Swiyu wallet</strong> (typically via QR code)</li>
+<li>The <strong>Swiyu wallet</strong> displays which attributes are being requested and asks for user consent</li>
+<li>Upon consent, the <strong>Swiyu wallet</strong> presents the requested attributes from the user's credentials to the <strong>Verifier Service</strong></li>
+<li>The <strong>Verifier Service</strong> validates the credentials by checking signatures against the <strong>Base Registry</strong> and verifying the issuer is trusted</li>
+<li>The verified attributes are made available to the requesting business system (e.g., a Taler exchange's KYC module)</li>
+</ol>
<p>
-<strong>Important:</strong> The current system is in Public Beta and is provided on a best-effort basis. The system will continue to evolve over time.
+All participants (issuers and verifiers) must register their DIDs in the <strong>Base Registry</strong> to participate in the trust infrastructure. The registry ensures that all cryptographic keys can be discovered and verified by other participants.
</p>
<h2 id="prerequisites">Prerequisites</h2>
-<p>Before starting the <a href="https://github.com/swiyu-admin-ch/swiyu-verifier">generic verifier</a> onboarding process, it is necessary to onboard the Swiyu Base Registry. Ensure you have:</p>
+<p>Before deploying a <a href="https://github.com/swiyu-admin-ch/swiyu-verifier">generic verifier</a> in the beta, you must first onboard to the Swiyu Base Registry. Ensure you have:</p>
<ul>
<li>An AGOV or CH-Login account for accessing the ePortal</li>
@@ -42,13 +82,13 @@ Swiyu is Switzerland's decentralized trust infrastructure for digital identity m
</ol>
<p>
-The official Swiyu technical documentation offers detailed guides—cookbooks—that guide you through this process in a detailed manner. Follow <a href="https://swiyu-admin-ch.github.io/cookbooks/onboarding-generic-verifier/">this</a> cookbook to complete the necessary steps to onboard the Swiyu Base Registry.
+The official Swiyu technical documentation offers detailed guides—cookbooks—that guide you through this process in a detailed manner. Follow <a href="https://swiyu-admin-ch.github.io/cookbooks/onboarding-generic-verifier/">this</a> cookbook to complete the necessary steps to onboard the Swiyu Base Registry before continuing.
</p>
<h2 id="configuring-the-swiyu-generic-verifier">Configuring the Swiyu Generic Verifier</h2>
<p>
-With the Base Registry onboarding process complete, it is necessary to configure the <a href="https://github.com/swiyu-admin-ch/swiyu-verifier">Swiyu Generic Verifier</a> with the generated keys and DID.
+With the Base Registry onboarding process complete, it is necessary to configure the <a href="https://github.com/swiyu-admin-ch/swiyu-verifier">Swiyu Generic Verifier</a> with the generated keys and DID obtained in the Base Registry Onboarding <a href="https://swiyu-admin-ch.github.io/cookbooks/onboarding-base-and-trust-registry/">cookbook</a>.
</p>
<h3>Locate the Configuration File</h3>
@@ -60,19 +100,28 @@ The Generic Verifier uses a YAML configuration file, located in <tt>/swiyu-verif
<h3>Understanding the Required Configuration Parameters</h3>
<p>
-All required parameters can be found in the DID log generated by the DID toolbox in the Base Regsitry onboarding process:
+The configuration parameters are obtained from files generated during the Base Registry onboarding process. When you run the <a href="https://swiyu-admin-ch.github.io/cookbooks/onboarding-base-and-trust-registry/#quickstart--create-your-first-did">DID Toolbox</a> during onboarding, it creates a <tt>.didtoolbox</tt> directory containing the necessary files:
+</p>
+
+<ul>
+<li><strong>DID Log location:</strong> The DID log is generated by the DID Toolbox and saved as a JSONL (JSON Lines) file in the <tt>.didtoolbox</tt> directory. This file contains your DID and public key references in the format specified by the <a href="https://swiyu-admin-ch.github.io/cookbooks/onboarding-base-and-trust-registry/#quickstart--create-your-first-did">DID creation cookbook</a>.</li>
+<li><strong>Private keys location:</strong> Private keys are stored in separate PEM files within the <tt>.didtoolbox</tt> directory with names corresponding to their purpose (e.g., <tt>auth-key-01</tt>, <tt>agree-key-01</tt>, etc.).</li>
+</ul>
+
+<p>
+Extract the following parameters from these files for your Generic Verifier configuration:
</p>
<ul>
-<li><strong>client_id:</strong> The DID found in the value of the <tt>value.id</tt> field</li>
-<li><strong>signing-key-verification-method:</strong> Your DID with the authentication key reference appended. Its value is found in the <tt>value.assertionMethod</tt> entry in the DID log. The format is: <tt><your-did>#auth-key-01</tt></li>
-<li><strong>signing-key:</strong> The private EC authentication key from the file <tt>.didtoolbox/auth-key-01</tt>. Copy the entire content including the BEGIN and END markers</li>
+<li><strong>client_id:</strong> Your DID identifier found in the <tt>value.id</tt> field of the DID log JSONL file. This is a unique identifier in the format <tt>did:tdw:<hash>:<registry-domain>:api:v1:did:<uuid></tt></li>
+<li><strong>signing-key-verification-method:</strong> Your DID with the authentication key fragment appended. Found in the <tt>value.assertionMethod</tt> array in the DID log. The format is: <tt><your-did>#auth-key-01</tt>. This specifies which key in your DID document is used for signing authorization requests.</li>
+<li><strong>signing-key:</strong> The private EC256 (Elliptic Curve P-256) authentication key from the file <tt>.didtoolbox/auth-key-01</tt>. This is a PEM-encoded private key used to sign requests sent to the Swiyu wallet. Copy the entire content including the <tt>-----BEGIN EC PRIVATE KEY-----</tt> and <tt>-----END EC PRIVATE KEY-----</tt> markers.</li>
</ul>
<h3>Example Configuration</h3>
<p>
-After replacing with your specific values, the <tt>application.yaml</tt> file will look similar to this:
+Create your configuration profile by copying the template from the local deployment YAML in the repository (<tt>application-local.yml</tt>). After replacing with your specific values, the <tt>application.yaml</tt> configuration will look similar to this:
</p>
<pre><code>application:
@@ -96,7 +145,7 @@ After replacing with your specific values, the <tt>application.yaml</tt> file wi
</code></pre>
<p>
-To make sure the Generic Verifier uses your configuration, specify your this <tt>.yaml</tt> run profile when booting the server:
+To make sure the Generic Verifier uses your configuration, specify your <tt>.yaml</tt> run profile when booting the server:
</p>
<pre><code>./mvnw spring-boot:run -pl verifier-application -Dspring-boot.run.profiles=application
@@ -104,39 +153,152 @@ To make sure the Generic Verifier uses your configuration, specify your this <tt
<p>Where 'application' is the name of your configuration <tt>.yaml</tt> file.</p>
-<h2 id="https-configuration-for-swiyu-wallet">HTTPS Configuration for Swiyu Wallet</h2>
+<h2 id="https-configuration">HTTPS/TLS Configuration</h2>
-<h3>HTTPS Requirement</h3>
+<p>
+<strong>Important:</strong> The Swiyu wallet only accepts HTTPS connections. Ensure your verifier is accessible via HTTPS with a valid TLS/SSL certificate from a trusted Certificate Authority.
+</p>
+
+<h2 id="testing">Testing Your Verifier Setup</h2>
<p>
-The Swiyu wallet only accepts HTTPS connections. To verify BetaID credentials, you must use a valid TLS/SSL certificate and ensure your verifier is accessible via HTTPS.
+Once your verifier is configured and running, you should test the complete verification flow to ensure everything works correctly. This section guides you through obtaining a test wallet, getting test credentials, and performing a verification.
</p>
-<h3>Option 1: Public URL with Trusted Certificate</h3>
+<h3>1. Get the Swiyu Wallet</h3>
<p>
-For easier setup, especially during development and testing, you can use a tunneling service like ngrok to forward a public HTTPS URL to your local verifier:
+Download the Swiyu BetaID wallet application for your mobile device (iOS or Android). Links can be found under 'Information for private individuals' <a href="https://www.eid.admin.ch/en/public-beta-e">here</a>.
+</p>
+
+<p>
+Install the app and complete the initial setup by setting your password and optionally setting a biometric login with your fingerprint. Since Swiyu is in public beta, you will need to obtain a BetaID credential directly:
</p>
<ol>
-<li>Install ngrok: <a href="https://ngrok.com/download">https://ngrok.com/download</a></li>
-<li>Start your Generic Verifier locally (e.g., on port 8080)</li>
-<li>Create an ngrok tunnel: <tt>ngrok http 8080</tt></li>
-<li>ngrok will provide a public HTTPS URL with a trusted certificate (e.g., <tt>https://abc123.ngrok-free.app</tt>)</li>
-<li>Use this URL in the <tt>.yaml</tt> configuration file under the 'external-url' field</li>
+<li>Follow the link displayed after the initial setup to the Beta-ID <a href="https://www.bcs.admin.ch/bcs-web/#/">website</a></li>
+<li>Request</a> a Beta-ID</a>
+<li>Choose a Beta-ID from a template (Helvetia or Marco), optionally upload a ID picture</li>
+<li>Click the 'Request the issuing of a Beta-ID' button and then the 'Add to wallet' button</li>
+<li>Once back in the Swiyu wallet app, click on 'Add' to add the Beta-ID to your wallet</li>
</ol>
+Congratulations! Your unique Beta-ID is now on your wallet (and nowhere else!).
+
+<h3>2. Create a Verification Request</h3>
+
+<p>
+With your verifier service running, create a test verification request using the management API. The following example verification request can be performed using <tt>curl</tt> to verify if a user is over 18 years old:
+</p>
+
+<pre><code>curl -X POST https://your-verifier-domain.com/management/api/verifications \
+ -H "Content-Type: application/json" \
+ -d '{
+ "jwt_secured_authorization_request": true,
+ "response_mode": "direct_post",
+ "response_type": "vp_token",
+ "presentation_definition": {
+ "id": "00000000-0000-0000-0000-000000000000",
+ "name": "Over 18 Verification",
+ "purpose": "Verify age is over 18",
+ "input_descriptors": [
+ {
+ "id": "11111111-1111-1111-1111-111111111111",
+ "format": {
+ "vc+sd-jwt": {
+ "sd-jwt_alg_values": ["ES256"],
+ "kb-jwt_alg_values": ["ES256"]
+ }
+ },
+ "constraints": {
+ "fields": [
+ {
+ "path": ["$.vct"],
+ "filter": {
+ "type": "string",
+ "const": "betaid-sdjwt"
+ }
+ },
+ {
+ "path": ["$.age_over_18"]
+ }
+ ]
+ }
+ }
+ ]
+ },
+ "configuration_override": {}
+ }'
+</code></pre>
+
+<p>
+This request asks the Swiyu wallet to provide proof that the user is over 18 years old from their BetaID credential.
+</p>
+
+<h3>3. Generate and Scan QR Code</h3>
+
+<p>
+The verification request response will contain a verification ID. You need to convert the request URL in the response to a QR code for the Swiyu wallet to scan. The request URL format is:
+</p>
+
+<pre><code>https://your-verifier-domain.com/oid4vp/api/request-object/<verificationId></code></pre>
+
+<p>
+For example, if your verification ID is <tt>abc123def456</tt>, the URL would be:
+</p>
+
+<pre><code>https://your-verifier-domain.com/oid4vp/api/request-object/abc123def456</code></pre>
+
+<p>
+Convert this URL to a QR code using for example <a href="https://fukuchi.org/en/works/qrencode/">qrencode</a> (a CLI QR code generation tool available in most package managers):
-<p><strong>Note:</strong> ngrok free tier URLs can change with each session.</p>
+</p>
-<h3>Option 2: Local Network with Valid Certificate</h3>
+<ol>
+<li>Install qrencode if not already available:
+<pre><code># macOS, requires homebrew
+brew install qrencode
+
+# Ubuntu/Debian
+sudo apt-get install qrencode</code></pre>
+</li>
+<li>Generate a QR code PNG from your the terminal:
+<pre><code>qrencode -o verification-qr.png "https://your-verifier-domain.com/oid4vp/api/request-object/abc123def456"</code></pre>
+</li>
+<li>Open your Swiyu wallet app and scan the generated QR code</li>
+</ol>
+
+<h3>4. Complete the Verification</h3>
<p>
-Another somewhat more cumbersome approach, if running the verifier on the same network as the Swiyu wallet:
+After scanning the QR code:
</p>
<ol>
-<li>Obtain a valid TLS/SSL certificate (e.g., from a trusted Certificate Authority)</li>
-<li>Configure the Generic Verifier application to use the certificate</li>
+<li>The Swiyu wallet will display which attributes are being requested</li>
+<li>Review the request and tap to approve sharing the requested attributes</li>
+<li>The Swiyu wallet sends the selected Beta-ID attributes to your verifier service</li>
</ol>
+<h3>5. Check Verification Results</h3>
+
+<p>
+Query your verifier's management API to retrieve the verification results:
+</p>
+
+<pre><code>curl https://your-verifier-domain.com/management/api/verifications/<verificationId>
+</code></pre>
+
+<p>
+A successful verification will show a status indicating completion, along with the verified attributes that were presented by the Swiyu wallet.
+</p>
+
+<h3>Troubleshooting</h3>
+
+<p>Here are some common errors you might encounter during the configuration of the generic verifier and during QR code generation and scanning:</p>
+
+<ul>
+<li><strong>Swiyu wallet cannot connect:</strong> Ensure your verifier is accessible via HTTPS with a valid certificate</li>
+<li><strong>Verification fails:</strong>The format of the signing key in the .yaml configuration of your Verifier must be exactly as specified in the example configuration file and cannot contain literal <tt>\n</tt> escape sequences or extra quotation marks (<tt>"</tt>). The signing key field should use YAML's multiline string format with the pipe (<tt>|</tt>) operator.</li>
+</ul>
+
{% endblock body_content %}
