kych

taler-kych-manual.rst (24001B)

---

 ..
   This file is part of GNU TALER.
 
   Copyright (C) 2024, 2025 Taler Systems SA
 
   TALER is free software; you can redistribute it and/or modify it under the
   terms of the GNU Affero General Public License as published by the Free Software
   Foundation; either version 2.1, or (at your option) any later version.
 
   TALER is distributed in the hope that it will be useful, but WITHOUT ANY
   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
   A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
 
   You should have received a copy of the GNU Affero General Public License along with
   TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
 
 
 KyCH Operator Manual
 ####################
 
 Introduction
 ============
 
 About KyCH
 ----------
 
 KyCH is an OAuth 2.0-compatible gateway for KYC (Know Your Customer) verification
 using OID4VP (OpenID for Verifiable Presentations) with Swiyu Verifier.
 By redirecting a user-agent to a KyCH service, a client (such as a Taler exchange)
 can have KyCH verify the user's identity through verifiable credentials stored
 in the user's Swiyu Wallet and obtain the verified identity attributes via
 the ``/info`` endpoint.
 
 
 About this manual
 -----------------
 
 This manual targets system administrators who want to install,
 operate or integrate a KyCH service.  To report issues
 or learn about known limitations, please check our
 `bug tracker <https://bugs.taler.net>`__.
 
 
 Architecture overview
 ---------------------
 
 The following diagram shows the high-level architecture of KyCH and its
 interactions with other components:
 
 .. image:: images/kych_overview.jpg
    :alt: KyCH Architecture Overview
    :align: center
 
 KyCH acts as an OAuth 2.0 gateway that orchestrates KYC verification between:
 
 - **Taler Exchange**: The client that requires KYC verification for users.
 - **KyCH OAuth2 Gateway**: Manages OAuth 2.0 flows and verification sessions.
 - **Swiyu Verifier**: Handles OID4VP verification requests.
 - **Swiyu Wallet**: The user's mobile wallet containing verifiable credentials.
 
 The flow proceeds as follows:
 
 1. The *resource owner* (user) initiates a KYC-requiring operation with the
    *client* (e.g., Taler exchange).
 
 2. The *client* calls ``POST /setup/{client_id}`` with its client secret to
    obtain a ``nonce`` for the verification session.
 
 3. The *client* redirects the user-agent to ``GET /authorize/{nonce}`` with
    OAuth 2.0 parameters (``response_type``, ``client_id``, ``redirect_uri``,
    ``state``, ``scope``).
 
 4. KyCH creates a verification request with the Swiyu Verifier and returns
    an HTML page with a QR code (or JSON with ``verification_url``).
 
 5. The user scans the QR code with their Swiyu Wallet, which retrieves the
    presentation definition and requests user consent.
 
 6. Upon user consent, the Swiyu Wallet presents the requested credentials to
    the Swiyu Verifier.
 
 7. The Swiyu Verifier sends a webhook notification to KyCH's ``/notification``
    endpoint with the verification result.
 
 8. The client polls ``GET /status/{verification_id}`` until the status becomes
    ``verified``, then redirects to ``GET /finalize/{verification_id}``.
 
 9. KyCH redirects the user to the client's ``redirect_uri`` with an
    authorization code.
 
 10. The client exchanges the authorization code for an access token via
     ``POST /token``.
 
 11. The client retrieves the verified identity claims via ``GET /info`` using
     the access token.
 
 
 .. _KyCHInstallation:
 
 Installation
 ============
 
 Prerequisites
 -------------
 
 Before installing KyCH, ensure you have the following:
 
 * Rust toolchain (stable, version 1.70 or later)
 * PostgreSQL 12 or later
 * A Swiyu Verifier instance with API access
 
 
 Building from source
 --------------------
 
 Clone the KyCH repository and build the release binaries:
 
 .. code-block:: shell-session
 
    $ git clone https://github.com/example/kych.git
    $ cd kych/kych_oauth2_gateway
    $ cargo build --release
 
 The compiled binaries will be available in ``target/release/``:
 
 * ``kych-oauth2-gateway`` - the main HTTP server
 * ``kych-client-management`` - CLI tool for managing clients
 
 
 Database setup
 --------------
 
 KyCH uses PostgreSQL to store client configurations, verification sessions,
 authorization codes, and access tokens.
 
 First, switch to the ``postgres`` user and create a database user and database
 for KyCH:
 
 .. code-block:: shell-session
 
    [root@server]# su - postgres
    [postgres@server]# createuser kych
    [postgres@server]# createdb -O kych kych
    [postgres@server]# exit
 
 The ``createuser`` command creates a PostgreSQL role named ``kych``.
 The ``createdb`` command creates a database named ``kych`` owned by the
 ``kych`` role (``-O kych``).
 
 Next, initialize the database schema. KyCH uses a versioning system to manage
 database migrations. First, install the versioning support, then apply the
 schema migration:
 
 .. code-block:: shell-session
 
    $ psql -U kych -d kych -f oauth2_gatewaydb/versioning.sql
    $ psql -U kych -d kych -f oauth2_gatewaydb/oauth2gw-0001.sql
 
 The ``versioning.sql`` script installs the ``_v`` schema which tracks applied
 database patches. The ``oauth2gw-0001.sql`` script creates the ``oauth2gw``
 schema with the following tables:
 
 - ``clients``: Registered OAuth 2.0 clients and their configurations.
 - ``verification_sessions``: Active and completed verification sessions.
 - ``authorization_codes``: OAuth 2.0 authorization codes issued after verification.
 - ``access_tokens``: Bearer tokens issued to clients for accessing user data.
 
 .. note::
 
    The SQL migration files are located in the ``oauth2_gatewaydb/`` directory
    of the KyCH source tree. Adjust the path if you installed KyCH to a
    different location.
 
 
 Configuration
 =============
 
 Configuration file location
 ---------------------------
 
 KyCH reads its configuration from a file in the GNU Taler configuration
 format, the same one the rest of the Taler stack uses: INI-like, with
 ``@inline@`` includes and ``$VAR`` expansion in paths. The default location is
 ``/etc/kych/kych.conf``. You can specify an alternative path using the
 ``--config`` or ``-c`` command-line option. See kych.conf(5) for the format
 and for the full list of options.
 
 
 Main configuration section
 --------------------------
 
 The main configuration is specified in the ``[kych-oauth2-gateway]`` section:
 
 .. code-block:: ini
    :caption: /etc/kych/kych.conf
 
    [kych-oauth2-gateway]
    # Server binding: unix, tcp or systemd
    SERVE = unix
 
    # For SERVE = unix:
    UNIXPATH = /run/kych/kych.sock
    UNIXPATH_MODE = 660
 
    # For SERVE = tcp:
    #BIND_TO = 127.0.0.1
    #PORT = 8080
 
    # Database connection string
    DATABASE = postgres://kych:password@localhost/kych
 
    # Cryptographic parameters
    NONCE_BYTES = 32
    TOKEN_BYTES = 32
    AUTH_CODE_BYTES = 32
    AUTH_CODE_TTL_MINUTES = 10
 
    # Optional: restrict allowed OAuth scopes
    #ALLOWED_SCOPES = {family_name, given_name, birth_date}
 
 
 Server binding options
 ----------------------
 
 ``SERVE`` selects one of three ways to obtain the listening socket. For
 production deployments behind a reverse proxy (recommended), a Unix socket
 avoids network exposure altogether.
 
 **Unix socket binding (SERVE = unix):**
 
 Use this for production deployments behind nginx or another reverse proxy.
 
 -  ``UNIXPATH``: Path to the Unix domain socket file (e.g., ``/run/kych/kych.sock``).
    Ensure the directory exists and is writable by the KyCH process.
 -  ``UNIXPATH_MODE``: Octal permission mode for the socket file. Use ``660``
    so that only the reverse proxy user, which shares KyCH's group, can reach it.
 
 **TCP binding (SERVE = tcp):**
 
 Use TCP binding for development or when KyCH must be accessible over the network.
 
 -  ``BIND_TO``: The IP address to bind to. Use ``127.0.0.1`` for localhost-only
    access or ``0.0.0.0`` to accept connections on all interfaces.
 -  ``PORT``: The TCP port to listen on (e.g., ``8080``).
 
 **Socket activation (SERVE = systemd):**
 
 KyCH takes the listening socket from the service manager rather than binding
 one, so systemd owns the socket, its permissions and its lifetime, and the
 service can start on the first connection. Nothing else needs to be
 configured; the Debian package ships a ``kych.socket`` unit for it.
 
 
 Database configuration
 ----------------------
 
 KyCH requires a PostgreSQL database to persist client registrations, verification
 sessions, authorization codes, and access tokens. The connection is specified
 using a standard PostgreSQL connection URI.
 
 -  ``DATABASE``: PostgreSQL connection string in the format
    ``postgres://user:password@host:port/database``. For local connections,
    you can omit the port (defaults to 5432). Example:
    ``postgres://kych:secretpassword@localhost/kych``
 
 For production deployments, consider using environment variables or a secrets
 manager to avoid storing database credentials in plain text configuration files.
 
 
 Cryptographic parameters
 ------------------------
 
 KyCH generates cryptographically secure random values for nonces, access tokens,
 and authorization codes. These parameters control the size (entropy) and
 lifetime of these values. Larger sizes provide more security but result in
 longer token strings.
 
 -  ``NONCE_BYTES``: Number of random bytes for session nonces. The nonce is
    used in the ``/authorize/{nonce}`` URL to identify the verification session.
    Recommended: ``32`` (256 bits of entropy, base64-encoded to ~43 characters).
 
 -  ``TOKEN_BYTES``: Number of random bytes for OAuth 2.0 access tokens. These
    tokens are used by clients to access the ``/info`` endpoint.
    Recommended: ``32`` (256 bits of entropy).
 
 -  ``AUTH_CODE_BYTES``: Number of random bytes for OAuth 2.0 authorization codes.
    These short-lived codes are exchanged for access tokens at the ``/token``
    endpoint. Recommended: ``32`` (256 bits of entropy).
 
 -  ``AUTH_CODE_TTL_MINUTES``: How long authorization codes remain valid before
    expiring. Clients must exchange the code for an access token within this
    time window. Default: ``10`` minutes. Shorter values are more secure but
    may cause issues with slow clients.
 
 
 Verifiable Credential settings
 ------------------------------
 
 These settings define the type of verifiable credential that KyCH will request
 from the Swiyu Verifier during the OID4VP flow. The configuration must match
 the credential type supported by your Swiyu Verifier deployment and the
 credentials available in users' Swiyu Wallets.
 
 .. code-block:: ini
    :caption: /etc/kych/kych.conf
 
    [kych-oauth2-gateway]
    VC_TYPE = betaid-sdjwt
    VC_FORMAT = vc+sd-jwt
    VC_ALGORITHMS = {ES256}
    VC_CLAIMS = {family_name, given_name, birth_date, age_over_18}
 
 -  ``VC_TYPE``: The verifiable credential type identifier. This must match
    the credential type configured in the Swiyu Verifier. For Swiss Beta ID
    credentials, use ``betaid-sdjwt``.
 
 -  ``VC_FORMAT``: The credential format. SD-JWT (Selective Disclosure JWT)
    credentials use ``vc+sd-jwt``, which allows users to disclose only the
    specific claims requested.
 
 -  ``VC_ALGORITHMS``: Cryptographic signature algorithms accepted for credential
    verification, as a bracketed list. The Swiyu ecosystem uses ``{ES256}``
    (ECDSA with P-256 and SHA-256).
 
 -  ``VC_CLAIMS``: The complete set of claims that may be requested from the
    credential. Clients specify which of these claims they need via the
    ``scope`` parameter in the authorization request. Only claims listed here
    can be requested.
 
 **Available claims for Swiss Beta ID (betaid-sdjwt):**
 
 The Swiss Beta ID credential supports the following claims:
 
 *Personal identification:*
 
 - ``family_name``: Family name (surname)
 - ``given_name``: Given name (first name)
 - ``birth_date``: Date of birth (ISO 8601 format)
 - ``sex``: Gender
 - ``portrait``: Photograph of the credential holder
 
 *Swiss-specific attributes:*
 
 - ``place_of_origin``: Place of citizenship (Heimatort), a Swiss legal concept
 - ``birth_place``: Place of birth
 - ``nationality``: Nationality/citizenship
 - ``personal_administrative_number``: Swiss social security number (AHV/AVS number)
 
 *Age verification (selective disclosure):*
 
 - ``age_over_16``: Boolean indicating if holder is 16 or older
 - ``age_over_18``: Boolean indicating if holder is 18 or older
 - ``age_over_65``: Boolean indicating if holder is 65 or older
 - ``age_birth_year``: Year of birth (for age verification without full date)
 
 *Document information:*
 
 - ``document_number``: Identity document number
 - ``issuance_date``: When the credential was issued
 - ``expiry_date``: When the credential expires
 - ``issuing_authority``: Authority that issued the credential
 - ``issuing_country``: Country that issued the credential
 
 *Verification metadata:*
 
 - ``verification_type``: How the identity was verified (e.g., in-person)
 - ``verification_organization``: Organization that performed verification
 - ``reference_id_type``: Type of reference identity document
 - ``reference_id_expiry_date``: Expiry date of reference document
 - ``additional_person_info``: Additional personal information
 
 For most KYC use cases, requesting ``family_name``, ``given_name``,
 ``birth_date``, and ``age_over_18`` provides sufficient identity verification
 while minimizing data collection.
 
 
 Scope restrictions
 ------------------
 
 Optionally, you can restrict which claims clients are allowed to request,
 regardless of what claims are defined in ``VC_CLAIMS``. This provides an
 additional policy layer to limit data exposure.
 
 -  ``ALLOWED_SCOPES``: If set, only these claims can be requested by clients.
    If not set, clients may request any claim from ``VC_CLAIMS``. Format is
    a bracketed comma-separated list.
 
 For example, to allow clients to only verify age without accessing personal
 details:
 
 .. code-block:: ini
 
    ALLOWED_SCOPES = {age_over_18, age_over_16}
 
 
 Client Management
 =================
 
 OAuth 2.0 clients (such as Taler exchanges) must be registered with KyCH before
 they can initiate KYC verification flows. Each client has its own credentials,
 redirect URI, and may use a different Swiyu Verifier instance.
 
 There are two methods to manage clients:
 
 - **Configuration-based**: Define clients in the configuration file and use the
   ``sync`` command to load them into the database. Good for infrastructure-as-code
   deployments.
 
 - **CLI-based**: Use the ``kych-client-management`` tool to create, update, and
   delete clients directly in the database. Good for dynamic management.
 
 
 Configuration-based client management
 -------------------------------------
 
 Clients can be defined in the configuration file using ``[client_*]`` sections.
 Each section name must start with ``client_`` followed by a unique identifier
 (e.g., ``[client_exchange]``, ``[client_staging]``).
 
 .. code-block:: ini
    :caption: /etc/kych/kych.conf
 
    [client_exchange]
    CLIENT_ID = exchange_production
    CLIENT_SECRET = secret-token:your-secure-secret-here
    VERIFIER_URL = https://swiyu-verifier.example.com
    VERIFIER_MANAGEMENT_API_PATH = /management/api/verifications
    REDIRECT_URI = https://exchange.example.com/kyc/kych-redirect
    ACCEPTED_ISSUER_DIDS = {did:tdw:trusted_issuer_1, did:tdw:trusted_issuer_2}
 
 **Client configuration options:**
 
 -  ``CLIENT_ID``: Unique identifier that the client uses to authenticate with
    KyCH. This is passed in the ``client_id`` parameter during OAuth 2.0 flows
    and in the ``/setup/{client_id}`` endpoint URL.
 
 -  ``CLIENT_SECRET``: Shared secret for client authentication. The client
    provides this as a Bearer token in the ``Authorization`` header when calling
    ``/setup``, and in the request body when calling ``/token``. Use the
    ``secret-token:`` prefix per RFC 8959 for secrets that should not be logged.
    KyCH stores the secret as a bcrypt hash in the database.
 
 -  ``VERIFIER_URL``: Base URL of the Swiyu Verifier instance that this client
    will use for credential verification. Different clients can use different
    verifier instances (e.g., production vs. staging).
 
 -  ``VERIFIER_MANAGEMENT_API_PATH``: Path to the verifier's management API
    endpoint for creating verification requests. Default:
    ``/management/api/verifications``. Only change this if your Swiyu Verifier
    uses a non-standard API path.
 
 -  ``REDIRECT_URI``: The OAuth 2.0 redirect URI where users are sent after
    completing verification. This must exactly match the ``redirect_uri``
    parameter provided by the client in authorization requests. For security,
    KyCH rejects requests with mismatched redirect URIs.
 
 -  ``ACCEPTED_ISSUER_DIDS``: List of trusted credential issuer DIDs (Decentralized
    Identifiers) in bracketed format. Only credentials issued by these DIDs will
    be accepted. This provides trust anchoring - you specify which issuers you
    trust to have properly verified identities. Example:
    ``{did:tdw:issuer1, did:tdw:issuer2}``.
 
 
 CLI-based client management
 ---------------------------
 
 The ``kych-client-management`` tool manages clients directly in the database.
 All commands require the ``--config`` option to specify the configuration file
 (for database connection settings).
 
 **Listing clients:**
 
 Display all registered clients:
 
 .. code-block:: shell-session
 
    $ kych-client-management --config /etc/kych/kych.conf list
 
 This shows a summary of all clients including their IDs and verifier URLs.
 
 **Viewing client details:**
 
 Show full details for a specific client:
 
 .. code-block:: shell-session
 
    $ kych-client-management --config /etc/kych/kych.conf show exchange_prod
 
 This displays all configuration options for the client, except the secret
 (which is stored as a hash).
 
 **Creating a client:**
 
 Register a new OAuth 2.0 client:
 
 .. code-block:: shell-session
 
    $ kych-client-management --config /etc/kych/kych.conf create \
        --client-id exchange_prod \
        --secret "secret-token:your-secure-secret" \
        --verifier-url https://swiyu-verifier.example.com \
        --redirect-uri https://exchange.example.com/kyc/kych-redirect \
        --accepted-issuer-dids "{did:tdw:trusted_issuer}"
 
 The ``--client-id``, ``--secret``, ``--verifier-url``, and ``--redirect-uri``
 options are required. The ``--verifier-api-path`` defaults to
 ``/management/api/verifications`` if not specified.
 
 **Updating a client:**
 
 Modify an existing client's configuration:
 
 .. code-block:: shell-session
 
    $ kych-client-management --config /etc/kych/kych.conf update exchange_prod \
        --redirect-uri https://new-exchange.example.com/kyc/kych-redirect
 
 Only the specified options are updated; other settings remain unchanged.
 
 **Deleting a client:**
 
 Remove a client from the database:
 
 .. code-block:: shell-session
 
    $ kych-client-management --config /etc/kych/kych.conf delete exchange_prod
 
 You will be prompted for confirmation. Use ``-y`` to skip the prompt:
 
 .. code-block:: shell-session
 
    $ kych-client-management --config /etc/kych/kych.conf delete exchange_prod -y
 
 .. warning::
 
    Deleting a client will cascade to all associated sessions and tokens.
 
 **Synchronizing configuration to database:**
 
 The ``sync`` command is the bridge between configuration-based and database-based
 client management. It reads all ``[client_*]`` sections from the configuration
 file and creates or updates the corresponding clients in the database:
 
 .. code-block:: shell-session
 
    $ kych-client-management --config /etc/kych/kych.conf sync
 
 This is useful for infrastructure-as-code workflows where client configuration
 is managed in version control and deployed to the database during releases.
 
 To also remove clients from the database that are no longer defined in the
 configuration file, use the ``--prune`` flag:
 
 .. code-block:: shell-session
 
    $ kych-client-management --config /etc/kych/kych.conf sync --prune
 
 .. warning::
 
    The ``--prune`` flag will delete clients and all their associated sessions
    and tokens. Use with caution in production.
 
 
 Deployment
 ==========
 
 systemd service
 ---------------
 
 Create a systemd service file for KyCH:
 
 .. code-block:: ini
    :caption: /etc/systemd/system/kych.service
 
    [Unit]
    Description=KyCH OAuth2 Gateway
    After=network.target postgresql.service
 
    [Service]
    Type=simple
    User=kych
    Group=kych
    ExecStart=/usr/local/bin/kych-oauth2-gateway --config /etc/kych/kych.conf
    Restart=always
    RestartSec=5
 
    [Install]
    WantedBy=multi-user.target
 
 Enable and start the service:
 
 .. code-block:: shell-session
 
    [root@server]# systemctl daemon-reload
    [root@server]# systemctl enable kych
    [root@server]# systemctl start kych
 
 
 Reverse proxy setup
 -------------------
 
 KyCH should be deployed behind a reverse proxy that provides TLS termination,
 as required by OAuth 2.0. The following example shows an nginx configuration
 using a Unix socket:
 
 .. code-block:: nginx
    :caption: /etc/nginx/sites-available/kych
 
    upstream kych {
        server unix:/run/kych/kych.sock;
    }
 
    server {
        listen 443 ssl http2;
        server_name kych.example.com;
 
        ssl_certificate /etc/letsencrypt/live/kych.example.com/fullchain.pem;
        ssl_certificate_key /etc/letsencrypt/live/kych.example.com/privkey.pem;
 
        location / {
            proxy_pass http://kych;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
    }
 
 Enable the site:
 
 .. code-block:: shell-session
 
    [root@server]# ln -s /etc/nginx/sites-available/kych /etc/nginx/sites-enabled/kych
    [root@server]# nginx -t
    [root@server]# systemctl reload nginx
 
 
 Webhook configuration
 ---------------------
 
 KyCH receives callbacks from the Swiyu Verifier when a verification request
 changes state (e.g., when the user presents their credential). The webhook
 endpoint is ``/notification``.
 
 When configuring the Swiyu Verifier, set the callback URL to:
 
 ::
 
    https://kych.example.com/notification
 
 This endpoint must be accessible from the Swiyu Verifier service.
 
 .. note::
 
    The Swiyu Verifier must be configured to send notifications to the KyCH
    gateway. Consult the Swiyu Verifier documentation for details on configuring
    webhook callbacks. The verifier will POST a JSON payload containing the
    ``verification_id`` and ``timestamp`` when a verification completes.
 
 
 Integration with Taler Exchange
 ===============================
 
 To use KyCH as a KYC provider for a GNU Taler exchange, configure the
 exchange with the following settings:
 
 .. code-block:: ini
    :caption: /etc/taler-exchange/conf.d/exchange-kyc.conf
 
    [kyc-provider-kych]
    LOGIC = oauth2
    PROVIDED_CHECKS = KYCH_IDENTITY
    KYC_OAUTH2_AUTHORIZE_URL = https://kych.example.com/authorize
    KYC_OAUTH2_TOKEN_URL = https://kych.example.com/token
    KYC_OAUTH2_INFO_URL = https://kych.example.com/info
    KYC_OAUTH2_CLIENT_ID = exchange_production
    KYC_OAUTH2_CLIENT_SECRET = secret-token:your-secure-secret
    KYC_OAUTH2_POST_URL = https://kych.example.com
 
 The exchange will then use KyCH for KYC verification when the
 ``KYCH_IDENTITY`` check is required.
 
 
 OAuth 2.0 endpoints
 -------------------
 
 KyCH provides the following OAuth 2.0 endpoints:
 
 -  ``/authorize`` - Authorization endpoint (redirects user to Swiyu Wallet flow)
 -  ``/token`` - Token endpoint (exchanges authorization code for access token)
 -  ``/info`` - Info endpoint (returns verified identity claims)
 
 The flow follows standard OAuth 2.0 authorization code grant:
 
 1. Client redirects user to ``/authorize`` with ``client_id``, ``redirect_uri``,
    ``response_type=code``, and optional ``state`` parameter.
 
 2. User completes verification via Swiyu Wallet.
 
 3. User is redirected to the client's ``redirect_uri`` with an authorization
    ``code``.
 
 4. Client exchanges the ``code`` for an ``access_token`` at ``/token``.
 
 5. Client retrieves user information using the ``access_token`` at ``/info``.