oidc-hydra-config/README.md

# 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
  ```