docs(authelia): authelia guide updates (#29702)
**Description** Updates authelia guides with yaml ⚒️ Fixes # **⚙️ Type of change** - [ ] ⚙️ Feature/App addition - [ ] 🪛 Bugfix - [ ] ⚠️ Breaking change (fix or feature that would cause existing functionality to not work as expected) - [ ] 🔃 Refactor of current code **🧪 How Has This Been Tested?** **📃 Notes:** **✔️ Checklist:** - [ ] ⚖️ My code follows the style guidelines of this project - [ ] 👀 I have performed a self-review of my own code - [ ] #️⃣ I have commented my code, particularly in hard-to-understand areas - [ ] 📄 I have made corresponding changes to the documentation - [ ] ⚠️ My changes generate no new warnings - [ ] 🧪 I have added tests to this description that prove my fix is effective or that my feature works - [ ] ⬆️ I increased versions for any altered app according to semantic versioning - [ ] I made sure the title starts with `feat(chart-name):`, `fix(chart-name):` or `chore(chart-name):` **➕ App addition** If this PR is an app addition please make sure you have done the following. - [ ] 🖼️ I have added an icon in the Chart's root directory called `icon.png` --- _Please don't blindly check all the boxes. Read them and only check those that apply. Those checkboxes are there for the reviewer to see what is this all about and the status of this PR with a quick glance._
This commit is contained in:
kqmaverick
@@ -2,113 +2,143 @@
|
||||
title: Authelia + LLDAP + Traefik ForwardAuth Setup guide
|
||||
---
|
||||
|
||||
This quick guide should take you through the steps necessary to setup `Authelia` as your `forwardAuth` for `Traefik`. We'll be using `LLDAP` as the backend for `Authelia` since it's lightweight and simple enough for most users. A more complete video is available on our YouTube Channel.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Traefik installed (enable the `premium train`)
|
||||
- Clusterissuer for certificates
|
||||
- CloudnativePG operator (enable the `system train`)
|
||||
This quick guide should take you through the steps necessary to setup `Authelia` as your `forwardAuth` for `Traefik`. We'll be using `LLDAP` as the backend for `Authelia` since it's lightweight and simple enough for most users.
|
||||
|
||||
## Setup LLDAP
|
||||
|
||||
:::caution
|
||||
|
||||
LLDAP is a `Stable` train chart and therefore isn't supported at the same level as the charts in the `premium` train (Authelia and Traefik).
|
||||
LLDAP is a `stable` train chart and therefore isn't supported at the same level as the charts in the `premium` train (Authelia and Traefik).
|
||||
|
||||
:::
|
||||
|
||||
- Follow the easy steps included in the [Installation Notes](/charts/stable/lldap/installation-notes) for [LLDAP](/charts/stable/lldap/). Change `dc=example,dc=com` to your domain, i.e. `dc=MYDOMAIN,dc=net` and then change your password. Also, make sure you have the `system` train enabled and `CloudnativePG` operator installed, since you'll need it for `LLDAP` and `Authelia`.
|
||||
- Follow the easy steps included in the [Installation Notes](/charts/stable/lldap/installation-notes) for [LLDAP](/charts/stable/lldap/). Change `dc=example,dc=com` to your domain, i.e. `dc=MYDOMAIN,dc=net` and then change your password.
|
||||
|
||||
|
||||
- Once in `LLDAP`, create a user inside the `lldap_password_manager` group and change your default `admin` password. That `lldap_password_manager` user will be used to bind to `Authelia`. Here I've created a user called `manager`, but you can use anything
|
||||
|
||||
- Ensure you've set the services to `ClusterIP` since you'll be using ingress
|
||||
|
||||
- Once in `LLDAP`, create a user inside the `lldap_password_manager` group and change your default `admin` password. That `lldap_password_manager` user will be used to bind to `Authelia`. Here I've created a user called `Steven`, but you can use anything
|
||||
|
||||
- Create an `admin` group and add `Steven` to it. We will allow users of this group to access the site with Authelia later in the guide.
|
||||
- Create an `admin` group and add `User` to it. We will allow users of this group to access the site with Authelia later in the guide.
|
||||
|
||||
## Setup Authelia
|
||||
|
||||
- The setup for Authelia is very specific and the logs won't tell you where you've messed up, but there's precise steps used to integrate `LLDAP` into `Authelia`. The info comes from the [LLDAP Authelia Docs](/charts/stable/lldap/authelia) and the upstream repo.
|
||||
- The setup for Authelia is very specific and the logs won't tell you where you've messed up, but there's precise steps used to integrate `LLDAP` into `Authelia`.
|
||||
|
||||
### App Configuration
|
||||
|
||||
- Domain: `mydomain.com` - Your domain without https://
|
||||
- Default Redirection URL: `https://auth.mydomain.com` - Can be anything, but we'll stick to auth.mydomain.com. As well, this will be the ingress URL for `Authelia`.
|
||||
|
||||
### LDAP Backend Configuration
|
||||
|
||||
Click `Enable` then ensure everything is as below or you won't be able to connect to the LLDAP backend:
|
||||
|
||||
- Implementation: `Custom` (that's the default)
|
||||
- URL: `ldap://lldap-ldap.ix-lldap.svc.cluster.local:3890`
|
||||
- Connection Timeout: 5s
|
||||
- Start TLS: (Not necessary)
|
||||
- TLS Settings: (Not necessary)
|
||||
- Server Name: Leave blank
|
||||
- Skip Certificate Verification: Leave unchecked
|
||||
- Minimum TLS version: `TLS1.2`
|
||||
- Base DN: `DC=mydomain,DC=com`
|
||||
- Username Attribute: `uid`
|
||||
- Additional Users DN: `ou=people`
|
||||
- Users Filter: `(&(|({username_attribute}={input})({mail_attribute}={input}))(objectClass=person))`
|
||||
- Additional Groups DN: `ou=groups`
|
||||
- Groups Filter: `(member={dn})`
|
||||
- Group name Attribute:`cn`
|
||||
- Mail Attribute:`mail`
|
||||
- Display Name Attribute:`displayName`
|
||||
- Admin User: `uid=Steven,ou=people,dc=mydomain,dc=com` - Notice the uid=Steven, most of the time people use admin and a generated password
|
||||
- Password: `RANDOMPASSWORD`
|
||||
|
||||
#### SMTP Configuration
|
||||
|
||||
Check your mail provider for this, generally Gmail gives you an app specific password for your email account and uses `smtp.gmail.com` and port `587`.
|
||||
|
||||
### Access Control Configuration
|
||||
|
||||
This section is to set rules to connect to `Authelia` and defines which users can go where. This is a basic general rule where users of the `admin` group (Steven) can access all of the site using a wildcard.
|
||||
|
||||
Set the default `deny`. Then click `Add` next to `Rules` to get the screen below.
|
||||
|
||||
|
||||
|
||||
- Add your `Domain` and a `Wildcard` for your subdomains
|
||||
- Set policy to `one_factor` or `two_factor`, up to you
|
||||
- Click `Add Subject` and add a subject of `group:admin` since `Steven` is part of that group.
|
||||
```yaml
|
||||
// values.yaml
|
||||
# your domain
|
||||
domain: example.com
|
||||
# autehlia ingress url
|
||||
default_redirection_url: https://auth.example.com
|
||||
authentication_backend:
|
||||
# lldap setup
|
||||
ldap:
|
||||
enabled: true
|
||||
implementation: custom
|
||||
# if name is not lldap update as needed
|
||||
url: ldap://lldap-ldap.lldap.svc.cluster.local:3890
|
||||
# replace with your domain
|
||||
base_dn: DC=example,DC=com
|
||||
username_attribute: uid
|
||||
additional_users_dn: ou=people
|
||||
users_filter: (&(|({username_attribute}={input})({mail_attribute}={input}))(objectClass=person))
|
||||
additional_groups_dn: ou=groups
|
||||
groups_filter: (member={dn})
|
||||
group_name_attribute: cn
|
||||
mail_attribute: mail
|
||||
display_name_attribute: displayName
|
||||
# user with lldap_password_manager group
|
||||
user: uid=manager,ou=people,dc=example,dc=com
|
||||
# above user password in plain text
|
||||
plain_password: somepassword
|
||||
file:
|
||||
enabled: false
|
||||
notifier:
|
||||
# smtp setup (example is gmail)
|
||||
smtp:
|
||||
enabled: true
|
||||
host: smtp.gmail.com
|
||||
port: 587
|
||||
# gmail email address (username)
|
||||
username: email@gmail.com
|
||||
# use a google app password if using gmail
|
||||
plain_password: somepassword
|
||||
# email address to show as sender
|
||||
sender: no-reply@example.com
|
||||
filesystem:
|
||||
enabled: false
|
||||
access_control:
|
||||
rules:
|
||||
# basic rule for one factor (username/password) login for users in the lldap_admin group
|
||||
- domain:
|
||||
- "*.example.com"
|
||||
- example.com
|
||||
policy: one_factor
|
||||
subject: "group:lldap_admin"
|
||||
```
|
||||
|
||||
Please see [Authelia Rules](./authelia-rules) for more advanced rules.
|
||||
|
||||
#### Setup Authelia Ingress
|
||||
### Setup Authelia Ingress
|
||||
|
||||
- Make sure you're using the same domain as the `Default Redirection URL` above, so for me that's `auth.mydomain.com`
|
||||
|
||||
|
||||
```yaml
|
||||
// values.yaml
|
||||
ingress:
|
||||
main:
|
||||
enabled: true
|
||||
integrations:
|
||||
traefik:
|
||||
enabled: true
|
||||
certManager:
|
||||
enabled: true
|
||||
certificateIssuer: domain-0-le-prod
|
||||
hosts:
|
||||
- host: auth.example.com
|
||||
```
|
||||
|
||||
## Traefik ForwardAuth Setup
|
||||
|
||||
- This part is straight forward as long as you have a working `Traefik` install, please see our [How-To](/charts/premium/traefik/how-to) if you need more info on getting that running.
|
||||
|
||||
- Scroll down to `forwardAuth` and click `Add`
|
||||
- The following is added to `Traefik` `values.yaml`,
|
||||
|
||||
|
||||
|
||||
- Name your `forwardauth` something you'll remember, since that's the middleware you'll add to your ingress going forward. Most people use `auth`
|
||||
- Address: `http://authelia.ix-authelia.svc.cluster.local:9091/api/verify?rd=https://auth.mydomain.com/` and replace the last part based on `mydomain.com`, and if you've changed ports/names you can get that from [`HeavyScript`](/
|
||||
- Check `trustForwardHeader`
|
||||
- Add the following `authResponseHeaders` (press `Add` 4 times)
|
||||
- `Remote-User`
|
||||
- `Remote-Groups`
|
||||
- `Remote-Name`
|
||||
- `Remote-Email`
|
||||
```yaml
|
||||
// values.yaml
|
||||
middlewares:
|
||||
forwardAuth:
|
||||
- name: auth
|
||||
address: http://authelia.authelia.svc.cluster.local:9091/api/verify?rd=https://auth.example.com/
|
||||
authResponseHeaders:
|
||||
- Remote-User
|
||||
- Remote-Group
|
||||
- Remote-Name
|
||||
- Remote-Email
|
||||
trustForwardHeader: true
|
||||
```
|
||||
|
||||
### Adding the forwardauth to your Apps
|
||||
|
||||
The last step is adding the `forwardauth` along with the standard `ingress` settings for your app, for more info on setting ingress see the [ClusterIssuer Guide](/charts/premium/clusterissuer/how-to). What changes versus a standard setup is the `Traefik Middlewares` section, where you must add your `forwardauth` to the section.
|
||||
The last step is adding the `forwardauth` along with the standard `ingress` settings for your app, for more info on setting ingress see the [ClusterIssuer Guide](/charts/premium/clusterissuer/how-to).
|
||||
|
||||
- In this example we use the same name as above, or `auth`. Click `Add` to the `Traefik Middlewares` section, and enter your `forwardauth` name.
|
||||
- In this example we use the same name as above, or `auth`.
|
||||
|
||||
|
||||
```yaml
|
||||
// values.yaml
|
||||
ingress:
|
||||
main:
|
||||
enabled: true
|
||||
integrations:
|
||||
traefik:
|
||||
enabled: true
|
||||
middlewares:
|
||||
- name: auth
|
||||
namespace: traefik
|
||||
certManager:
|
||||
enabled: true
|
||||
certificateIssuer: domain-0-le-prod
|
||||
hosts:
|
||||
- host: radarr.example.com
|
||||
```
|
||||
|
||||
### References
|
||||
|
||||
|
||||
@@ -26,116 +26,63 @@ Members of the `user` group will only have access to a select set of apps you ch
|
||||
|
||||
This rule will bypass Authelia for API level access in most apps. This should always be your first rule.
|
||||
|
||||
Domain: `*.domain.tld`
|
||||
|
||||
Policy: `bypass`
|
||||
|
||||
Subject: `Not Used (Do Not Add)`
|
||||
|
||||
Networks: `Not Used (Do Not Add)`
|
||||
|
||||
Resources:
|
||||
|
||||
- `^/api([/?].*)?$`
|
||||
- `^/identity.*$`
|
||||
- `^/triggers.*$`
|
||||
- `^/meshagents.*$`
|
||||
- `^/meshsettings.*$`
|
||||
- `^/agent.*$`
|
||||
- `^/control.*$`
|
||||
- `^/meshrelay.*$`
|
||||
- `^/wl.*$`
|
||||
|
||||
|
||||
```yaml
|
||||
// values.yaml
|
||||
- domain: "*.example.com"
|
||||
policy: bypass
|
||||
resources:
|
||||
- "^/api([/?].*)?$"
|
||||
- "^/api([/?].*)?$"
|
||||
- "^/identity.*$"
|
||||
- "^/triggers.*$"
|
||||
- "^/meshagents.*$"
|
||||
- "^/meshsettings.*$"
|
||||
- "^/agent.*$"
|
||||
- "^/control.*$"
|
||||
- "^/meshrelay.*$"
|
||||
- "^/wl.*$"
|
||||
```
|
||||
|
||||
## Vaultwarden
|
||||
|
||||
These rules will protect the Vaultwarden admin page with Authelia but bypass when accessing the web vault. The order of these rules is critical or the admin page will not be protected.
|
||||
This rule will allow users of the `admin` group to access the Vaultwarden admin page and bypass Authelia when accessing the webportal as auth is already provided by vaultwarden.
|
||||
|
||||
### Rule 1
|
||||
|
||||
This rule will allow users of the `admin` group to access the Vaultwarden admin page.
|
||||
|
||||
Domain: `vaultwarden.domain.tld`
|
||||
|
||||
Policy: `two_factor`
|
||||
|
||||
Subject: `group:admin`
|
||||
|
||||
Networks: `Not Used (Do Not Add)`
|
||||
|
||||
Resources: `^*/admin.*$`
|
||||
|
||||
|
||||
|
||||
### Rule 2
|
||||
|
||||
This rule will prevent users not in the `admin` group to access the Vaultwarden admin page.
|
||||
This is necessary even if the your default policy is set to `deny` because of the `bypass` rule below.
|
||||
|
||||
Domain: `vaultwarden.domain.tld`
|
||||
|
||||
Policy: `deny`
|
||||
|
||||
Subject: `Not Used (Do Not Add)`
|
||||
|
||||
Networks: `Not Used (Do Not Add)`
|
||||
|
||||
Resources: `^*/admin.*$`
|
||||
|
||||
|
||||
|
||||
### Rule 3
|
||||
|
||||
This rule will bypass Authelia when accessing the webportal as auth is already provided by vaultwarden.
|
||||
|
||||
Domain: `vaultwarden.domain.tld`
|
||||
|
||||
Policy: `bypass`
|
||||
|
||||
Subject: `Not Used (Do Not Add)`
|
||||
|
||||
Networks: `Not Used (Do Not Add)`
|
||||
|
||||
Resources: `Not Used (Do Not Add)`
|
||||
|
||||
|
||||
```yaml
|
||||
// values.yaml
|
||||
- domain: "vaultwarden.example.com"
|
||||
policy: two_factor
|
||||
subject: group:admin
|
||||
resources: "^*/admin.*$"
|
||||
- domain: "vaultwarden.example.com"
|
||||
policy: deny
|
||||
resources: "^*/admin.*$"
|
||||
- domain: "vaultwarden.example.com"
|
||||
policy: bypass
|
||||
```
|
||||
|
||||
## User Rule
|
||||
|
||||
This rule will allow users in the `user` group access to only the specified applications.
|
||||
|
||||
Domain:
|
||||
|
||||
- `jellyfin.domain.tld`
|
||||
- `nextcloud.domain.tld`
|
||||
- `whateveryouwant.domain.tld`
|
||||
|
||||
Policy: `two_factor`
|
||||
|
||||
Subject: `group:user`
|
||||
|
||||
Networks: `Not Used (Do Not Add)`
|
||||
|
||||
Resources: `Not Used (Do Not Add)`
|
||||
|
||||
|
||||
```yaml
|
||||
// values.yaml
|
||||
- domain:
|
||||
- "jellyfin.example.com"
|
||||
- "nextcloud.example.com"
|
||||
- "whateveryouwant.example.com"
|
||||
policy: two_factor
|
||||
subject: group:user
|
||||
```
|
||||
|
||||
## Catch All Rule
|
||||
|
||||
This rule will give access to everything to users of the `admin` group.
|
||||
|
||||
Domain:
|
||||
|
||||
- `domain.tld`
|
||||
- `*.domain.tld`
|
||||
|
||||
Policy: `two_factor`
|
||||
|
||||
Subject: `group:admin`
|
||||
|
||||
Networks: `Not Used (Do Not Add)`
|
||||
|
||||
Resources: `Not Used (Do Not Add)`
|
||||
|
||||
|
||||
```yaml
|
||||
// values.yaml
|
||||
- domain:
|
||||
- "example.com"
|
||||
- "*.example.com"
|
||||
policy: two_factor
|
||||
subject: group:admin
|
||||
```
|
||||
|
||||
@@ -1,58 +0,0 @@
|
||||
---
|
||||
title: Authelia Setup
|
||||
---
|
||||
|
||||
Authelia which is available in the premium train can act as the authentication provider for your apps and services either through OAuth or forward authentication. LLDAP can be used to manage your Authelia users and groups. To enable this as an option follow the steps outlined below. References to the specific questions as they appear in the TrueNAS SCALE UI are included in the guide and highlighted along with the answers you should use. Authelia is the recommended authentication provider for TrueCharts however you can use any other provider you wish for Authentik is available in the Stable train.
|
||||
|
||||
This guide has been written as LLDAP has specific requirements for the LDAP setup of Authelia. If you are using another LDAP provider you will need to follow the setup instructions for that provider.
|
||||
|
||||
> **Disclaimer:** This guide only covers the LDAP setup of Authelia. Refer to other guides for the remaining setup of Authelia.
|
||||
|
||||
## Setup instructions
|
||||
|
||||
1. Tick the box for `LDAP backend configuration` a further set of questions will then appear.
|
||||
2. The dropdown `Implementation` should be set as `custom`
|
||||
3. URL should be set to internally link back to your LLDAP instance for the default configuration it should look something like this, `ldap://lldap-ldap.ix-lldap.svc.cluster.local:3890`. This will need to be adapted if you have named LLDAP differently or used a different port for LDAP.
|
||||
4. Next, set the `Base DN`. This is one of the configurable options you set when installing LLDAP, which by default is `dc=example,dc=com` and should be adapted to your domain if set.
|
||||
5. The `Username Attribute` should be set to `uid`.
|
||||
6. The `Additional Users DN` should be set to `ou=people`, as this is where all your users are stored.
|
||||
7. The users filter can be set to one of two options depending on whether you want to allow sign-in with a username or both username and email. Both options are outlined below.
|
||||
|
||||
**Username only**
|
||||
|
||||
```shell
|
||||
(&({username_attribute}={input})(objectClass=person))
|
||||
```
|
||||
|
||||
**Username and email**
|
||||
|
||||
```shell
|
||||
(&(|({username_attribute}={input})({mail_attribute}={input}))(objectClass=person))
|
||||
```
|
||||
|
||||
8. The next option that needs setting is `Additional Groups DN`. It must be set to `ou=groups`, as this is where all your groups are stored.
|
||||
9. LLDAP only supports only one filter, which should be set in `Groups Filter` and set to `(member={dn})`.
|
||||
10. The `Group name Attribute` should be set to `cn`.
|
||||
11. The `Mail Attribute` should simply be set to `mail`.
|
||||
12. The `Display Name Attribute` should be set to `displayName`. This is the attribute that Authelia will use to greet users when they log in.
|
||||
13. `Admin user` is the default admin user used when setting up LLDAP initially and is auto-generated for you. The entry you input into this box should look something like the one below. Change `dc=example,dc=com` to match the `Base DN` you set earlier.
|
||||
|
||||
**Admin user**
|
||||
|
||||
```shell
|
||||
uid=admin,ou=people,dc=example,dc=com
|
||||
```
|
||||
|
||||
14. Enter the admin user password into the `Password` field. As stated earlier, **DO NOT** use the default password.
|
||||
|
||||
## References
|
||||
|
||||
The origin material for this guide is available on the [LLDAP Github](https://github.com/lldap/lldap). While further information on Authelia can be found on their [Github](https://github.com/authelia/authelia) and [website](https://www.authelia.com/).
|
||||
|
||||
## Support
|
||||
|
||||
If you have any issues with following this guide, we can be reached using [Discord](https://discord.gg/tVsPTHWTtr) for real-time feedback and support.
|
||||
|
||||
---
|
||||
|
||||
All Rights Reserved - The TrueCharts Project
|
||||
@@ -6,25 +6,37 @@ title: Installation notes
|
||||
|
||||
LLDAP is configured using the default options generated by the application on first run. The exception to this is the 'Base DN for LDAP' option which has been exposed to the user.
|
||||
|
||||
By default, LLDAP will use the following options:
|
||||
|
||||
- Base DN for LDAP: `dc=example,dc=org`
|
||||
- Ldap User DN: `admin`
|
||||
- Ldap User Email: `admin@admin.com`
|
||||
- Ldap User Password: `password`
|
||||
- Public URL:`<https://lldap.example.com>`
|
||||
- LDAP port: `3890`
|
||||
- JWT secret: random (generated on first run)
|
||||
|
||||
- Show SMTP Settings
|
||||
- Enable Password Reset: false
|
||||
- SMTP Server Url: smtp.gmail.com
|
||||
- SMTP Server Port: 587
|
||||
- SMTP Encryption: STARTTLS
|
||||
- SMTP User: email
|
||||
- SMTP Password: password | app password
|
||||
- SMTP From: LLDAP Admin `<sender@gmail.com>`
|
||||
- SMTP Reply To: Do not reply `<noreply@localhost>`
|
||||
```yaml
|
||||
// values.yaml
|
||||
workload:
|
||||
main:
|
||||
podSpec:
|
||||
containers:
|
||||
main:
|
||||
env:
|
||||
# replace with your domain
|
||||
LLDAP_LDAP_BASE_DN: "dc=example,dc=com"
|
||||
# initial lldap admin account
|
||||
LLDAP_LDAP_USER_DN: admin
|
||||
# initial lldap admin email
|
||||
LLDAP_LDAP_USER_EMAIL: email@gmail.com
|
||||
# above user password in plain text
|
||||
LLDAP_LDAP_USER_PASS: somepassword
|
||||
# allow password reset using email
|
||||
LLDAP_SMTP_OPTIONS__ENABLE_PASSWORD_RESET: true
|
||||
# smtp setup (example is gmail)
|
||||
LLDAP_SMTP_OPTIONS__SERVER: smtp.gmail.com
|
||||
LLDAP_SMTP_OPTIONS__PORT: 587
|
||||
LLDAP_SMTP_OPTIONS__SMTP_ENCRYPTION: "STARTTLS"
|
||||
# gmail email address (username)
|
||||
LLDAP_SMTP_OPTIONS__USER: email@gmail.com
|
||||
# use a google app password if using gmail
|
||||
LLDAP_SMTP_OPTIONS__PASSWORD: somepassword
|
||||
# email address to show as sender
|
||||
LLDAP_SMTP_OPTIONS__FROM: "LLDAP Admin <no-reply@example.com>"
|
||||
# email address to show as reply address
|
||||
LLDAP_SMTP_OPTIONS__REPLY_TO: "Do not reply <no-reply@example.com>"
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
Reference in New Issue
Block a user