diff --git a/docs/content/en/configuration/methods/files.md b/docs/content/en/configuration/methods/files.md index 667d38df3..8793cf889 100644 --- a/docs/content/en/configuration/methods/files.md +++ b/docs/content/en/configuration/methods/files.md @@ -61,7 +61,7 @@ authelia --config configuration.yml,config-acl.yml,config-other.yml ``` Authelia's configuration files use the YAML format. A template with all possible options can be found at the root of the -repository [here](https://github.com/authelia/authelia/blob/master/config.template.yml). +repository {{< github-link name="here" path="config.template.yml" >}}. *__Important Note:__ You should not have configuration sections such as Access Control Rules or OpenID Connect clients configured in multiple files. If you wish to split these into their own files that is fine, but if you have two files that diff --git a/docs/content/en/configuration/prologue/introduction.md b/docs/content/en/configuration/prologue/introduction.md index 76763c33a..586d61935 100644 --- a/docs/content/en/configuration/prologue/introduction.md +++ b/docs/content/en/configuration/prologue/introduction.md @@ -16,9 +16,8 @@ toc: true We document the configuration in two ways: -1. The [YAML] configuration template - [config.template.yml](https://github.com/authelia/authelia/blob/master/config.template.yml) has comments with very - limited documentation on the effective use of a particular option. All documentation lines start with `##`. Lines +1. The [YAML] configuration template {{< github-link path="config.template.yml" >}} has comments with very limited + documentation on the effective use of a particular option. All documentation lines start with `##`. Lines starting with a single `#` are [YAML] configuration options which are commented to disable them or as examples. 2. This documentation site. Generally each section of the configuration is in its own section of the documentation site. Each configuration option is listed in its relevant section as a heading, under that heading generally are two diff --git a/docs/content/en/contributing/development/environment.md b/docs/content/en/contributing/development/environment.md index 96fd84e29..008b87fc5 100644 --- a/docs/content/en/contributing/development/environment.md +++ b/docs/content/en/contributing/development/environment.md @@ -38,6 +38,23 @@ The additional tools are recommended: * [yamllint] * [VSCodium] or [GoLand] +## Certificate + +Authelia utilizes a self-signed Root CA certificate for the development environment. This allows us to sign elements of +the CI process uniformly and only trust a single additional Root CA Certificate. The private key for this certificate is +maintained by the [Core Team] so if you need an additional certificate signed for this purpose please reach out to them. + +While developing for Authelia you may also want to trust this Root CA. It is critical that you are aware of what this +means if you decide to do so. + +1. It will allow us to generate trusted certificates for machines this is installed on. +2. If compromised there is no formal revocation process at this time as we are not a certified CA. +3. Trusting Root CA's is not necessary for the development process it only makes it smoother. +4. Trusting additional Root CA's for prolonged periods is not generally a good idea. + +If you'd still like to trust the Root CA Certificate it's located (encoded as a PEM) in the main git repository at + [/internal/suites/common/pki/ca/ca.public.crt](https://github.com/authelia/authelia/blob/master/internal/suites/common/pki/ca/ca.public.crt). + ## Scripts There is a scripting context provided with __Authelia__ which can easily be configured. It allows running integration diff --git a/docs/content/en/integration/deployment/bare-metal.md b/docs/content/en/integration/deployment/bare-metal.md index 0e8126be3..8e03e00fb 100644 --- a/docs/content/en/integration/deployment/bare-metal.md +++ b/docs/content/en/integration/deployment/bare-metal.md @@ -25,8 +25,8 @@ bootstrapping *Authelia*. We publish two example [systemd] unit files: -* [authelia.service](https://github.com/authelia/authelia/blob/master/authelia.service) -* [authelia@.service](https://github.com/authelia/authelia/blob/master/authelia%40.service) +* {{< github-link path="authelia.service" >}} +* {{< github-link path="authelia@.service" >}} ## Arch Linux diff --git a/docs/content/en/integration/prologue/get-started.md b/docs/content/en/integration/prologue/get-started.md index 78e9d754a..3b5fe67b3 100644 --- a/docs/content/en/integration/prologue/get-started.md +++ b/docs/content/en/integration/prologue/get-started.md @@ -23,24 +23,31 @@ common scenarios however those using more advanced architectures are likely goin help with answering less specific questions about this and it may be possible if provided adequate information more specific questions may be answered. +1. Authelia *__MUST__* be served via the `https` scheme. This is not optional even for testing. This is a deliberate + design decision to improve security directly (by using encrypted communication) and indirectly by reducing complexity. + ### Forwarded Authentication Forwarded Authentication is a simple per-request authorization flow that checks the metadata of a request and a session cookie to determine if a user must be forwarded to the authentication portal. -Due to the fact a cookie is used, it's an intentional design decision that *__ALL__* applications/domains protected via +In addition to the `https` scheme requirement for Authelia itself: + +1. Due to the fact a cookie is used, it's an intentional design decision that *__ALL__* applications/domains protected via this method *__MUST__* use secure schemes (`https` and `wss`) for all of their communication. ### OpenID Connect -Only requires Authelia to be accessible via a secure scheme (`https`). +No additional requirements other than the use of the `https` scheme for Authelia itself exist excluding those mandated +by the relevant specifications. ## Configuration It's important to customize the configuration for *Authelia* in advance of deploying it. The configuration is static and -not configured via web GUI. You can find a -[configuration template](https://github.com/authelia/authelia/blob/master/config.template.yml) on GitHub which can be -used as a basis for configuration. +not configured via web GUI. You can find a configuration template named {{< github-link path="config.template.yml" >}} +on GitHub which can be used as a basis for configuration, alternatively *Authelia* will write this template relevant for +your version the first time it is started. Users should expect that they have to configure elements of this file as part +of initial setup. The important sections to consider in initial configuration are as follows: diff --git a/docs/content/en/overview/authentication/push-notification/index.md b/docs/content/en/overview/authentication/push-notification/index.md index c7e5ba725..bc6013c45 100644 --- a/docs/content/en/overview/authentication/push-notification/index.md +++ b/docs/content/en/overview/authentication/push-notification/index.md @@ -44,7 +44,7 @@ case you have multiple devices available, you will be asked to select your prefe ### Why don't I have access to the *Push Notification* option? It's likely that you have not configured __Authelia__ correctly. Please read this documentation again and be sure you -had a look at [config.template.yml](https://github.com/authelia/authelia/blob/master/config.template.yml) and +had a look at {{< github-link path="config.template.yml" >}} and [configuration documentation](../../../configuration/second-factor/duo.md). [Duo]: https://duo.com/ diff --git a/docs/layouts/shortcodes/github-link.html b/docs/layouts/shortcodes/github-link.html new file mode 100644 index 000000000..2f399ac4a --- /dev/null +++ b/docs/layouts/shortcodes/github-link.html @@ -0,0 +1,17 @@ +{{- $repo := "authelia/authelia" }}{{ with .Get "repo" }}{{ $repo = . }}{{ end }} +{{- $branch := printf "v%s" .Site.Data.misc.latest }}{{ with .Get "branch" }}{{ $branch = . }}{{ end }} +{{- $path := "" }}{{ with .Get "path" }}{{ $path = . }}{{ end }} +{{- $link := printf "https://github.com/%s/blob/%s/%s" $repo $branch (urlquery $path) }} +{{- $name := "" }} +{{- with .Get "name" }} +{{- $name = . }} +{{- else }} +{{- if (eq $repo "authelia/authelia") }} +{{- $name = $path }} +{{- else }} +{{- $name = printf "https://github.com/%s/blob/%s/%s" $repo $branch $path }} +{{- end }} +{{- end }} +{{- "" -}} +{{ $name }} +{{- "" -}}