diff --git a/README.md b/README.md index 8977e70..0c72f29 100644 --- a/README.md +++ b/README.md @@ -17,16 +17,9 @@ git config submodule.recurse true 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 +sudo apt install git golang-go make mkcert postgresql python3-pip python3-venv 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 @@ -38,27 +31,31 @@ export PATH=$HOME/.local/bin:$PATH `.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. +*Note:* If you want to do everything manually, read on. Otherwise skip to the +ansible or Vagrant options below. + +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 + 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 + 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 +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. +Third, go in to the `oidc_app` sub-directory. There, you again need to create a certicate and key pair using mkcert. @@ -66,19 +63,19 @@ Third, go in to the oidc_app sub-directory. 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. +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. +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 + As well, after creating a secret key, you will create the configuration file, registration.toml. ### Continuing @@ -90,14 +87,12 @@ needed by this system. 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: @@ -132,8 +127,9 @@ 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: +*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 @@ -141,8 +137,8 @@ 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 +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 @@ -152,22 +148,19 @@ vagrant ssh -- cat .local/share/mkcert/rootCA.pem | sudo tee /usr/local/share/ca sudo update-ca-certificates ``` - -======== - ## Finally -Note: You may also want to configure your browser to trust the CA certificate +*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. +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". +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 @@ -185,5 +178,10 @@ This should give you a JSON document with information about the authorization se 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. +welcome page with a CAcert logo. +### Test the demo application + +Open [https://app.cacert.localhost:4000/](https://app.cacert.localhost:4000/) +to visit the demo application. Login should redirect you to the IDP, request +consent and redirect back to the application.