# 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/