---
title: Custom authentication
sidebar_position: 40
---
:::warning
Since LibreTime v3.0.0-alpha.13, this documentation is out of date, as it relies on the Apache2 web server and the default web server installed by LibreTime is now NGINX.
:::
## Setup FreeIPA authentication
You can configure LibreTime to delegate all authentication to a FreeIPA server.
This allows you users to use their existing FreeIPA credentials. For this to
work you need to configure Apache to use `mod_authnz_pam` and `mod_intercept_form_submit`.
### Apache configuration
After installing the needed modules you can set up Apache to intercept form logins and
check them against pam.
```apacheconf
InterceptFormPAMService http-libretime
InterceptFormLogin username
InterceptFormPassword password
InterceptFormLoginSkip admin
InterceptFormPasswordRedact on
InterceptFormLoginRealms INT.RABE.CH
Require pam-account http-libretime
Require pam-account http-libretime
Require all granted
Require expr %{REQUEST_URI} =~ /(index.php|login|favicon.ico|js|css|locale)/
Require all granted
```
### PAM configuration
The above configuration expects a PAM configuration for the `http-libretime` service.
To configure this you need to create the file `/etc/pam.d/http-libretime` with the following contents.
```
auth required pam_sss.so
account required pam_sss.so
```
### LDAP configuration
LibreTime needs direct access to LDAP so it can fetch additional information. It does so with
a [system account](https://www.freeipa.org/page/HowTo/LDAP#System_Accounts) that you need to
set up beforehand.
You can configure everything pertaining to how LibreTime accesses LDAP in
`/etc/libretime/config.yml`. The default file has the following values you need to change.
```yml
#
# ----------------------------------------------------------------------
# L D A P
# ----------------------------------------------------------------------
#
# hostname: Hostname of LDAP server
#
# binddn: Complete DN of user used to bind to LDAP
#
# password: Password for binddn user
#
# account_domain: Domain part of username
#
# basedn: base search DN
#
# filter_field: Name of the uid field for searching
# Usually uid, may be cn
#
# groupmap_*: Map LibreTime user types to LDAP groups
# Lets LibreTime assign user types based on the
# group a given user is in.
#
ldap:
hostname: ldap.example.org
binddn: "uid=libretime,cn=sysaccounts,cn=etc,dc=int,dc=example,dc=org"
password: hackme
account_domain: INT.EXAMPLE.ORG
basedn: "cn=users,cn=accounts,dc=int,dc=example,dc=org"
filter_field: uid
groupmap_guest: "cn=guest,cn=groups,cn=accounts,dc=int,dc=example,dc=org"
groupmap_host: "cn=host,cn=groups,cn=accounts,dc=int,dc=example,dc=org"
groupmap_program_manager: "cn=program_manager,cn=groups,cn=accounts,dc=int,dc=example,dc=org"
groupmap_admin: "cn=admins,cn=groups,cn=accounts,dc=int,dc=example,dc=org"
groupmap_superadmin: "cn=superadmin,cn=groups,cn=accounts,dc=int,dc=example,dc=org"
```
### Enable FreeIPA authentication
After everything is set up properly you can enable FreeIPA auth in `config.yml`:
```yml
general:
auth: LibreTime_Auth_Adaptor_FreeIpa
```
You should now be able to use your FreeIPA credentials to log in to LibreTime.
## Setup Header Authentication
If you have an SSO system that supports trusted SSO header authentication such as [Authelia](https://www.authelia.com/),
you can configure LibreTime to login users based on those trusted headers.
This allows users to only need to log in once on the SSO system and not need to log in again. It also allows LibreTime
to indirectly support other authentication mechanisms such as OAuth2.
This ONLY affects Legacy/Legacy API auth and does NOT affect API V2 auth.
### Configure Headers
LibreTime needs to know what headers are sent, and what information is available to it. You can also
setup a predefined group mapping so users are automatically granted the desired permissions.
This configuration is in `/etc/libretime/config.yml`. The following is an example configuration for an SSO service
that does the following:
- Sends the username in the `Remote-User` HTTP header.
- Sends the email in the `Remote-Email` HTTP header.
- Sends the name in the `Remote-Name` HTTP header. Example `John Doe`
- Sends the comma delimited groups in the `Remote-Groups` HTTP header. Example `group 1,lt-admin,group2`
- Has an IP of `10.0.0.34` (not required). When not provided it is not checked.
- Users with the `lt-host` group should get host privileges.
- Users with the `lt-admin` group should get admin privileges.
- Users with the `lt-pm` group should get program manager privileges.
- Users with the `lt-superadmin` group should get super admin privileges.
- All other users should get guest privileges.
```yml
header_auth:
user_header: Remote-User # This is the default and could be omitted
groups_header: Remote-Groups # This is the default and could be omitted
email_header: Remote-Email # This is the default and could be omitted
name_header: Remote-Name # This is the default and could be omitted
proxy_ip: 10.0.0.34
group_map:
host: lt-host
program_manager: lt-pm
admin: lt-admin
superadmin: lt-superadmin
```
If the `user_header` is not found in the request, users will be kicked to the login page
with a message that their username/password is invalid and will not be able to log in. When `proxy_ip` is provided
it will check that the request is coming from the correct proxy before doing the login. This prevents users who have
internal network access from being able to login as whoever they want in LibreTime.
::: warning
If `proxy_ip` is not provided any user on the internal network can log in as any user in LibreTime.
:::
### Enable Header authentication
After everything is set up properly you can enable header auth in `config.yml`:
```yml
general:
auth: LibreTime_Auth_Adaptor_Header
```
You should now be automatically logged into LibreTime when you click the `Login` button.