From fb38ef86dd5f5e6cb24fe82ac7ed03578c12b51b Mon Sep 17 00:00:00 2001
From: Jan Dittberner <jandd@cacert.org>
Date: Sat, 11 Sep 2021 11:39:10 +0200
Subject: [PATCH] Add Hydra setup documentation

---
 .gitignore |   3 ++
 README.md  | 145 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 148 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 README.md

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..8b505fc
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,3 @@
+.idea/
+certs/
+hydra.yaml
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b2322eb
--- /dev/null
+++ b/README.md
@@ -0,0 +1,145 @@
+# ORY Hydra configuration for CAcert
+
+This repository contains instructions how to setup [ORY
+Hydra](https://www.ory.sh/hydra/) for the OAuth2 / OpenID Connect operations
+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
+
+## 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:
+
+1. create signing requests
+
+   ```
+   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/
+   ```
+
+2. Use the CA to sign the certificates
+
+   ```
+   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 .
+   ```
+
+### Setup Hydra
+
+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.
+
+Perform the Hydra database setup:
+
+```
+sudo -i -u postgres psql
+> 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"
+```
+
+Create a configuration file for Hydra i.e. ``hydra.yaml``:
+
+```
+serve:
+  admin:
+    host: hydra.cacert.localhost
+  public:
+    host: auth.cacert.localhost
+  tls:
+    cert:
+      path: certs/hydra.cacert.localhost.crt.pem
+    key:
+      path: certs/hydra.cacert.localhost.key
+  dsn: 'postgres://hydra_local:${YOUR_POSTGRESQL_PASSWORD}@localhost:5432/hydra_local'
+
+webfinger:
+  oidc_discovery:
+    supported_claims:
+      - email
+      - email_verified
+      - given_name
+      - family_name
+      - middle_name
+      - name
+      - birthdate
+      - zoneinfo
+      - locale
+      - https://cacert.localhost/groups
+    supported_scope:
+      - profile
+      - email
+
+oauth2:
+  expose_internal_errors: false
+
+urls:
+  login: https://login.cacert.localhost:3000/login
+  consent: https://login.cacert.localhost:3000/consent
+  logout: https://login.cacert.localhost:3000/logout
+  error: https://login.cacert.localhost:3000/error
+  post_logout_redirect: https://login.cacert.localhost:3000/logout-successful
+  self:
+    public: https://auth.cacert.localhost:4444/
+    issuer: https://auth.cacert.localhost:4444/
+
+secrets:
+  system:
+    - "${YOUR SECRET FOR HYDRA}"
+```
+
+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:
+
+```
+::1 auth.cacert.localhost hydra.cacert.localhost
+```
+
+### Add OpenID Connect configuration for a client
+
+Create an OpenID Connect (OIDC) client configuration for the demo application
+
+```
+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 \
+    --name "Client App Demo" \
+    --scope "openid offline_access profile email" \
+    --post-logout-callbacks https://app.cacert.localhost:4000/after-logout \
+    --client-uri https://register.cacert.localhost:3000/info/app
+```
+
+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
+  ```