commit 244b7d3e7cad1a141d61b4539a8d7a4990eca4b0
parent a5f03845c5135e50efeee3b5909380748f0783fa
Author: Henrique Chan Carvalho Machado <henriqueccmachado@tecnico.ulisboa.pt>
Date: Fri, 17 Oct 2025 18:09:41 +0200
verifier: added onboarding documentation
Diffstat:
2 files changed, 140 insertions(+), 0 deletions(-)
diff --git a/documentation/onboarding_verifier.pdf b/documentation/onboarding_verifier.pdf
Binary files differ.
diff --git a/documentation/onboarding_verifier.tex b/documentation/onboarding_verifier.tex
@@ -0,0 +1,140 @@
+\documentclass{article}
+\usepackage{hyperref}
+\usepackage{enumitem}
+\usepackage{listings}
+\usepackage{xcolor}
+
+% Code listing settings
+\lstset{
+ basicstyle=\ttfamily\small,
+ breaklines=true,
+ frame=single,
+ backgroundcolor=\color{gray!10}
+}
+
+\title{Onboarding the Swiyu Trust Infrastructure for a Generic Verifier}
+\author{Henrique Machado}
+\date{\today}
+
+\begin{document}
+\maketitle
+
+\section{Introduction}
+
+Before being able to act as an issuer or verifier in the swiyu ecosystem, you will need to onboard onto the base registry and optionally register on the trust registry.
+
+Section \ref{Section 3} outlines all the steps necessary to onboard the swiyu trust infrastructure.
+
+\textbf{Important:} Please note that the current system is in Public Beta and is provided on a best-effort basis. The system will continue to evolve over time.
+
+\section{Prerequisites}
+
+Before starting the onboarding process, ensure you have:
+
+\begin{itemize}
+ \item An AGOV or CH-Login account for accessing the ePortal.
+ \item Java Runtime Environment (JRE) 21 or higher installed.
+ \item Sufficient disk space (approximately 100 MB).
+ \item Internet connection.
+ \item Operating system: Linux x64/AArch64, macOS (AArch64), or Windows (x64).
+\end{itemize}
+
+\section{Onboarding Process Overview}\label{Section 3}
+
+The onboarding process consists of the following steps:
+
+\begin{enumerate}
+ \item Sign-in or sign-up to the Swiss Confederacy ePortal.
+ \item Register as Business Partner.
+ \item Get API keys from the self-service portal.
+ \item Allocate DID space on the Swiyu Base Registry.
+ \item Generate cryptographic keys and DID log using the swiyu DID Toolbox.
+ \item Create and upload the DID log.
+ \item (Optional) Become a trusted participant.
+\end{enumerate}
+
+The official swiyu technical documentation offers detailed guides ---\href{https://swiyu-admin-ch.github.io/cookbooks/}{cookbooks}--- that guide you through this process in a detailed manner. Follow \href{https://swiyu-admin-ch.github.io/cookbooks/onboarding-base-and-trust-registry/}{this cookbook} to complete the necessary steps for a successful onboarding process.
+
+\section{Configuring the Swiyu Generic Verifier}
+
+With the onboarding process complete, it is necessary to configure the Swiyu Generic Verifier with the generated keys and DID.
+
+\subsection{Locate the Configuration File}
+
+The Generic Verifier uses a YAML configuration file, located in
+
+\texttt{/swiyu-verifier/verifier-application/src/main/resources/application.yml}.
+
+\subsection{Understanding the Required Configuration Parameters}
+
+All required parameters can be found in the DID log generated by the DID toolbox.
+
+\begin{itemize}
+ \item \textbf{client\_id:} The DID found in the value of the \texttt{value.id} field.
+
+ \item \textbf{signing-key-verification-method:} Your DID with the authentication key reference appended. Its value is found in the \texttt{value.assertionMethod} entry in the DID log. The format is: \texttt{<your-did>\#auth-key-01}
+
+ \item \textbf{signing-key:} The private EC authentication key from the file \texttt{.didtoolbox/auth-key-01}. Copy the entire content including the BEGIN and END markers.
+\end{itemize}
+
+\subsection{Example Configuration}
+
+After replacing with your specific values, the \texttt{application.yaml} file will look similar to this:
+
+\begin{lstlisting}[language=yaml]
+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"
+\end{lstlisting}
+
+To make sure the Generic Verifier uses your configuration, do not forget to specify this .yaml run profile when booting the server:
+
+\begin{lstlisting}[language=bash]
+./mvnw spring-boot:run -pl verifier-application -Dspring-boot.run.profiles=application
+\end{lstlisting}
+
+Where 'application' is the name of the configuration .yaml file.
+
+\section{HTTPS Configuration for Swiyu Wallet}
+
+\subsection{HTTPS Requirement}
+
+The Swiyu wallet \textbf{only accepts HTTPS connections}. To verify BetaID credentials, you must use a valid TLS/SSL certificate and ensure your verifier is accessible via HTTPS.
+
+\subsection{Option 1: Public URL with Trusted Certificate}
+
+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:
+
+\begin{enumerate}
+ \item Install ngrok: \url{https://ngrok.com/download}
+ \item Start your Generic Verifier locally (e.g., on port 8080)
+ \item Create an ngrok tunnel:
+ \begin{lstlisting}[language=bash]
+ngrok http 8080
+ \end{lstlisting}
+ \item ngrok will provide a public HTTPS URL with a trusted certificate (e.g., \texttt{https://abc123.ngrok-free.app})
+ \item Use this URL in the .yaml configuration file under the 'external-url' field.
+\end{enumerate}
+
+\textbf{Note:} ngrok free tier URLs can change with each session.
+
+\subsection{Option 2: Local Network with Valid Certificate}
+
+A more cumbersome approach, if running the verifier on the same network as the Swiyu wallet:
+
+\begin{enumerate}
+ \item Obtain a valid TLS/SSL certificate (e.g. from a trusted Certificate Authority).
+ \item Configure the Generic Verifier application to use the certificate.
+\end{enumerate}
+
+\end{document}
+
