authelia: Add README

authelia/README.md

@@ -0,0 +1,74 @@
+# Authelia
+
+[Authelia][0] is an open-source authentication and authorization server and
+portal.  It can operate as an OpenID Connect identity provider or as a proxy
+authorization subrequest handler (e.g. for *nginx*).  It supports a built-in
+user database as well as LDAP, and various forms of second-factor
+authentication.
+
+## Installation
+
+```sh
+kubectl apply -k authelia
+```
+
+## Configuration
+
+Authelia is configured by the `configuration.yml` file.  It is stored as a
+Kubernetes ConfigMap and mounted into the Authelia server container.  See the
+[Configuration][1] section of the Authelia documentation for details.
+
+Various secrets are used to secure Authelia.  These are stored as Kubernetes
+Secret resources and mounted into the Authelia server container.  Their
+contents originate from files such as `jwt.secret`, `ldap.password`, etc.
+
+
+### OpenID Connect
+
+For applications that support it, OpenID Connect is usually a better option
+than proxy authorization subrequest.  Each application needs to be defined in
+the `identity_providers.oidc.clients` list.  At minimum, clients need an ID,
+description, and list of redirect URIs.  Additionally, a client must either
+have a defined secret or be marked public.
+
+
+### Proxy Authorization Subrequest
+
+Authellia's original purpose was to support the authorization subrequest
+feature of nginx and other reverse proxy solutions.  When used in this way,
+Authelia can protect for applications that do not have a built-in
+authentication/authorization capabilities.  For each incoming request, the
+proxy makes a subrequest to Authelia, passing along cookies, etc. from the
+original request.  Authelia validates the session and indicates whether or not
+the request is allowed.  If it is allowed, the proxy resumes processing the
+original request, forwarding it to the upstream server.  If it is not allowed,
+the proxy returns a redirect response to the client, instructing the user agent
+to load the Authelia login page.  Authelia then checks the user's credentials,
+optionally enforcing MFA validation (based on the configured [access control
+policy][2]), and creates a new session.  It then redirects the user agent back
+to the resource requested initially.
+
+Enabling the proxy authorization subrequest for applications hosted in
+Kubernetes is very straightforward.  The *ingress-nginx* Ingress controller
+supports configuring it via the `nginx.ingress.kubernetes.io/auth-url`, et al.
+annotations.  Adding authentication to an Ingress resource is therefore as
+simple as adding a few annotations:
+
+```yaml
+metadata:
+  annotations:
+    nginx.ingress.kubernetes.io/auth-method: GET
+    nginx.ingress.kubernetes.io/auth-url: http://authelia.authelia.svc.cluster.local:9091/api/verify
+    nginx.ingress.kubernetes.io/auth-signin: https://auth.pyrocufflink.blue/?rm=$request_method
+    nginx.ingress.kubernetes.io/auth-response-headers: Remote-User,Remote-Name,Remote-Groups,Remote-Email
+    nginx.ingress.kubernetes.io/auth-snippet: |
+      proxy_set_header X-Forwarded-Method $request_method;
+```
+
+Note that the value of the `auth-url` contains the *internal* URL for Authelia,
+while the `auth-signin` value is the *external* URL.
+
+
+[0]: https://www.authelia.com/
+[1]: https://www.authelia.com/configuration/prologue/introduction/
+[2]: https://www.authelia.com/configuration/security/access-control/