kych

onboarding_verifier.tex (5934B)

---

 \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}