README.Debian (3579B)
1 kych for Debian 2 =============== 3 4 The service is installed disabled and will not start until you have done the 5 three steps below: it has no usable defaults for the database or for the OAuth 6 2.0 clients it serves. 7 8 1. Create the database 9 ---------------------- 10 11 The daemon runs as the system user "kych" and the shipped configuration 12 connects over the local PostgreSQL socket using peer authentication, so no 13 password is stored anywhere. Create a matching role and database: 14 15 sudo -u postgres createuser kych 16 sudo -u postgres createdb -O kych kych 17 18 Then load the schema. The SQL is installed under /usr/share/kych/sql; the 19 first file sets up the "Versioning" patch-level bookkeeping that upstream uses 20 for migrations, the second creates the oauth2gw schema itself: 21 22 sudo -u kych psql kych -f /usr/share/kych/sql/versioning.sql 23 sudo -u kych psql kych -f /usr/share/kych/sql/oauth2gw-0001.sql 24 25 Later upstream releases add further oauth2gw-000N.sql patches, which are 26 applied the same way, in order. /usr/share/kych/sql/drop.sql removes 27 everything again. 28 29 To use a remote database or password authentication instead, set DATABASE in 30 /etc/kych/kych.conf to a full connection URI. A password does not have to live 31 in the main file: with 32 33 @inline-secret@ kych-oauth2-gateway /etc/kych/secrets/database.conf 34 35 the DATABASE line can sit in a file of its own, restricted to root:kych, while 36 kych.conf itself stays readable. 37 38 2. Configure 39 ------------ 40 41 Edit /etc/kych/kych.conf. It is commented throughout; the parts you have to 42 touch are the credential settings (VC_*), the recommended ALLOWED_SCOPES 43 ceiling, and at least one [client_*] section. 44 45 Then register the clients in the database -- the running gateway reads clients 46 from there, not from the configuration file: 47 48 kych-client-management -c /etc/kych/kych.conf sync 49 kych-client-management -c /etc/kych/kych.conf list 50 51 Re-run "sync" after every change to a [client_*] section. Note that it does 52 not rotate an existing client's secret; delete and re-create the client for 53 that. 54 55 3. Start it 56 ----------- 57 58 systemctl enable --now kych 59 systemctl status kych 60 61 Socket activation (optional) 62 ---------------------------- 63 64 With the shipped SERVE = unix the daemon binds /run/kych/kych.sock itself and 65 kych.socket must stay disabled -- the two would fight over the same path. To 66 let systemd own the socket instead, so that it exists from boot and the daemon 67 starts on the first connection, change SERVE to "systemd" in 68 /etc/kych/kych.conf, comment out UNIXPATH, and swap the units: 69 70 systemctl disable --now kych.service 71 systemctl enable --now kych.socket 72 73 The socket path, its group (www-data) and its mode (0660) are the same either 74 way, so nothing changes for the reverse proxy. kych.socket is the place to 75 edit them in this mode; UNIXPATH_MODE is not consulted. 76 77 Reverse proxy 78 ------------- 79 80 The gateway speaks plain HTTP on the Unix socket /run/kych/kych.sock and does 81 not terminate TLS. The socket has group www-data and mode 0660, so a proxy 82 running as www-data can reach it. No web-server snippets are shipped; for 83 nginx the essential part is 84 85 location / { 86 proxy_pass http://unix:/run/kych/kych.sock; 87 proxy_set_header Host $host; 88 proxy_set_header X-Forwarded-Proto $scheme; 89 } 90 91 Do not expose the gateway directly: /notification accepts unauthenticated 92 webhooks from the SWIYU verifier and should additionally be restricted to the 93 verifier's address at the proxy. 94 95 Logs go to the journal: 96 97 journalctl -u kych -f 98 99 -- Taler Systems SA <deb@taler.net>