kych-client-management.1.rst (6693B)
1 kych-client-management(1) 2 ######################### 3 4 .. only:: html 5 6 Name 7 ==== 8 9 **kych-client-management** - manage OAuth 2.0 clients of the KyCH gateway 10 11 12 Synopsis 13 ======== 14 15 **kych-client-management** 16 [**-c** *CONFIG*] 17 [**-L** *LEVEL*] 18 [**-v**] 19 *COMMAND* 20 [*OPTIONS*] 21 22 23 Description 24 =========== 25 26 **kych-client-management** maintains the table of OAuth 2.0 clients that 27 kych-oauth2-gateway(1) serves. It allows administrators to create, update, 28 delete, list and synchronize client registrations. 29 30 This tool exists because the running gateway resolves clients from the 31 *database* and never from the configuration file. The ``[client_*]`` sections 32 of kych.conf(5) are only a declarative source for the **sync** command below; 33 adding a section and restarting the gateway has no effect. A configuration 34 file is nevertheless needed for every invocation, because the database 35 connection string is read from it. 36 37 Client secrets are stored bcrypt-hashed and cannot be recovered, only 38 replaced. 39 40 41 Global Options 42 ============== 43 44 **-c** *CONFIG* \| **--config=**\ *CONFIG* 45 Use the configuration file *CONFIG*. Without it the standard search path 46 applies, ending at ``/etc/kych/kych.conf``; see kych.conf(5). 47 48 **-L** *LEVEL* \| **--log=**\ *LEVEL* 49 Set the logging verbosity: ``ERROR``, ``WARN``, ``INFO``, ``DEBUG`` or 50 ``TRACE``, or the numbers 1 to 5. Defaults to ``INFO``. This affects the 51 diagnostics on standard error only; the output of the commands themselves 52 goes to standard output regardless. 53 54 **-v** \| **--verbose** 55 Also log what the libraries have to say, ``sqlx`` in particular, which is 56 the way to see the statements this tool runs. 57 58 **-h** \| **--help** 59 Print short help. Also accepted after a command, as in 60 ``kych-client-management help create``, for the options of that command. 61 62 **-V** \| **--version** 63 Print version information and exit. 64 65 66 Commands 67 ======== 68 69 list 70 ---- 71 72 List all registered OAuth 2.0 clients, followed by the total count. 73 74 **kych-client-management** **-c** *CONFIG* **list** 75 76 show 77 ---- 78 79 Show details of one OAuth 2.0 client. Fails if it does not exist. 80 81 **kych-client-management** **-c** *CONFIG* **show** *CLIENT_ID* 82 83 *CLIENT_ID* 84 The identifier of the client to display. 85 86 Both **list** and **show** report the internal UUID, the client identifier, a 87 truncated prefix of the secret hash, the verifier URL and management API 88 path, the redirect URI allowlist, the accepted issuer DIDs, and the creation 89 and modification times. 90 91 create 92 ------ 93 94 Create a new OAuth 2.0 client. 95 96 **kych-client-management** **-c** *CONFIG* **create** [*OPTIONS*] 97 98 **--client-id=**\ *CLIENT_ID* 99 The unique identifier for the new client. Required. 100 101 **--secret=**\ *SECRET* 102 The client secret for authentication. Required. Stored hashed. Note that it 103 is visible in the process list and in the shell history while this command 104 runs. 105 106 **--verifier-url=**\ *URL* 107 Base URL of the SWIYU verifier used for this client's verifications. 108 Required. 109 110 **--verifier-api-path=**\ *PATH* 111 The API path on the verifier for verifications. 112 Default: ``/management/api/verifications`` 113 114 **--redirect-uri=**\ *URI* 115 The OAuth 2.0 redirect URI for this client. Required. Several may be given 116 as one comma-separated value; a redirect URI presented at authorization 117 time must match one of them exactly. 118 119 **--accepted-issuer-dids=**\ *DIDS* 120 Issuers whose credentials this client accepts, as a braced list such as 121 ``{did:tdw:a, did:tdw:b}``. A bare comma-separated list is also accepted. 122 123 .. note:: 124 125 Although this option is syntactically optional, ``/authorize`` fails 126 with ``accepted_issuer_dids_not_configured`` for a client that has no 127 issuer DIDs, so no verification can be started. It should always be 128 given. 129 130 update 131 ------ 132 133 Update an existing OAuth 2.0 client. At least one option must be provided; 134 omitted fields keep their current value. The secret cannot be changed this 135 way. 136 137 **kych-client-management** **-c** *CONFIG* **update** *CLIENT_ID* [*OPTIONS*] 138 139 *CLIENT_ID* 140 The identifier of the client to update. 141 142 **--verifier-url=**\ *URL* 143 Update the verifier service URL. 144 145 **--verifier-api-path=**\ *PATH* 146 Update the verifier API path. 147 148 **--redirect-uri=**\ *URI* 149 Update the OAuth 2.0 redirect URI allowlist. 150 151 **--accepted-issuer-dids=**\ *DIDS* 152 Update the accepted issuer DIDs. 153 154 delete 155 ------ 156 157 Delete an OAuth 2.0 client. 158 159 **kych-client-management** **-c** *CONFIG* **delete** [*OPTIONS*] *CLIENT_ID* 160 161 *CLIENT_ID* 162 The identifier of the client to delete. 163 164 **-y** \| **--yes** 165 Skip the confirmation prompt. Without it, the deletion must be confirmed by 166 typing ``yes`` on standard input. 167 168 .. warning:: 169 170 Deletion cascades in the database: all verification sessions of that 171 client, and with them the stored credentials, authorization codes and 172 access tokens, are removed. 173 174 sync 175 ---- 176 177 Read every ``[client_*]`` section of the configuration file and bring the 178 database in line with it. Sections whose client identifier is unknown are 179 created; the rest are updated. 180 181 **kych-client-management** **-c** *CONFIG* **sync** [*OPTIONS*] 182 183 **--prune** 184 Remove clients from the database that are not present in the configuration 185 file, with the same consequences as **delete** above. 186 187 .. note:: 188 189 **sync** never rotates a secret: ``CLIENT_SECRET`` is read only when a 190 client is first created, and editing it in the configuration file has no 191 effect. To change a secret, delete the client and synchronize again, or 192 recreate it with **create**. 193 194 195 Exit Status 196 =========== 197 198 Zero on success. Non-zero if the configuration cannot be read, the database 199 is unreachable, the named client does not exist, or a client identifier being 200 created already exists. 201 202 203 Examples 204 ======== 205 206 Register the clients described in the configuration file, then check the 207 result: 208 209 .. code-block:: shell 210 211 $ kych-client-management -c /etc/kych/kych.conf sync 212 $ kych-client-management -c /etc/kych/kych.conf list 213 214 Register one client directly: 215 216 .. code-block:: shell 217 218 $ kych-client-management -c /etc/kych/kych.conf create \ 219 --client-id exchange-prod-01 \ 220 --secret SECRET \ 221 --verifier-url https://verifier.example.com \ 222 --redirect-uri https://exchange.example.com/kyc-proof/kych \ 223 --accepted-issuer-dids '{did:tdw:example:issuer}' 224 225 Point an existing client at a different verifier: 226 227 .. code-block:: shell 228 229 $ kych-client-management -c /etc/kych/kych.conf update exchange-prod-01 \ 230 --verifier-url https://verifier-staging.example.com 231 232 233 See Also 234 ======== 235 236 kych-oauth2-gateway(1), kych.conf(5). 237 238 239 Bugs 240 ==== 241 242 Report bugs by using https://bugs.taler.net/ or by sending electronic 243 mail to <taler@gnu.org>.