Improve and document frontend resource build

Document the frontend build and reformat README.md to improve structure
and readability. Switch from plain npm to yarn.
This commit is contained in:
Jan Dittberner 2021-01-02 10:42:19 +01:00
parent 49c91cddb0
commit cd61f7d3cf
4 changed files with 2569 additions and 9804 deletions

164
README.md
View file

@ -7,11 +7,14 @@ in this repository provides the UI components that are required by Hydra.
## Setup
- create certificates for the IDP, the application and Hydra. You can use the
testca from the [CAcert developer setup](https://git.dittberner.info/jan/cacert-devsetup)
like this:
### Certificates
1. create signing requests
You need a set of certificates for the IDP, the application and 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
@ -34,7 +37,7 @@ in this repository provides the UI components that are required by Hydra.
cp *.csr.pem $PATH_TO_DEVSETUP_TESTCA/
```
2. Use the CA to sign the certificates
2. Use the CA to sign the certificates
```
pushd $PATH_TO_DEVSETUP_TESTCA/
@ -47,23 +50,34 @@ in this repository provides the UI components that are required by Hydra.
cp $PATH_TO_DEVSETUP_TESTCA/{hydra,idp,app}.cacert.localhost.crt.pem .
```
- install Hydra according to their documentation
- setup the Hydra database
3. Copy CA certificate for client certificates
```
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"
openssl x509 -in $PATH_TO_DEVSETUP_TESTCA/class3/ca.crt.pem \
-out client_ca.pem
```
- create a configuration file for Hydra i.e. hydra.yaml:
### Setup Hydra
```
serve:
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:
@ -75,7 +89,7 @@ in this repository provides the UI components that are required by Hydra.
path: certs/hydra.cacert.localhost.key
dsn: 'postgres://hydra_local:${YOUR_POSTGRESQL_PASSWORD}@localhost:5432/hydra_local'
webfinger:
webfinger:
oidc_discovery:
supported_claims:
- email
@ -92,10 +106,10 @@ in this repository provides the UI components that are required by Hydra.
- profile
- email
oauth2:
oauth2:
expose_internal_errors: false
urls:
urls:
login: https://login.cacert.localhost:3000/login
consent: https://login.cacert.localhost:3000/consent
logout: https://login.cacert.localhost:3000/logout
@ -105,69 +119,101 @@ in this repository provides the UI components that are required by Hydra.
public: https://auth.cacert.localhost:4444/
issuer: https://auth.cacert.localhost:4444/
secrets:
secrets:
system:
- "${YOUR SECRET FOR HYDRA}"
```
```
- add entries for auth.cacert.localhost and hydra.cacert.localhost to /etc/hosts
The available configuration options are described in the
[Hydra configuration documentation](https://www.ory.sh/hydra/docs/reference/configuration).
```
::1 auth.cacert.localhost hydra.cacert.localhost
```
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:
This is required to allow Hydra to start properly
```
::1 auth.cacert.localhost hydra.cacert.localhost
```
- create an OIDC client configuration for the demo application
### Add OpenID Connect configuration for a client
```
hydra clients create --endpoint https://hydra.cacert.localhost:4445/ \
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 to
configure for the demo application
The command returns a client id and a client secret, that you need for the
demo application configuration.
- create a configuration for the IDP
### Configure IDP
The IDP requires a strong random key for its CSRF cookie. You can generate
such a key using the following openssl command:
The Identity Provider application (IDP) requires a strong random key for its
CSRF cookie. You can generate such a key using the following openssl command:
```
openssl rand -base64 32
```
```
openssl rand -base64 32
```
Use this value and create `idp.toml`:
Use this value and the database credentials from your cacert-devsetup and
create `idp.toml`:
```
[security]
csrf.key = "<32 bytes of base64 encoded data>"
```
```
[security]
csrf.key = "<32 bytes of base64 encoded data>"
- create a configuration for the Demo application
[db]
dsn = "$MYSQL_USER:$MYSQL_PASSWORD@tcp(localhost:13306)/cacert
```
You will need a 32 byte and a 64 byte random secret for the session
authentication and encryption keys:
### Configure the Demo Application
```
openssl rand -base64 64
openssl rand -base64 32
```
You will need a 32 byte and a 64 byte random secret for the session
authentication and encryption keys:
```
[oidc]
client-id = "<client id from hydra clients invocation>"
client-secret = "<client secret from hydra clients invocation>"
```
openssl rand -base64 64
openssl rand -base64 32
```
[session]
auth-key = "<64 bytes of base64 encoded data>"
enc-key = "<32 bytes of base64 encoded data>"
```
You also need the client id and the client secret, that have been generated
during the OIDC client setup described above.
```
[oidc]
client-id = "<client id from hydra clients invocation>"
client-secret = "<client secret from hydra clients invocation>"
[session]
auth-key = "<64 bytes of base64 encoded data>"
enc-key = "<32 bytes of base64 encoded data>"
```
## Frontend resource build
The frontend resources are built using [webpack 5](https://webpack.js.org/)
and [yarn](https://classic.yarnpkg.com/lang/en/). You need recent nodejs
and yarn versions. See the
[Debian installation instructions](https://github.com/nodesource/distributions/blob/master/README.md#debinstall)
of nodesource or look at the other options on the
[nodejs Download page](https://nodejs.org/en/download/) if you cannot use
Debian Bullseye or newer.
When you are sure that you have nodejs >= 12 and yarn you can install the
required dependencies and run webpack like this:
```
yarn
yarn run build
```
## Start
Now you can start Hydra, the IDP and the demo app in 3 terminal windows:

9679
package-lock.json generated

File diff suppressed because it is too large Load diff

View file

@ -32,6 +32,7 @@ module.exports = {
path: path.resolve(__dirname, 'static'),
filename: 'js/[name].bundle.js',
},
devtool: 'source-map',
optimization: {
minimize: true,
minimizer: [new TerserPlugin()],
@ -59,14 +60,14 @@ module.exports = {
loader: 'postcss-loader',
options: {
postcssOptions: {
plugins: function () {
return [
require('precss'),
require('autoprefixer'),
];
}
}
}
plugins: [
[
'precss',
'autoprefixer',
],
],
},
},
}, {
loader: 'sass-loader',
}]

2397
yarn.lock Normal file

File diff suppressed because it is too large Load diff