kych

OAuth 2.0 API for Swiyu to enable Taler integration of Swiyu for KYC (experimental)
Log | Files | Refs | Submodules | README | LICENSE

README (4383B)

      1 SWIYU Verifier
      2 ==============
      3 
      4 The SWIYU Generic Verifier is the service that performs the actual OpenID4VP
      5 credential verification: it publishes the endpoints the SWIYU wallet talks to,
      6 checks the presented SD-JWT credential against the issuer's key in the Swiss
      7 Base Registry and its revocation status in the Status Registry, and reports
      8 the result back to KyCH.
      9 
     10 It is a separate upstream, maintained by the Swiss Confederation:
     11 
     12     https://github.com/swiyu-admin-ch/swiyu-verifier
     13 
     14 This directory holds our checkout of it and the pieces around it.
     15 
     16 
     17 Contents
     18 --------
     19 
     20   upstream/                   git submodule, pinned to a release tag
     21   run.sh                      run it from upstream/ for development
     22   application-kych.yml.template  development configuration to copy and fill in
     23   client_metadata.json        name and logo the wallet shows the user
     24   install_db.sh               create the development database
     25   uninstall_db.sh             drop it again
     26   api_requests/               example management API calls
     27 
     28 For a deployment, use the swiyu-verifier Debian package instead of anything in
     29 here; see ../debian/swiyu-verifier.README.Debian.  The packaging builds the
     30 jar from the same upstream/ submodule.
     31 
     32 
     33 Getting the source
     34 ------------------
     35 
     36 The submodule is not part of a plain clone:
     37 
     38     git submodule update --init
     39 
     40 It is pinned to a tag rather than tracking a branch.  To move it, see
     41 "Updating the verifier" in ../debian/README.source -- upstream's releases have
     42 broken the interface with KyCH more than once.
     43 
     44 
     45 Prerequisites
     46 -------------
     47 
     48   - JDK 25.  The verifier moved to Java 25 with its 5.0.0 release; an older
     49     JDK fails the build with a release-version error.  On Debian trixie:
     50         apt install openjdk-25-jdk-headless maven
     51   - PostgreSQL
     52   - For a wallet to take part: a DID and signing key from SWIYU onboarding,
     53     and a public HTTPS URL (ngrok will do for development).
     54 
     55 
     56 Development setup
     57 -----------------
     58 
     59 1. Database.  The verifier creates and migrates its own schema with Flyway on
     60    every start, so only a role and an empty database are needed:
     61 
     62        ./install_db.sh
     63 
     64    It needs a password, because the PostgreSQL JDBC driver cannot use peer
     65    authentication over a Unix socket.
     66 
     67 2. Configuration:
     68 
     69        cp application-kych.yml.template application-kych.yml
     70 
     71    and fill in external-url, client_id (your DID),
     72    signing-key-verification-method and signing_key.  run.sh passes this file
     73    to Spring Boot as an additional configuration location, so the upstream
     74    checkout stays untouched.
     75 
     76 3. Run:
     77 
     78        ./run.sh              # run
     79        ./run.sh clean        # rebuild first
     80        ./run.sh -d           # with a debugger on port 5005
     81 
     82    The service then answers on http://localhost:8080, with the API
     83    documentation at /swagger-ui.html and health at /actuator/health.
     84 
     85 4. For wallet testing, expose it over HTTPS -- the wallet accepts nothing else:
     86 
     87        ngrok http 8080
     88 
     89    and put that URL in external-url.
     90 
     91 
     92 Talking to KyCH
     93 ---------------
     94 
     95 In the gateway's configuration, the client section points at this service:
     96 
     97     VERIFIER_URL = http://localhost:8080
     98     VERIFIER_MANAGEMENT_API_PATH = /management/api/verifications
     99 
    100 and the verifier's webhook.callback-uri points back at KyCH's /notification.
    101 
    102 KyCH needs a verifier of release 3.0.0 or newer: it sends a DCQL query, and
    103 that release dropped the DIF Presentation Exchange format older ones used.
    104 
    105 
    106 API request examples
    107 --------------------
    108 
    109   post_management_api_verifications.sh <file.json>
    110       Create a verification from a JSON body and render the resulting
    111       verification_url as a QR code (needs jq and qrencode).
    112 
    113   get_management_api_verifications.sh <verificationId>
    114       Fetch a verification and its result.
    115 
    116   request_over_18.json
    117       A DCQL query for age_over_18, in the shape KyCH itself sends -- same
    118       credential query id, same dc+sd-jwt format.  Note that the
    119       accepted_issuer_dids in it is a sandbox issuer and will have to be
    120       replaced.
    121 
    122 
    123 Two upstream interfaces to know about
    124 -------------------------------------
    125 
    126   /management/api/      internal: creates verifications and returns results.
    127                         Must not be reachable from outside the organisation.
    128   /oid4vp/api/          public: what the wallet fetches and posts to.  Needs
    129                         HTTPS with a publicly trusted certificate.