commit 2e402bb7519b61d4c5d8ea49f1978e6e5f2fae4a
parent 0254edb8832237461b5899b2af8b5b9459fbfc52
Author: Henrique Chan Carvalho Machado <henriqueccmachado@tecnico.ulisboa.pt>
Date: Tue, 4 Nov 2025 15:22:09 +0100
news: add Swiyu Generic Verifier guide
Diffstat:
1 file changed, 142 insertions(+), 0 deletions(-)
diff --git a/template/news/2025-11.html.j2 b/template/news/2025-11.html.j2
@@ -0,0 +1,142 @@
+{% extends "common/news.j2" %}
+{% block body_content %}
+<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.
+</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.
+
+<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.
+</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>
+
+<ul>
+<li>An AGOV or CH-Login account for accessing the ePortal</li>
+<li>Java Runtime Environment (JRE) 21 or higher installed</li>
+<li>Sufficient disk space (approximately 100 MB)</li>
+<li>Internet connection</li>
+<li>Operating system: Linux x64/AArch64, macOS (AArch64), or Windows (x64)</li>
+</ul>
+
+<h2 id="onboarding-process">Onboarding Process</h2>
+
+<p>The onboarding process consists of the following steps:</p>
+
+<ol>
+<li>Sign-in or sign-up to the Swiss Confederacy ePortal</li>
+<li>Register as Business Partner</li>
+<li>Get API keys from the self-service portal</li>
+<li>Allocate DID space on the Swiyu Base Registry</li>
+<li>Generate cryptographic keys and DID log using the Swiyu DID Toolbox</li>
+<li>Create and upload the DID log</li>
+<li>(Optional) Become a trusted participant</li>
+</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.
+</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.
+</p>
+
+<h3>Locate the Configuration File</h3>
+
+<p>
+The Generic Verifier uses a YAML configuration file, located in <tt>/swiyu-verifier/verifier-application/src/main/resources/application.yml</tt>.
+</p>
+
+<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:
+</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>
+</ul>
+
+<h3>Example Configuration</h3>
+
+<p>
+After replacing with your specific values, the <tt>application.yaml</tt> file will look similar to this:
+</p>
+
+<pre><code>application:
+ signing-key: |
+ -----BEGIN EC PRIVATE KEY-----
+ MHcCAQEEIABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstu
+ oAoGCCqGSM49AwEHoUQDQgAE5cice+6ILYCD2gFEVFMLPt3HPf5n/Oef
+ zOOoP+3SLDAlh/YkKQvF/1xv0uYuvy1t6wpDM7au1dMEg2L1I9wDxE==
+ -----END EC PRIVATE KEY-----
+ signing-key-verification-method: "did:tdw:
+ Qmd9bwsodZ1GAz4h8D7Vy6qRio78voXifDrnXokSTsMVQK:
+ identifier-reg.trust-infra.swiyu-int.admin.ch:api:v1:
+ did:18fa7c77-9dd1-4e20-a147-fb1bec146085#auth-key-01"
+ external-url: "https://yourdomain.com"
+ client_id: "did:tdw:
+ Qmd9bwsodZ1GAz4h8D7Vy6qRio78voXifDrnXokSTsMVQK:
+ identifier-reg.trust-infra.swiyu-int.admin.ch:api:v1:
+ did:18fa7c77-9dd1-4e20-a147-fb1bec146085"
+ client_id_scheme: "did"
+ client-metadata-file: "classpath:/client_metadata.json"
+</code></pre>
+
+<p>
+To make sure the Generic Verifier uses your configuration, specify your this <tt>.yaml</tt> run profile when booting the server:
+</p>
+
+<pre><code>./mvnw spring-boot:run -pl verifier-application -Dspring-boot.run.profiles=application
+</code></pre>
+
+<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>
+
+<h3>HTTPS Requirement</h3>
+
+<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.
+</p>
+
+<h3>Option 1: Public URL with Trusted Certificate</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:
+</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>
+</ol>
+
+<p><strong>Note:</strong> ngrok free tier URLs can change with each session.</p>
+
+<h3>Option 2: Local Network with Valid Certificate</h3>
+
+<p>
+Another somewhat more cumbersome approach, if running the verifier on the same network as the Swiyu wallet:
+</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>
+</ol>
+
+{% endblock body_content %}
