tubearchivist/docs
1
0
Fork 0
mirror of https://github.com/tubearchivist/docs.git synced 2025-06-15 16:01:09 +00:00
Code Issues Packages Projects Releases Wiki Activity

LDAP multi-provider and TA_LOGIN_AUTH_MODE docs (#62)

Browse Source 
* feat: Add TA_LOGIN_AUTH_MODE configuration and LDAP documentation updates

* TA_LOGIN_AUTH_MODE settings are documented with instructions for adding privileges to new LDAP users
This commit is contained in:
joshrivers 2025-06-07 22:05:32 -07:00 committed by GitHub
parent 89337a5857
commit 3509e24d1f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 62 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
mkdocs/docs/configuration/forward-auth.md
View File

@ -6,15 +6,16 @@ Check the documentation of your auth proxy and your reverse proxy on how to corr
Warning:
If you've successfully authenticated using this method, you will not have administrative rights to the Dashboard. To fix this, you need to comment out the three environment variables, restart the instance, log in with the local account, and grant administrative rights to the automatically added user in the user management interface, which is located at https://youriporfqdn.local/settings/user/.After that, uncomment the previously commented variables, restart your instance again, you should now have administrative right on your next authentication.
If you've successfully authenticated using this method, you will not have administrative rights to the Dashboard. To fix this, you need to comment out the three environment variables, restart the instance, log in with the local account, and grant administrative rights to the automatically added user in the user management interface, which is located at `https://youriporfqdn.local/settings/user/`. After that, uncomment the previously commented variables, restart your instance again, you should now have administrative right on your next authentication.
Note that this automatically creates new users in the database if they do not already exist.
| Environment Variable | Example | Description |
| :------------------- | :------ | :---------- |
| `TA_ENABLE_AUTH_PROXY` | `true` | Set to anything besides empty string to use forward proxy authentication. |
| `TA_AUTH_PROXY_USERNAME_HEADER` | `HTTP_REMOTE_USER` | The name of the request header that the auth proxy passes to the proxied application (**Tube Archivist** in this case), so that the application can identify the user. Check the documentation of your auth proxy to get this information.[^1][^2] |
| `TA_AUTH_PROXY_LOGOUT_URL` | | The URL that **Tube Archivist** should redirect to after a logout. By default, the logout redirects to the login URL, which means the user will be automatically authenticated again. Instead, you might want to configure the logout URL of the auth proxy here. |
| Environment Variable | Default | Example | Description |
| :-------------------- | :-------- | :-------- | :------------ |
| `TA_LOGIN_AUTH_MODE` | `single` | `forwardauth` | Selects authentication backends. See potential values below. Overrides `TA_LDAP`/`TA_ENABLE_AUTH_PROXY`. |
| `TA_ENABLE_AUTH_PROXY` | `null` | `true` | *deprecated* (see below) Set to anything besides empty string to use forward proxy authentication. |
| `TA_AUTH_PROXY_USERNAME_HEADER`| `null` | `HTTP_REMOTE_USER` | The name of the request header that the auth proxy passes to the proxied application (**Tube Archivist** in this case), so that the application can identify the user. Check the documentation of your auth proxy to get this information.[^1][^2] |
| `TA_AUTH_PROXY_LOGOUT_URL` | `null` | | The URL that **Tube Archivist** should redirect to after a logout. By default, the logout redirects to the login URL, which means the user will be automatically authenticated again. Instead, you might want to configure the logout URL of the auth proxy here. |
[^1]:
The request headers are rewritten within **Tube Archivist**: all HTTP headers are prefixed with `HTTP_`, all letters are in uppercase, and dashes are replaced with underscores. For example, for Authelia, which passes the `Remote-User` HTTP header, the `TA_AUTH_PROXY_USERNAME_HEADER` needs to be configured as `HTTP_REMOTE_USER`.
@ -36,4 +37,20 @@ Note that this automatically creates new users in the database if they do not al
# auth_request_set $authentik_username $upstream_http_x_authentik_username;
# proxy_set_header X-Authentik-Username $authentik_username;
## Auth Login Modes
| Value | Behavior |
| :------------ | :------- |
| `single` | backwards-compatibility mode, uses a single auth backend based on deprecated flags |
| `local` | use only local Django database backend for user authentication |
| `ldap` | use only ldap remote backend for user authentication |
| `forwardauth` | use only forward auth backend |
| `ldap_local` | use ldap remote and local Django database backends together |
If the value of `TA_LOGIN_AUTH_MODE` is empty or set to `single` the existing flags (`TA_LDAP`/`TA_ENABLE_AUTH_PROXY`) select the backend, or the local Django backend is used. Eventually these flags should be removed and only `TA_LOGIN_AUTH_MODE` should be used for selection, but this change currently will not impact any existing deployments.
Using `local` overrides the other flags (`TA_LDAP`/`TA_ENABLE_AUTH_PROXY`) and uses only the local database backend for users and groups.
Set `forwardauth` to enable only forward auth / reverse proxy authentication.
See [LDAP](ldap.md) for information on the LDAP settings.

40
mkdocs/docs/configuration/ldap.md
View File

@ -2,7 +2,8 @@ You can enable and configure LDAP with the following environment variables:
| Environment Variable | Default | Example | Description |
| :-------------------- | :-------- | :-------- | :------------ |
| `TA_LDAP` | `false` | `true` | Set to anything besides empty string to use LDAP authentication **instead** of local user authentication. |
| `TA_LOGIN_AUTH_MODE` | `single` | `ldap_local` | Selects authentication backends. See potential values below. Overrides `TA_LDAP`/`TA_ENABLE_AUTH_PROXY`. |
| `TA_LDAP` | `false` | `true` | *deprecated* (see below) Set to anything besides empty string to use LDAP authentication **instead** of local user authentication. |
| `TA_LDAP_SERVER_URI` | `null` | `ldap://ldap-server:389` | Set to the uri of your LDAP server. |
| `TA_LDAP_DISABLE_CERT_CHECK` | `null` | `true` | Set to anything besides empty string to disable certificate checking when connecting over LDAPS. |
| `TA_LDAP_BIND_DN` | `null` | `uid=search-user,ou=users,dc=your-server` | DN of the user that is able to perform searches on your LDAP account. |
@ -14,4 +15,39 @@ You can enable and configure LDAP with the following environment variables:
| `TA_LDAP_USER_BASE` | `null` | `ou=users,dc=your-server` | Search base for user filter. |
| `TA_LDAP_USER_FILTER` | `null` | `(objectClass=user)` | Filter for valid users. Login usernames are matched using the attribute specified in `TA_LDAP_USER_ATTR_MAP_USERNAME` and should not be specified in this filter. |
While LDAP authentication is enabled, the django-managed passwords (e.g. the password defined in TA_PASSWORD), will not allow you to login. Only the LDAP server is used for authentication.
## Auth Login Modes
| Value | Behavior |
| :------------ | :------- |
| `single` | backwards-compatibility mode, uses a single auth backend based on deprecated flags |
| `local` | use only local Django database backend for user authentication |
| `ldap` | use only ldap remote backend for user authentication |
| `forwardauth` | use only forward auth backend |
| `ldap_local` | use ldap remote and local Django database backends together |
If the value of `TA_LOGIN_AUTH_MODE` is empty or set to `single` the existing flags (`TA_LDAP`/`TA_ENABLE_AUTH_PROXY`) select the backend, or the local Django backend is used. Eventually these flags should be removed and only `TA_LOGIN_AUTH_MODE` should be used for selection, but this change currently will not impact any existing deployments.
Using `local` overrides the other flags (`TA_LDAP`/`TA_ENABLE_AUTH_PROXY`) and uses only the local database backend for users and groups.
Most LDAP users should probably use the new `ldap_local` mode, which allows LDAP users to login, but also allows logging in as any locally defined user, including the one defined as an admin using `TA_USERNAME` and `TA_PASSWORD`. Having access to this admin user makes it much easier to promote LDAP logins to staff or superuser roles using the user admin screens.
For installations which require secure enforcement of LDAP-only credentials, use the `ldap`-only value after properly configuring one or more administrator users.
### Lack of privileges on new accounts
LDAP modes automatically create new users in the database if they do not already exist.
If those accounts are successfully authenticated using this method, they will not have administrative rights to the Dashboard (including ability to add downloads). To fix this, the preferred method is to switch to `ldap_local` and add privileges as described in the next section.
### LDAP + Local Considerations
- When using `ldap_local` mode:
- Users can log in with credentials from either system
- Shared usernames can use either password, so weak passwords in either store can be compromising
- Local database accounts can be created to manage LDAP user privileges
Hardening Workflow:
1. Use `ldap_local` during initial setup
2. Login as LDAP user(s) to initialize the local database with their username
3. Login as local admin user and assign privileges to the automatically added LDAP user in the user management interface, which is located at `https://youriporfqdn.local/settings/user/`
4. Switch to `ldap` mode for production