From 12e3cd56b130a6ef71058b734a6d51fe298c335f Mon Sep 17 00:00:00 2001 From: James Elliott Date: Sun, 23 Oct 2022 18:09:19 +1100 Subject: [PATCH] docs: refactor generator guides (#4244) --- .../en/configuration/first-factor/ldap.md | 2 +- .../identity-providers/open-id-connect.md | 4 +- .../en/configuration/miscellaneous/guides.md | 77 --------- .../en/configuration/miscellaneous/server.md | 2 +- .../en/configuration/notifications/smtp.md | 2 +- .../en/configuration/session/introduction.md | 2 +- .../content/en/configuration/session/redis.md | 4 +- .../en/configuration/storage/introduction.md | 2 +- .../content/en/configuration/storage/mysql.md | 2 +- .../en/configuration/storage/postgres.md | 2 +- .../openid-connect/specific-information.md | 4 +- .../overview/prologue/architecture/index.md | 2 +- .../guides/generating-secure-values.md | 151 ++++++++++++++++++ 13 files changed, 165 insertions(+), 91 deletions(-) delete mode 100644 docs/content/en/configuration/miscellaneous/guides.md create mode 100644 docs/content/en/reference/guides/generating-secure-values.md diff --git a/docs/content/en/configuration/first-factor/ldap.md b/docs/content/en/configuration/first-factor/ldap.md index 3afff36d0..a46710169 100644 --- a/docs/content/en/configuration/first-factor/ldap.md +++ b/docs/content/en/configuration/first-factor/ldap.md @@ -289,7 +289,7 @@ especially for containerized deployments.* The password paired with the [user](#user) used to bind to the LDAP server for lookup and password change operations. It's __strongly recommended__ this is a -[Random Alphanumeric String](../miscellaneous/guides.md#generating-a-random-alphanumeric-string) with 64 or more +[Random Alphanumeric String](../../reference/guides/generating-secure-values.md#generating-a-random-alphanumeric-string) with 64 or more characters and the user password is changed to this value. ## Refresh Interval diff --git a/docs/content/en/configuration/identity-providers/open-id-connect.md b/docs/content/en/configuration/identity-providers/open-id-connect.md index 04fd9677e..9baad93f0 100644 --- a/docs/content/en/configuration/identity-providers/open-id-connect.md +++ b/docs/content/en/configuration/identity-providers/open-id-connect.md @@ -157,7 +157,7 @@ The HMAC secret used to sign the [JWT]'s. The provided string is hashed to a SHA purpose of meeting the required format. It's __strongly recommended__ this is a -[Random Alphanumeric String](../miscellaneous/guides.md#generating-a-random-alphanumeric-string) with 64 or more +[Random Alphanumeric String](../../reference/guides/generating-secure-values.md#generating-a-random-alphanumeric-string) with 64 or more characters. ### issuer_certificate_chain @@ -185,7 +185,7 @@ certificate immediately following it if present. especially for containerized deployments.* The private key used to sign/encrypt the [OpenID Connect] issued [JWT]'s. The key must be generated by the administrator -and can be done by following the [Generating an RSA Keypair](../miscellaneous/guides.md#generating-an-rsa-keypair) guide. +and can be done by following the [Generating an RSA Keypair](../../reference/guides/generating-secure-values.md#generating-an-rsa-keypair) guide. The private key *__MUST__*: * Be a PEM block encoded in the DER base64 format ([RFC4648]). diff --git a/docs/content/en/configuration/miscellaneous/guides.md b/docs/content/en/configuration/miscellaneous/guides.md deleted file mode 100644 index 20e04b6ed..000000000 --- a/docs/content/en/configuration/miscellaneous/guides.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: "Guides" -description: "Miscellaneous Guides for Configuration." -lead: "This section contains miscellaneous guides used in the configuration." -date: 2022-06-15T17:51:47+10:00 -draft: false -images: [] -menu: - configuration: - parent: "miscellaneous" -weight: 199500 -toc: true ---- - -## Generating a Random Alphanumeric String - -Some sections of the configuration recommend generating a random string. There are many ways to accomplish this, one -possible way on Linux is utilizing the following command which prints a string with a length in characters of -`${LENGTH}` to `stdout`. The string will only contain alphanumeric characters. - -```bash -LENGTH=64 -tr -cd '[:alnum:]' < /dev/urandom | fold -w "${LENGTH}" | head -n 1 | tr -d '\n' ; echo -``` - -## Generating an RSA Keypair - -Some sections of the configuration need an RSA keypair. There are many ways to achieve this, this section explains two -such ways. - -### openssl - -The `openssl` command on Linux can be used to generate a RSA 4096 bit keypair: - -```bash -openssl genrsa -out private.pem 4096 -openssl rsa -in private.pem -outform PEM -pubout -out public.pem -``` - -### authelia - -The __Authelia__ docker container or CLI binary can be used to generate a RSA 4096 bit keypair: - -```bash -docker run -u "$(id -u):$(id -g)" -v "$(pwd)":/keys authelia/authelia:latest authelia crypto pair rsa generate --bits 4096 --directory /keys -``` - -```bash -authelia crypto pair rsa generate --directory /path/to/keys -``` - -## Generating an RSA Self-Signed Certificate - -Some sections of the configuration need a certificate and it may be possible to use a self-signed certificate. There are -many ways to achieve this, this section explains two such ways. - -### openssl - -The `openssl` command on Linux can be used to generate a RSA 4096 bit self-signed certificate for the domain -`example.com`: - -```bash -openssl req -x509 -nodes -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 365 -subj '/CN=example.com' -``` - -### authelia - -The __Authelia__ docker container or binary can be used to generate a RSA 4096 bit self-signed certificate for the -domain `example.com`: - -```bash -docker run -u "$(id -u):$(id -g)" -v "$(pwd)":/keys authelia/authelia authelia crypto certificate rsa generate --common-name example.com --directory /keys -``` - -```bash -authelia crypto certificate rsa generate --common-name example.com --directory /path/to/keys -``` diff --git a/docs/content/en/configuration/miscellaneous/server.md b/docs/content/en/configuration/miscellaneous/server.md index 65ba79629..45529df05 100644 --- a/docs/content/en/configuration/miscellaneous/server.md +++ b/docs/content/en/configuration/miscellaneous/server.md @@ -130,7 +130,7 @@ security on lower areas of the OSI model. However it required, if you specify bo [tls certificate](#certificate) options, Authelia will listen for TLS connections. The key must be generated by the administrator and can be done by following the -[Generating an RSA Self Signed Certificate](../miscellaneous/guides.md#generating-an-rsa-self-signed-certificate) +[Generating an RSA Self Signed Certificate](../../reference/guides/generating-secure-values.md#generating-an-rsa-self-signed-certificate) guide provided a self-signed certificate is fit for purpose. If a self-signed certificate is fit for purpose is beyond the scope of the documentation and if it is not fit for purpose we instead recommend generating a certificate signing request or obtaining a certificate signed by one of the many ACME certificate providers. Methods to achieve this are diff --git a/docs/content/en/configuration/notifications/smtp.md b/docs/content/en/configuration/notifications/smtp.md index e2a69d963..511bb668b 100644 --- a/docs/content/en/configuration/notifications/smtp.md +++ b/docs/content/en/configuration/notifications/smtp.md @@ -156,7 +156,7 @@ especially for containerized deployments.* The password paired with the [username](#username) sent for authentication with the SMTP server. It's __strongly recommended__ this is a -[Random Alphanumeric String](../miscellaneous/guides.md#generating-a-random-alphanumeric-string) with 64 or more +[Random Alphanumeric String](../../reference/guides/generating-secure-values.md#generating-a-random-alphanumeric-string) with 64 or more characters and the user password is changed to this value. ### sender diff --git a/docs/content/en/configuration/session/introduction.md b/docs/content/en/configuration/session/introduction.md index 494ab0832..6bc2a3baa 100644 --- a/docs/content/en/configuration/session/introduction.md +++ b/docs/content/en/configuration/session/introduction.md @@ -88,7 +88,7 @@ especially for containerized deployments.* The secret key used to encrypt session data in Redis. It's __strongly recommended__ this is a -[Random Alphanumeric String](../miscellaneous/guides.md#generating-a-random-alphanumeric-string) with 64 or more +[Random Alphanumeric String](../../reference/guides/generating-secure-values.md#generating-a-random-alphanumeric-string) with 64 or more characters. ### expiration diff --git a/docs/content/en/configuration/session/redis.md b/docs/content/en/configuration/session/redis.md index e8fc23dc3..fa6b9dd8a 100644 --- a/docs/content/en/configuration/session/redis.md +++ b/docs/content/en/configuration/session/redis.md @@ -154,7 +154,7 @@ especially for containerized deployments.* The password for [redis authentication](https://redis.io/commands/auth). It's __strongly recommended__ this is a -[Random Alphanumeric String](../miscellaneous/guides.md#generating-a-random-alphanumeric-string) with 64 or more +[Random Alphanumeric String](../../reference/guides/generating-secure-values.md#generating-a-random-alphanumeric-string) with 64 or more characters and the user password is changed to this value. ### database_index @@ -213,7 +213,7 @@ authenticate to the Redis Sentinel with ACL-based authentication. Otherwise, thi authentication. It's __strongly recommended__ this is a -[Random Alphanumeric String](../miscellaneous/guides.md#generating-a-random-alphanumeric-string) with 64 or more +[Random Alphanumeric String](../../reference/guides/generating-secure-values.md#generating-a-random-alphanumeric-string) with 64 or more characters and the user password is changed to this value. #### nodes diff --git a/docs/content/en/configuration/storage/introduction.md b/docs/content/en/configuration/storage/introduction.md index 412fa9fcb..d2c09e830 100644 --- a/docs/content/en/configuration/storage/introduction.md +++ b/docs/content/en/configuration/storage/introduction.md @@ -44,7 +44,7 @@ value, and use that to encrypt the data with the AES-GCM 256bit algorithm. The minimum length of this key is 20 characters. It's __strongly recommended__ this is a -[Random Alphanumeric String](../miscellaneous/guides.md#generating-a-random-alphanumeric-string) with 64 or more +[Random Alphanumeric String](../../reference/guides/generating-secure-values.md#generating-a-random-alphanumeric-string) with 64 or more characters. See [security measures](../../overview/security/measures.md#storage-security-measures) for more information. diff --git a/docs/content/en/configuration/storage/mysql.md b/docs/content/en/configuration/storage/mysql.md index f9ef749c1..15aa648ee 100644 --- a/docs/content/en/configuration/storage/mysql.md +++ b/docs/content/en/configuration/storage/mysql.md @@ -174,7 +174,7 @@ especially for containerized deployments.* The password paired with the [username](#username) used to connect to the database. It's __strongly recommended__ this is a -[Random Alphanumeric String](../miscellaneous/guides.md#generating-a-random-alphanumeric-string) with 64 or more +[Random Alphanumeric String](../../reference/guides/generating-secure-values.md#generating-a-random-alphanumeric-string) with 64 or more characters and the user password is changed to this value. ### timeout diff --git a/docs/content/en/configuration/storage/postgres.md b/docs/content/en/configuration/storage/postgres.md index d888640d5..4c3adbc60 100644 --- a/docs/content/en/configuration/storage/postgres.md +++ b/docs/content/en/configuration/storage/postgres.md @@ -178,7 +178,7 @@ especially for containerized deployments.* The password paired with the [username](#username) used to connect to the database. It's __strongly recommended__ this is a -[Random Alphanumeric String](../miscellaneous/guides.md#generating-a-random-alphanumeric-string) with 64 or more +[Random Alphanumeric String](../../reference/guides/generating-secure-values.md#generating-a-random-alphanumeric-string) with 64 or more characters and the user password is changed to this value. ### timeout diff --git a/docs/content/en/integration/openid-connect/specific-information.md b/docs/content/en/integration/openid-connect/specific-information.md index 8e461e1d7..a89bf29b6 100644 --- a/docs/content/en/integration/openid-connect/specific-information.md +++ b/docs/content/en/integration/openid-connect/specific-information.md @@ -25,12 +25,12 @@ We strongly recommend the following guidelines for generating client secrets: 5. Secrets should only have alphanumeric characters as some implementations do not appropriately encode the secret when using it to access the token endpoint. -Authelia provides an easy way to perform such actions via the [authelia crypto hash generate] command. Users can +Authelia provides an easy way to perform such actions via the [Generating a Random Password Hash] guide. Users can perform a command such as `authelia crypto hash generate pbkdf2 --variant sha512 --random --random.length 72` command to both generate a client secret with 72 characters which is printed and is to be used with the relying party and hash it using PBKDF2 which can be stored in the Authelia configuration. -[authelia crypto hash generate]: ../../reference/cli/authelia/authelia_crypto_hash_generate.md +[Generating a Random Password Hash]: ../../reference/guides/generating-secure-values.md#generating-a-random-password-hash ### Plaintext diff --git a/docs/content/en/overview/prologue/architecture/index.md b/docs/content/en/overview/prologue/architecture/index.md index 9b012bcde..d4e36f494 100644 --- a/docs/content/en/overview/prologue/architecture/index.md +++ b/docs/content/en/overview/prologue/architecture/index.md @@ -54,5 +54,5 @@ connections. Please note that it has been decided that we won't support websites risk due to misconfiguration (see [#590](https://github.com/authelia/authelia/issues/590)). If a self-signed certificate is required, the -[Generating an RSA Self-Signed Certificate](../../../configuration/miscellaneous/guides.md#generating-an-rsa-self-signed-certificate) +[Generating an RSA Self-Signed Certificate](../../../reference/guides/generating-secure-values.md#generating-an-rsa-self-signed-certificate) guide should be followed. diff --git a/docs/content/en/reference/guides/generating-secure-values.md b/docs/content/en/reference/guides/generating-secure-values.md new file mode 100644 index 000000000..46f9e7d46 --- /dev/null +++ b/docs/content/en/reference/guides/generating-secure-values.md @@ -0,0 +1,151 @@ +--- +title: "Generating Secure Values" +description: "A reference guide on generating secure values such as password hashes, password strings, and cryptography keys" +lead: "This section contains reference documentation for generating secure values such as password hashes, password strings, and cryptography keys." +date: 2022-06-15T17:51:47+10:00 +draft: false +images: [] +menu: + reference: + parent: "guides" +weight: 220 +toc: true +--- + +## Generating a Random Password Hash + +Often times it's required that a random password is generated. While you could randomly generate a string then hash it, +we provide a convenience layer for this purpose. + +### authelia + +The __Authelia__ docker container or CLI binary can be used to generate a random alphanumeric string and output the +the string and the hash at the same time. + +Use the `authelia crypto hash generate --help` command or see the [authelia crypto hash generate] reference guide for +more information on all available options and algorithms. + +##### Using Docker + +```bash +docker run authelia/authelia:latest authelia crypto hash generate argon2 --random --random.length 64 --random.charset alphanumeric +``` + +##### Using the Binary + +```bash +authelia crypto hash generate argon2 --random --random.length 64 --random.charset alphanumeric +``` + +## Generating a Random Alphanumeric String + +Some sections of the configuration recommend generating a random string. There are many ways to accomplish this and the +following methods are merely suggestions. + +### authelia + +The __Authelia__ docker container or CLI binary can be used to generate a random alphanumeric string. + +Use the `authelia crypto rand --help` command or see the [authelia crypto rand] reference guide for more information on +all available options. + +##### Using Docker + +```bash +docker run authelia/authelia:latest authelia crypto rand --length 64 --charset alphanumeric +``` + +##### Using the Binary + +```bash +authelia crypto rand --length 64 --charset alphanumeric +``` + +### openssl + +The `openssl` command on Linux can be used to generate a random alphanumeric string: + +```bash +openssl rand -hex 64 +``` + +### Linux + +Basic Linux commands can be used to generate a random alphanumeric string: + +```bash +LENGTH=64 +tr -cd '[:alnum:]' < /dev/urandom | fold -w "${LENGTH}" | head -n 1 | tr -d '\n' ; echo +``` + +## Generating an RSA Keypair + +Some sections of the configuration need an RSA keypair. There are many ways to achieve this, this section explains two +such ways. + +### authelia + +The __Authelia__ docker container or CLI binary can be used to generate a RSA 4096 bit keypair. + +Use the `authelia crypto pair --help` command or see the [authelia crypto pair] reference guide for more +information on all available options. + +##### Using Docker + +```bash +docker run -u "$(id -u):$(id -g)" -v "$(pwd)":/keys authelia/authelia:latest authelia crypto pair rsa generate --bits 4096 --directory /keys +``` + +##### Using the Binary + +```bash +authelia crypto pair rsa generate --directory /path/to/keys +``` + +### openssl + +The `openssl` command on Linux can be used to generate a RSA 4096 bit keypair: + +```bash +openssl genrsa -out private.pem 4096 +openssl rsa -in private.pem -outform PEM -pubout -out public.pem +``` + +## Generating an RSA Self-Signed Certificate + +Some sections of the configuration need a certificate and it may be possible to use a self-signed certificate. There are +many ways to achieve this, this section explains two such ways. + +### authelia + +The __Authelia__ docker container or binary can be used to generate a RSA 4096 bit self-signed certificate for the +domain `example.com`. + +Use the `authelia crypto certificate --help` command or see the [authelia crypto certificate] reference guide for more +information on all available options. + +##### Using Docker + +```bash +docker run -u "$(id -u):$(id -g)" -v "$(pwd)":/keys authelia/authelia authelia crypto certificate rsa generate --common-name example.com --directory /keys +``` + +##### Using the Binary + +```bash +authelia crypto certificate rsa generate --common-name example.com --directory /path/to/keys +``` + +### openssl + +The `openssl` command on Linux can be used to generate a RSA 4096 bit self-signed certificate for the domain +`example.com`: + +```bash +openssl req -x509 -nodes -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 365 -subj '/CN=example.com' +``` + +[authelia crypto hash generate]: ../cli/authelia/authelia_crypto_hash_generate.md +[authelia crypto rand]: ../cli/authelia/authelia_crypto_rand.md +[authelia crypto pair]: ../cli/authelia/authelia_crypto_pair.md +[authelia crypto certificate]: ../cli/authelia/authelia_crypto_certificate.md