oidc-parent/README.md

# CAcert OpenID connect parent project

This repository references several repositories for the CAcert OpenID connect
setup.

## Clone the repository

```shell
git clone --recurse-submodules https://code.cacert.org/cacert/oidc-parent.git
cd oidc-parent
# cause pull, fetch and other git commands to consider submodules
git config submodule.recurse true
```

## Get started

Make sure you have the necessary prerequisites installed (tested on Debian 12
Bookworm) and `~/.local/bin` in your `$PATH` variable:

Those prerequisites include:
git -- of course
PostgreSQL -- see README-extra.md
Hydra -- see hydra_config/README.md

Further items are installed here:

```shell
sudo apt update
sudo apt install make mkcert python3-pip python3-venv golang-go yarnpkg
mkdir -p $HOME/.local/share/virtualenvs ~/.local/bin
python3 -m venv $HOME/.local/share/virtualenvs/ansible
$HOME/.local/share/virtualenvs/ansible/bin/pip install ansible
ln -s $HOME/.local/share/virtualenvs/ansible/bin/ansible* $HOME/.local/bin/
export PATH=$HOME/.local/bin:$PATH
```

*Note:* It is a good idea to put the `PATH` export line into your `.bashrc` or
`.zshenv`.

### Initial Configuration
Each of the sub-directories contains instructions for creating or editing
a configuration file and, usually, certificates.

The first that must be performed are the instructions found in the "hydra_config"
sub-directory.  

    In that one, you must first install Hydra before you continue.

    Next, create a certificate and key pair using mkcert, set your database 
    password, and generate a secret key for Hydra.

    Following that, you need to create the Hydra configuration file, hydra.yaml.

    Finally, after starting Hydra, you need to create a Hydra Client, using the 
    command found at the bottom of the README.md in that directory.  Save the 
    values returned from that command.

Next, go in to the cacert_resources sub-directory and follow the directions 
in that README.md regarding installing nodejs and webpack.

Third, go in to the oidc_app sub-directory.

    There, you again need to create a certicate and key pair using mkcert.

    Create the configuration file, resource_app.toml, using the values created
    from the Hydra command described in the hydra_config README.md, and the two
    secret keys as described in the current README.md file.

Next, the oidc_idp sub-directory.

    Again, you will need to create the certificate and key pair using mkcert.

    Create the configuration file, idp.toml, using only the a secret key, as
    described in the current README.md file.

Finally, change into the oidc_registration sub-directory.

    There, you will find detailed instructions for certificate creation for
    this module.

    As well, after creating a secret key, you will create the configuration 
    file, registration.toml.

### Continuing

At this point, you should have created all of the certificates and configuration files
needed by this system.

### Build the applications

Use `make` to build the web app resources and applications:


### Install the language translation tool

```shell
go install github.com/nicksnyder/go-i18n/v2/goi18n@latest
```


### Build the applications

Use `make` to build the web app resources and applications:

```shell
make
```

## Deployment options

There are two deployment options for the Hydra server and for the custom applications:

1. local deployment
2. Vagrant deployment

You only need one of these options.

Both options use [ansible](https://docs.ansible.com/) to:

- setup the Hydra authorization server
- setup IDP (provides login and consent screens)
- setup demo application
- setup OpenID Connect client registration application

### Local deployment

Use `ansible-playbook` to deploy Hydra, IDP, Client registration and the demo
application:

```shell
cd deployment
ansible-playbook 01_install_cacert_oidc.yml
```

Note: If ansible-playbook fails early in the process with "sudo: a password is required," 
then confirm that your user has sudo privileges and execute the `ansible-playbook` command like:

```shell
ansible-playbook -K 01_install_cacert_oidc.yml
```

### Vagrant setup

Instead of Ansible, you can also use [Vagrant](https://www.vagrantup.com/) with the
libvirt-provider. The included Vagrantfile is configured to apply the
ansible-playbook to the Vagrant managed virtual machine.

```shell
sudo apt install vagrant-libvirt virt-manager libvirt-clients
vagrant up
vagrant ssh -- cat .local/share/mkcert/rootCA.pem | sudo tee /usr/local/share/ca-certificates/mkcert-vagrant-oidc.crt
sudo update-ca-certificates
```


========

## Finally

Note: You may also want to configure your browser to trust the CA certificate
in `/usr/local/share/ca-certificates/mkcert-vagrant-oidc.crt`. If you do not
add this trust configuration you will get browser warnings for an unknown
certificate authority.

## Testing your local setup

After running "make" and "ansible-playbook," Hydra and oidc-idp will both be running.

To run the rest of the components, in each of two new terminal windows, execute 
"oidc_app/demo-app" and "oidc_registration/cacert-oidc-registration".


### Test the authorization server

Request the OpenID connect auto discovery information from Hydra

```shell
curl https://hydra.cacert.localhost:4444/.well-known/openid-configuration | python3 -m json.tool
```

This should give you a JSON document with information about the authorization server.

### Test the identity provider

Open
[https://login.cacert.localhost:3000/](https://login.cacert.localhost:3000/)
this should ask you for a CAcert class 3 client certificate and should render a
404 page with a CAcert logo.