2025-10: Onboarding the Swiyu Trust Infrastructure as a Verifier

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.

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.

About Swiyu

Swiyu 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 Generic Verifier component enables registered third-party entities to request and verify identity attributes from Swiyu eID credentials.

Important: Swiyu is in Public Beta and is provided on a best-effort basis. The system will continue to evolve over time.

System Architecture and Components

The Swiyu ecosystem consists of several key components that work together to enable secure digital identity verification:

Core Components

Swiyu Base Registry: 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.
Swiyu Wallet: Mobile application held by end users that stores their verifiable credentials (eID). The Swiyu wallet communicates with verifiers to present identity attributes upon request.
Issuers: Trusted entities (such as government agencies) that issue verifiable credentials to users' Swiyu wallets after identity verification.
Verifiers: Services operated by organizations that request and verify identity attributes from user Swiyu wallets.
DID Toolbox: A command-line tool for generating cryptographic keys and DID documents required for onboarding to the Base Registry.

How Components Interact

The verification flow works as follows:

A Verifier Service creates a verification request specifying which identity attributes are needed (e.g., date of birth, name)
The request is presented to the user's Swiyu wallet (typically via QR code)
The Swiyu wallet displays which attributes are being requested and asks for user consent
Upon consent, the Swiyu wallet presents the requested attributes from the user's credentials to the Verifier Service
The Verifier Service validates the credentials by checking signatures against the Base Registry and verifying the issuer is trusted
The verified attributes are made available to the requesting business system (e.g., a Taler exchange's KYC module)

All participants (issuers and verifiers) must register their DIDs in the Base Registry to participate in the trust infrastructure. The registry ensures that all cryptographic keys can be discovered and verified by other participants.

Prerequisites

Before deploying a generic verifier in the beta, you must first onboard to the Swiyu Base Registry. Ensure you have:

An AGOV or CH-Login account for accessing the ePortal
Java Runtime Environment (JRE) 21 or higher installed
Sufficient disk space (approximately 100 MB)
Internet connection
Operating system: Linux x64/AArch64, macOS (AArch64), or Windows (x64)

Onboarding Process

The onboarding process consists of the following steps:

Sign-in or sign-up to the Swiss Confederacy ePortal
Register as Business Partner
Get API keys from the self-service portal
Allocate DID space on the Swiyu Base Registry
Generate cryptographic keys and DID log using the Swiyu DID Toolbox
Create and upload the DID log
(Optional) Become a trusted participant

The official Swiyu technical documentation offers detailed guides—cookbooks—that guide you through this process in a detailed manner. Follow this cookbook to complete the necessary steps to onboard the Swiyu Base Registry before continuing.

Configuring the Swiyu Generic Verifier

With the Base Registry onboarding process complete, it is necessary to configure the Swiyu Generic Verifier with the generated keys and DID obtained in the Base Registry Onboarding cookbook.

Locate the Configuration File

The Generic Verifier uses a YAML configuration file, located in /swiyu-verifier/verifier-application/src/main/resources/application.yml.

Understanding the Required Configuration Parameters

The configuration parameters are obtained from files generated during the Base Registry onboarding process. When you run the DID Toolbox during onboarding, it creates a .didtoolbox directory containing the necessary files:

DID Log location: The DID log is generated by the DID Toolbox and saved as a JSONL (JSON Lines) file in the .didtoolbox directory. This file contains your DID and public key references in the format specified by the DID creation cookbook.
Private keys location: Private keys are stored in separate PEM files within the .didtoolbox directory with names corresponding to their purpose (e.g., auth-key-01, agree-key-01, etc.).

Extract the following parameters from these files for your Generic Verifier configuration:

client_id: Your DID identifier found in the value.id field of the DID log JSONL file. This is a unique identifier in the format did:tdw:<hash>:<registry-domain>:api:v1:did:<uuid>
signing-key-verification-method: Your DID with the authentication key fragment appended. Found in the value.assertionMethod array in the DID log. The format is: <your-did>#auth-key-01. This specifies which key in your DID document is used for signing authorization requests.
signing-key: The private EC256 (Elliptic Curve P-256) authentication key from the file .didtoolbox/auth-key-01. This is a PEM-encoded private key used to sign requests sent to the Swiyu wallet. Copy the entire content including the -----BEGIN EC PRIVATE KEY----- and -----END EC PRIVATE KEY----- markers.

Example Configuration

Create your configuration profile by copying the template from the local deployment YAML in the repository (application-local.yml). After replacing with your specific values, the application.yaml configuration will look similar to this:

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"

To make sure the Generic Verifier uses your configuration, specify your .yaml run profile when booting the server:

./mvnw spring-boot:run -pl verifier-application -Dspring-boot.run.profiles=application

Where 'application' is the name of your configuration .yaml file.

HTTPS/TLS Configuration

Important: 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.

Testing Your Verifier Setup

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.

1. Get the Swiyu Wallet

Download the Swiyu BetaID wallet application for your mobile device (iOS or Android). Links can be found under 'Information for private individuals' here.

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:

Follow the link displayed after the initial setup to the Beta-ID website
Request a Beta-ID
Choose a Beta-ID from a template (Helvetia or Marco), optionally upload a ID picture
Click the 'Request the issuing of a Beta-ID' button and then the 'Add to wallet' button
Once back in the Swiyu wallet app, click on 'Add' to add the Beta-ID to your wallet

Congratulations! Your unique Beta-ID is now on your wallet (and nowhere else!).

2. Create a Verification Request

With your verifier service running, create a test verification request using the management API. The following example verification request can be performed using curl to verify if a user is over 18 years old:

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": {}
  }'

This request asks the Swiyu wallet to provide proof that the user is over 18 years old from their BetaID credential.

3. Generate and Scan QR Code

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:

https://your-verifier-domain.com/oid4vp/api/request-object/<verificationId>

For example, if your verification ID is abc123def456, the URL would be:

https://your-verifier-domain.com/oid4vp/api/request-object/abc123def456

Convert this URL to a QR code using for example qrencode (a CLI QR code generation tool available in most package managers):

Install qrencode if not already available:

# macOS, requires homebrew
brew install qrencode

# Ubuntu/Debian
sudo apt-get install qrencode

Generate a QR code PNG from your the terminal:

qrencode -o verification-qr.png "https://your-verifier-domain.com/oid4vp/api/request-object/abc123def456"

Open your Swiyu wallet app and scan the generated QR code

4. Complete the Verification

After scanning the QR code:

The Swiyu wallet will display which attributes are being requested
Review the request and tap to approve sharing the requested attributes
The Swiyu wallet sends the selected Beta-ID attributes to your verifier service

5. Check Verification Results

Query your verifier's management API to retrieve the verification results:

curl https://your-verifier-domain.com/management/api/verifications/<verificationId>

A successful verification will show a status indicating completion, along with the verified attributes that were presented by the Swiyu wallet.

Troubleshooting

Here are some common errors you might encounter during the configuration of the generic verifier and during QR code generation and scanning:

Swiyu wallet cannot connect: Ensure your verifier is accessible via HTTPS with a valid certificate
Verification fails: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 \n escape sequences or extra quotation marks ("). The signing key field should use YAML's multiline string format with the pipe (|) operator.

News