From 0f4bba55d5e5e89c4e65b4481c4a14ed3f360c47 Mon Sep 17 00:00:00 2001
From: Jan Dittberner <jandd@cacert.org>
Date: Tue, 9 Aug 2022 18:12:16 +0200
Subject: [PATCH] Update setup documentation

---
 .gitignore |  2 +-
 README.md  | 74 +++++++++++++++++++++++-------------------------------
 2 files changed, 33 insertions(+), 43 deletions(-)

diff --git a/.gitignore b/.gitignore
index 8b505fc..da3f76b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,3 @@
+*.pem
 .idea/
-certs/
 hydra.yaml
diff --git a/README.md b/README.md
index b2322eb..b9466fc 100644
--- a/README.md
+++ b/README.md
@@ -7,38 +7,25 @@ required for the CAcert IDP and client registration applications.
 The documentation in this repository is licensed under the terms of the Apache
 License Version 2.0.
 
-Copyright © 2020, 2021  Jan Dittberner
+Copyright © 2020, 2021, 2022  Jan Dittberner
 
 ## Setup
 
 ### Certificates
 
-You need a set of certificates for the Hydra. You can use the Test CA created
-by the ``setup_test_ca.sh`` script from the [CAcert developer
-setup](https://git.dittberner.info/jan/cacert-devsetup) repository like this:
+You need a set of certificates for the Hydra. I recommend to use the
+[mkcert](https://github.com/FiloSottile/mkcert) utility by Filippo Valsorda:
 
-1. create signing requests
+1. Setup local CA
 
-   ```
-   mkdir certs
-   cd certs
-   openssl req -new -newkey rsa:3072 -nodes \
-       -keyout hydra.cacert.localhost.key \
-       -out hydra.cacert.localhost.csr.pem \
-       -subj /CN=hydra.cacert.localhost \
-       -addext subjectAltName=DNS:hydra.cacert.localhost,DNS:auth.cacert.localhost
-   cp *.csr.pem $PATH_TO_DEVSETUP_TESTCA/
+   ```shell
+   mkcert -install
    ```
 
-2. Use the CA to sign the certificates
+2. Create a key pair and certificate
 
-   ```
-   pushd $PATH_TO_DEVSETUP_TESTCA/
-   openssl ca -config ca.cnf -name class3_ca -extensions server_ext \
-      -in hydra.cacert.localhost.csr.pem \
-      -out hydra.cacert.localhost.crt.pem -days 365
-   popd
-   cp $PATH_TO_DEVSETUP_TESTCA/hydra.cacert.localhost.crt.pem .
+   ```shell
+   mkcert hydra.cacert.localhost auth.cacert.localhost
    ```
 
 ### Setup Hydra
@@ -47,17 +34,25 @@ We use the ORY Hydra OAuth2 / OpenID Connect implementation. Install Hydra
 according to their [documentation](https://www.ory.sh/hydra/docs/install).
 The setup has been tested with the Linux binary installation.
 
+Preconditions:
+
+- generate certificate + key (see above)
+- generate a database password (`openssl rand -base64 16` might be a good idea)
+- generate a secret key for your instance (`openssl rand -base64 32` might be a good idea)
+
 Perform the Hydra database setup:
 
-```
+```shell
 sudo -i -u postgres psql
-> CREATE DATABASE hydra_local ENCODING utf-8;
+> CREATE DATABASE hydra_local ENCODING 'utf-8';
 > CREATE USER hydra_local WITH PASSWORD '${YOUR_POSTGRESQL_PASSWORD}';
 > GRANT CONNECT, CREATE ON DATABASE hydra_local TO hydra_local;
 
 hydra migrate sql "postgres://hydra_local:${YOUR_POSTGRESQL_PASSWORD}@localhost:5432/hydra_local"
 ```
 
+*Note*: replace `${YOUR_POSTGRESQL_PASSWORD}` with the password generated above
+
 Create a configuration file for Hydra i.e. ``hydra.yaml``:
 
 ```
@@ -68,9 +63,9 @@ serve:
     host: auth.cacert.localhost
   tls:
     cert:
-      path: certs/hydra.cacert.localhost.crt.pem
+      path: hydra.cacert.localhost+1.pem
     key:
-      path: certs/hydra.cacert.localhost.key
+      path: hydra.cacert.localhost+1.key.pem
   dsn: 'postgres://hydra_local:${YOUR_POSTGRESQL_PASSWORD}@localhost:5432/hydra_local'
 
 webfinger:
@@ -105,25 +100,28 @@ urls:
 
 secrets:
   system:
-    - "${YOUR SECRET FOR HYDRA}"
+    - "${YOUR_SECRET_FOR_HYDRA}"
 ```
 
+*Note:* Replace `${YOUR_POSTGRESQL_PASSWORD}` and `${YOUR_SECRET_FOR_HYDRA}`
+with the values generated above.
+
 The available configuration options are described in the
 [Hydra configuration documentation](https://www.ory.sh/hydra/docs/reference/configuration).
 
-Hydra needs to be able to resolve its hostnames and does not work with the
-systemd-nss module. You therefore need to define Hydra's hostnames in your
-``/etc/hosts`` file:
+## Start
 
-```
-::1 auth.cacert.localhost hydra.cacert.localhost
+Now you can start Hydra:
+
+```shell
+hydra serve all --config hydra.yaml
 ```
 
-### Add OpenID Connect configuration for a client
+## Add OpenID Connect configuration for a client
 
 Create an OpenID Connect (OIDC) client configuration for the demo application
 
-```
+```shell
 hydra clients create --endpoint https://hydra.cacert.localhost:4445/ \
     --callbacks https://app.cacert.localhost:4000/callback \
     --logo-uri https://register.cacert.localhost:3000/images/app.png \
@@ -135,11 +133,3 @@ hydra clients create --endpoint https://hydra.cacert.localhost:4445/ \
 
 The command returns a client id and a client secret, that you need for the
 demo application configuration.
-
-## Start
-
-Now you can start Hydra:
-
-  ```
-  hydra serve all --config hydra.yaml
-  ```