kych.conf.5.rst (5753B)
1 kych.conf(5) 2 ############ 3 4 .. only:: html 5 6 Name 7 ==== 8 9 **kych.conf** - KyCH OAuth2 Gateway configuration file 10 11 12 Description 13 =========== 14 15 The KyCH OAuth2 Gateway uses an INI-style configuration file. The configuration 16 defines server binding options, database connection, cryptographic parameters, 17 verifiable credential settings, and OAuth2 client configurations. 18 19 A configuration file may include another, by using the ``@INLINE@`` directive, 20 for example, in ``main.conf``, you could write ``@INLINE@ sub.conf`` to 21 include the entirety of ``sub.conf`` at that point in ``main.conf``. 22 23 24 GLOBAL OPTIONS 25 -------------- 26 27 The following options are from the ``[kych-oauth2-gateway]`` section. 28 29 30 Server Binding 31 ^^^^^^^^^^^^^^ 32 33 The server can listen on either a TCP socket or a Unix domain socket, but not both. 34 35 HOST 36 IP address or hostname to bind the TCP server to, e.g. ``127.0.0.1`` or ``0.0.0.0``. 37 Required when using TCP mode. Must be specified together with ``PORT``. 38 39 PORT 40 TCP port number to listen on, e.g. ``8080``. 41 Required when using TCP mode. Must be specified together with ``HOST``. 42 43 UNIXPATH 44 Path to the Unix domain socket file, e.g. ``/run/kych/kych.sock``. 45 Required when using Unix socket mode. Cannot be used together with ``HOST``/``PORT``. 46 47 UNIXPATH_MODE 48 File permissions for the Unix domain socket in octal notation. 49 Default: ``666``. 50 Only used when ``UNIXPATH`` is set. 51 52 53 Database 54 ^^^^^^^^ 55 56 DATABASE 57 PostgreSQL connection string for the database. 58 Required. Example: ``postgres://user:password@localhost/kych``. 59 60 61 Cryptographic Parameters 62 ^^^^^^^^^^^^^^^^^^^^^^^^ 63 64 NONCE_BYTES 65 Number of random bytes to generate for nonces. 66 Required. Recommended value: ``32``. 67 68 TOKEN_BYTES 69 Number of random bytes to generate for access tokens. 70 Required. Recommended value: ``32``. 71 72 AUTH_CODE_BYTES 73 Number of random bytes to generate for authorization codes. 74 Required. Recommended value: ``32``. 75 76 AUTH_CODE_TTL_MINUTES 77 Validity period for authorization codes in minutes. 78 Default: ``10``. 79 80 81 Verifiable Credential Configuration 82 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 83 84 These options define the verifiable credential type that KyCH will request 85 from the Swiyu Verifier. 86 87 VC_TYPE 88 The type identifier of the verifiable credential. 89 Required. Example: ``betaid-sdjwt``. 90 91 VC_FORMAT 92 The format of the verifiable credential. 93 Required. Example: ``vc+sd-jwt``. 94 95 VC_ALGORITHMS 96 List of acceptable cryptographic algorithms for credential verification. 97 Required. Format is a bracketed comma-separated list. 98 Example: ``{ES256}`` or ``{ES256, ES384}``. 99 100 VC_CLAIMS 101 The complete set of claim names that exist in the verifiable credential type. 102 This defines which claims are valid and can be requested by clients via the 103 ``scope`` parameter. The gateway validates that all requested claims are in 104 this set. Required. Format is a bracketed comma-separated list. 105 Example: ``{family_name, given_name, birth_date, age_over_18}``. 106 107 108 Scope Restrictions 109 ^^^^^^^^^^^^^^^^^^ 110 111 ALLOWED_SCOPES 112 Optional policy restriction on which claims clients may request. If set, 113 only the listed claims can be requested, even if more claims are defined 114 in ``VC_CLAIMS``. If not set, clients may request any claim from ``VC_CLAIMS``. 115 Use this to limit what data clients can access without changing the credential 116 configuration. Format is a bracketed comma-separated list. 117 Example: ``{family_name, age_over_18}``. 118 119 120 CLIENT SECTIONS 121 --------------- 122 123 Each OAuth2 client is configured in a separate section with a name starting with 124 ``client_``, for example ``[client_merchant]`` or ``[client_exchange]``. 125 126 CLIENT_ID 127 Unique identifier for this OAuth2 client. 128 Required. 129 130 CLIENT_SECRET 131 Secret key for client authentication. 132 Required. 133 134 VERIFIER_URL 135 Base URL of the Swiyu Verifier service that this client will use. 136 Required. Example: ``https://verifier.swiyu.admin.ch``. 137 138 VERIFIER_MANAGEMENT_API_PATH 139 Path to the verifier's management API endpoint. 140 Default: ``/management/api/verifications``. 141 142 REDIRECT_URI 143 OAuth2 callback URL where the authorization response will be sent. 144 Required. Must match the redirect URI registered with the client application. 145 Example: ``https://merchant.example.com/kyc/callback``. 146 147 ACCEPTED_ISSUER_DIDS 148 Optional list of trusted issuer DIDs for verifiable credentials. 149 Format is a bracketed comma-separated list. 150 If not specified, credentials from any issuer are accepted. 151 Example: ``{did:tdw:issuer1, did:tdw:issuer2}``. 152 153 154 EXAMPLE CONFIGURATION 155 ===================== 156 157 :: 158 159 [kych-oauth2-gateway] 160 # TCP binding (use either TCP or Unix socket, not both) 161 #HOST = 127.0.0.1 162 #PORT = 8080 163 164 # Unix socket binding 165 UNIXPATH = /run/kych/kych.sock 166 UNIXPATH_MODE = 666 167 168 # Database connection 169 DATABASE = postgres://kych:secret@localhost/kych 170 171 # Cryptographic parameters 172 NONCE_BYTES = 32 173 TOKEN_BYTES = 32 174 AUTH_CODE_BYTES = 32 175 AUTH_CODE_TTL_MINUTES = 10 176 177 # Optional scope restriction 178 #ALLOWED_SCOPES = {family_name, given_name, birth_date} 179 180 # Verifiable Credential configuration 181 VC_TYPE = betaid-sdjwt 182 VC_FORMAT = vc+sd-jwt 183 VC_ALGORITHMS = {ES256} 184 VC_CLAIMS = {family_name, given_name, birth_date, nationality} 185 186 # Client configuration 187 [client_merchant] 188 CLIENT_ID = merchant_prod_01 189 CLIENT_SECRET = supersecretkey 190 VERIFIER_URL = https://verifier.swiyu.admin.ch 191 VERIFIER_MANAGEMENT_API_PATH = /management/api/verifications 192 REDIRECT_URI = https://merchant.example.com/kyc/callback 193 ACCEPTED_ISSUER_DIDS = {did:tdw:trusted_issuer} 194 195 196 SEE ALSO 197 ======== 198 199 kych-oauth2-gateway(1), kych-client-management(1). 200 201 202 BUGS 203 ==== 204 205 Report bugs by using https://bugs.taler.net/ or by sending electronic 206 mail to <taler@gnu.org>.